docs: warn against bash ANSI-C quoting for multiline comment content

[robzolkos]

Summary

Documentation-only change addressing #459, where basecamp comment posted a comment with a stray leading $.

Root cause

Not a CLI bug — a shell quoting issue. The reporter used bash ANSI-C quoting:

basecamp comment 9802493119 $'海报 mockup 方向稿：\n\n<bc-attachment ...>' --in ... --json

$'...' is a bash/zsh extension, not POSIX. Under a POSIX /bin/sh (dash, busybox-ash — the default in most Linux sandboxes and "agent workflow" shells), $'...' is parsed as a literal $ followed by an ordinary single-quoted string. The CLI then faithfully posts exactly what the shell handed it.

The smoking gun is in the issue's own output: the posted HTML contains both the literal $ and literal \n\n (backslash-n, not real newlines). If bash had interpreted $'...', the \n would have become real newlines and the $/quotes consumed. Their survival proves a POSIX sh ran the command.

Why not "fix" it in the CLI

The issue floated stripping the $'...' wrapper inside the CLI. Rejected: $ and ' are legitimate content characters (prices, code, apostrophes), and the app can't know a leading $ was an unintended quote wrapper. Guessing at shell intent would silently corrupt real content.

The safe alternative — stdin via -, bare pipe, and --edit — already exists. This PR just documents it.

Changes

• comments create / comments update help text: warn against $'...' for multiline/non-ASCII content, recommend the stdin (-) pattern.
• skills/basecamp/SKILL.md: same guidance in the content-fields section, extending the existing printf %q quoting advice.

Note

bin/ci currently fails on this branch's base due to a pre-existing, unrelated build breakage in internal/commands/cards.go (the SDK's CardColumns.EnableOnHold/DisableOnHold/SetColor gained a columnID parameter that cards.go hasn't been updated for). It exists on the clean base independent of this change; this PR only touches help-text strings and Markdown (gofmt-clean).

---

Summary by cubic

Warns against using bash ANSI-C quoting $'...' for multiline or non-ASCII comment content, which under POSIX /bin/sh posts a stray $ and keeps \n literally. Updates the basecamp comments create/update help to recommend stdin with -, and adds the same guidance to skills/basecamp/SKILL.md (addresses #459).

^{Written for commit 471fdc7. Summary will update on new commits.}

[Copilot]

Pull request overview

Documents a common shell-quoting pitfall when posting Basecamp comments via the CLI: bash/zsh ANSI‑C quoting ($'...') can be passed through literally under POSIX /bin/sh, resulting in a stray leading $ and literal \n sequences being posted. This updates user-facing guidance to recommend the existing, safer stdin (-) pattern instead of attempting risky content “fixups” in the CLI.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Changes:

• Adds a warning + stdin recommendation to basecamp comments create help text, including an example pipeline.
• Adds a similar warning + stdin recommendation to basecamp comments update help text.
• Updates skills/basecamp/SKILL.md with the same guidance for agent workflows.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
internal/commands/comment.go	Updates CLI help text for comments create/comments update to warn against $'...' under POSIX sh and recommend stdin (-).
skills/basecamp/SKILL.md	Adds the same guidance in the agent skill documentation, with a concrete stdin example.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[cubic-dev-ai]

No issues found across 2 files

_{Re-trigger cubic}