Improve help text, naming, and discoverability

[jeremy]

Summary

• Dock disambiguation: getDockToolID now names the specific flag in ambiguity errors (e.g., "Use --chat to specify") instead of generic "Specify the ID directly"
• Config alias: basecamp config set project <id> works as a friendlier alias for project_id, matching the existing llm → llm_provider pattern
• Dock jargon: project show help text explains what the dock is parenthetically
• campfire → chat: Primary command renamed to chat to match the Basecamp UI; campfire remains as an alias with all removed surface entries acknowledged in .surface-breaking

Breaking surface note

The campfire alias preserves invocation compatibility — basecamp campfire post "hello" still works. However, the public CLI surface changed: --help, --help --agent JSON, basecamp commands, and catalog output now show chat instead of campfire. Tooling that parses help or agent output for the command name will see the rename. This is intentional — the Basecamp UI calls this feature "Chat" — and all affected surface entries are acknowledged in .surface-breaking.

Test plan

• bin/ci passes (unit tests, e2e, surface, skill drift, bare groups, naming, provenance)
• TestGetDockToolID_AmbiguousToolShowsFlagHint — flag name appears in ambiguity hint
• TestConfigSet_ProjectAlias / TestConfigUnset_ProjectAlias — config alias round-trips
• TestChatAliases — alias registered, canonical name is chat
• TestChatAliasShowsChatHelp — basecamp campfire --help shows basecamp chat (canonical)
• e2e: campfire alias --help shows canonical chat help — alias works end-to-end

[cubic-dev-ai]

No issues found across 23 files

[Copilot]

Pull request overview

This PR improves CLI discoverability and compatibility handling by refining dock ambiguity hints, adding a friendlier config key alias, clarifying “dock” terminology in help text, and renaming the primary campfire command to chat while keeping campfire as an alias.

Changes:

• Enhance getDockToolID ambiguity errors to optionally point users at the relevant flag (e.g. --campfire <id>).
• Add basecamp config set project <id> as an alias for project_id.
• Rename the primary command from campfire → chat, updating help text, tests, and surface snapshots, with removals acknowledged in .surface-breaking.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
skills/basecamp/SKILL.md	Updates skill documentation/examples and trigger list to use chat terminology.
internal/commands/surface_test.go	Allows acknowledged breaking removals listed in .surface-breaking to not fail the surface snapshot test.
internal/commands/schedule.go	Updates getDockToolID call site to pass the new flagName parameter.
internal/commands/projects.go	Clarifies “dock” meaning in project show long help text.
internal/commands/messages.go	Passes flag name to getDockToolID so ambiguity hint can mention --message-board.
internal/commands/messageboards.go	Passes flag name to getDockToolID so ambiguity hint can mention --board.
internal/commands/helpers_test.go	Updates existing tests for new getDockToolID signature and adds coverage for ambiguity hint flag naming.
internal/commands/helpers.go	Extends getDockToolID to accept an optional flagName and uses it in ambiguity hints.
internal/commands/forwards.go	Passes flag name to getDockToolID so ambiguity hint can mention --inbox.
internal/commands/files.go	Passes flag name to getDockToolID so ambiguity hint can mention --vault.
internal/commands/doc_contract_test.go	Updates contract test cases to use chat instead of campfire.
internal/commands/config_test.go	Adds tests for the new project alias key behavior in config set/unset.
internal/commands/config.go	Documents and implements project → project_id alias; updates onboarding breadcrumb/help text.
internal/commands/commands.go	Renames command category entry from campfire to chat.
internal/commands/checkins.go	Passes flag name to getDockToolID so ambiguity hint can mention --questionnaire.
internal/commands/campfire_test.go	Adds/updates tests validating chat canonical name and campfire alias behavior.
internal/commands/campfire.go	Renames the command to chat, keeps campfire alias, and updates help/breadcrumb text accordingly.
internal/cli/help_test.go	Updates help tests to reference chat and adds a test ensuring alias help output uses canonical chat.
internal/cli/help.go	Updates curated help categories to include chat instead of campfire.
e2e/errors.bats	Updates end-to-end error tests to use chat command.
e2e/campfire.bats	Updates end-to-end “campfire” suite to exercise chat as canonical + campfire as alias.
.surface-breaking	Records acknowledged breaking surface removals (including removed campfire surface entries).
.surface	Updates the CLI surface snapshot baseline to include chat commands/flags and remove campfire as canonical.

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 16abfc886e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

⚠️ Potential breaking changes detected:

• Added alias 'campfire' for the 'chat' command, which may affect scripts or integrations relying on the exact command name.
• Changed error hints to recommend using '--campfire ' instead of '--chat ' for ambiguous chat tool IDs, potentially affecting scripts parsing errors.
• Updated configuration key aliases to include 'project' mapping to 'project_id', introducing a new alias that could cause confusion or unintended behavior in environments expecting only 'project_id'.
• Modified breadcrumb output for configuration commands from 'basecamp config set project_id ' to 'basecamp config set project ', which may affect scripts parsing output.
• Adjusted wording in error messages and output, such as using 'Use --campfire ' instead of previous hints, which could break error message parsers or scripts relying on the old format.

Review carefully before merging. Consider a major version bump.

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

internal/commands/helpers.go:164

• Ambiguous-tool error message uses fmt.Sprintf("Project has %d %ss", ...), which produces incorrect plurals for some friendlyName values (e.g., "inbox" -> "inboxs"). Consider switching to a non-pluralized form (like "%d %s(s)") or adding an explicit plural form so user-facing errors read correctly.

		return "", &output.Error{
			Code:    output.CodeAmbiguous,
			Message: fmt.Sprintf("Project has %d %ss", len(matches), friendlyName),
			Hint:    hint,

---

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

[Copilot]

Pull request overview

Copilot reviewed 18 out of 19 changed files in this pull request and generated 4 comments.

---

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

[Copilot]

Pull request overview

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

---

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

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (1)

internal/commands/helpers.go:180

• The ambiguous-tool error message formats the plural as friendlyName + "s" ("Project has %d %ss"), which produces incorrect plurals for some names (e.g., inbox → "inboxs" from getInboxID). Consider changing the wording to avoid manual pluralization or adding a small pluralization helper/override so cases like "inboxes" read correctly.

		hint := fmt.Sprintf("%s Available:\n  - %s", instruction, strings.Join(toolList, "\n  - "))
		return "", &output.Error{
			Code:    output.CodeAmbiguous,
			Message: fmt.Sprintf("Project has %d %ss", len(enabled), friendlyName),
			Hint:    hint,

---

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