fix: help lists only applicable flags, groups question commands, states exit codes

[spark2ignite]

Summary

Three help-surface fixes found by an unauthenticated AI agent driving the built binary with no docs.

1. Per-command --help lists only the flags that can act on the command. Every dci persistent flag used to render under every command, burying the command's own flags under ~30 inert ones (invite-user --help showed --chart, --pivot, --for-reimport, --all, …). New chapter help_flags.go classifies the flags by the signals the pipeline already keys on: report/query result shape (chart, pivot, flat, rollup, max-rows, rows, include-empty-rows, drop-unlabeled-rows, heatmap), the file-shaped exports (for-reimport; output-file inline there), page-token paging (--all), list responses (--search), the list-insights view (--include-dismissed), and a resolvable positional argument (--id/--name). The agent-contract flags (--output, --fields, --exclude, --full, --dry-run, --yes, --agent, --no-agent, -D) stay inline everywhere; the table flags that apply to every command fold into one Output flags (… add --help-full to list them) line; --help-full lists every flag. Flags are hidden only while help renders and restored afterwards, so every flag is still accepted everywhere and dci commands --json is unchanged.
2. Question commands list with their resource. anomalies-recent and budgets-at-risk take the group of the operation they wrap and render right after list-anomalies / list-budgets instead of under "Additional Commands".
3. The exit-code and error-envelope contract is in --help. Root help gains a four-line "Exit codes" paragraph (codes 0/1/2/10/11/20/21/30/40/41/50, the stderr JSON envelope in agent mode, the Help Center link), and dci docs gains an "Exit codes and errors" entry.

Also: the skill text now says --help-full lists every flag, and a stray gofmt nit in help_context_test.go is fixed (separate chore: commit).

Not acted on: the commands --search ranking of open for "invite a teammate to the console" is expected keyword behaviour; the right command ranked first.

Before / after

dci invite-user --help (agent mode): 36 inherited flag lines → 10 flag lines plus the two-line output-flags pointer.

Output flags (apply to every command; add --help-full to list them):
  --no-truncate, --output-order, --raw-numbers, --utc, -C/--table-columns, -M/--table-mode
  -O/--output-file, -W/--table-width, -X/--table-max-col-width

dci --help:

Anomalies Commands: Monitor cost spikes in your cloud environment.
  get-anomaly              Retrieve an anomaly
  get-anomaly-explanation  Explain an anomaly
  list-anomalies           List anomalies
  anomalies-recent         List the most recent anomalies, ranked, with severity and cost aggregates

Exit codes: 0 success, 1 failure, 2 usage, 10 authentication, 11 permission, 20 not found,
21 conflict, 30 validation (or an unconfirmed destructive command), 40 server, 41 network, 50 rate limited.
Errors go to stderr; in agent mode as one JSON line: {"error":{"code","message","hint","retryable"}}.
Full table: https://help.doit.com/docs/cli#exit-codes

Tests

• help_flags_test.go: scope coverage of every persistent flag, placement per command shape, restore after render (catalog unaffected), --help-full, the pointer line, rendered help through the template, question-command group adoption and ordering, and a spec-gated check (DCI_COMMAND_DOCS_SPEC, fetched in CI) that the report-shaped and file-shaped operation sets match the live description.
• main_test.go TestHelpRendersWithoutCredentials: the hermetic spec now has one operation of each shape; new subtests for per-command flag visibility (four commands plus --help-full), root-help grouping, and the exit-code paragraph.
• docs_command_test.go and the pty suite (TestE2EDefaultHelpRoutesBareInvocation, TestE2EAPICommandHelpRendersWithoutCredentials) assert the new lines.
• gofmt -l ., go vet ./..., go test -skip TestE2E . ./tools/... (with the production spec), go test -run TestE2E . all pass; verified by hand with a fresh DCI_CONFIG_DIR for invite-user --help, anomalies-recent --help, and --help.

🤖 Generated with Claude Code

[claude]

Beyond the inline findings, I also checked whether marking a command as --search-eligible (helpCommandIsList, help_flags.go:192-201) could point at flags that silently do nothing: applyListSearch's shape detector (listWrapperRows, output_contract.go:268) accepts any single array-of-objects field or a results/items key with list metadata, which covers the list/search/paging/question-command shapes this classifier targets, so that concern is ruled out.

Extended reasoning...

The diff adds a help-text/UX chapter (help_flags.go) that classifies and folds persistent flags per command, plus question-command group adoption; it touches no auth/crypto/permission logic, only CLI help rendering and classification heuristics. Three confirmed findings already identified real edge-case inaccuracies in the flag-visibility classifier (report-shaped detection, error-path pointer line, multi-path-arg resolution fallback), so approval is not warranted. I additionally traced the ruled-out --search concern through applyListSearch/listWrapperRows to confirm it is not a live bug, which is the one piece of independent verification worth surfacing beyond the existing inline comments.

Findings marked 🟡 are optional suggestions and need no follow-up push.