docs: fix documentation accuracy (hook command, config keys, sidecar flags, env vars)

[cursor]

Summary

Weekly documentation accuracy review pass against the current codebase. Several gaps were introduced by recent PRs (#323, #329, #334, #335, #336) and pre-existing stale content.

What was outdated and what was corrected

docs/CLI.md

• Added hook command (disable / enable / status) — renamed from hooks in Rename hooks command to hook #334 and never added to the reference
• Fixed config set keys — removed stale apiKey key (users should use auth set); added orgID and validation.sidecarImage project-level keys
• Added task config subcommand — existed in code but was omitted from the tree
• Added init --skip-skills and --skip-test-suites — new flags added in recent PRs, not documented
• Removed ghost sidecar setup flags — --snapshot-name and --skip-snapshot do not exist in code; setup prints a hint to run snapshot create manually instead
• Fixed sidecar create annotations — --org-id and --name are not required (org has an interactive picker; name is auto-generated)
• Added sidecar list --all and --json, validate --org-id and --json, config show --json, sidecar current --json, sidecar snapshot get --json, task run --json
• Updated Behavior Decisions to reflect the correct config set keys and hook disable mechanics

docs/ARCHITECTURE.md

• Added hook.go to the cmd/ listing; updated task.go note to include task config
• Removed non-existent usererr/ package entry (the code lives in internal/cmd/usererr.go)
• Added newly promoted packages: secrets/, session/, settings/
• Added CHUNK_HOOKS_DISABLED and CLAUDE_WORKING_DIR to the environment variable table

docs/HOOKS.md

• Added "Disabling Hooks" section documenting chunk hook disable/enable/status and CHUNK_HOOKS_DISABLED

docs/GETTING_STARTED.md

• Extended the env-forwarding section to include chunk validate --remote (added in Add --env/--env-file flags to validate and sidecar setup #323 / Forward CIRCLE_TOKEN env vars to remote validate commands #336) alongside sidecar ssh and sidecar setup

README.md

• Added chunk hook disable|enable|status to the commands table

  

[cursor]

Risk Assessment

Overall: Low — This is a small docs-only PR with no runtime behavior changes, but one documented env var appears unsupported by the current hook/validate implementation.

Dimension	Finding
Blast radius	Low runtime blast radius: only README/docs changed. User-facing CLI and hook docs are affected, so inaccuracies can still mislead users/agents. Concern: docs/ARCHITECTURE.md:186 says CLAUDE_WORKING_DIR is used by validate, but the codebase only references that name in docs; generated Stop hooks run chunk validate, and validate resolves cwd/--project rather than reading CLAUDE_WORKING_DIR.
Test coverage	No runtime code paths changed, so no new command or acceptance tests are required. Residual gap: there is no generated-doc or Cobra consistency check, so docs drift remains possible.
Breaking changes	No concerns. The PR does not change command names, flags, defaults, output formats, or .chunk/ file structure.
Security	No concerns. No new token handling, file permissions, shell execution, external API calls, or dependencies are introduced. The .env.local forwarding docs describe existing behavior.
Complexity	Low complexity and easy to review. Minor docs formatting concern: docs/ARCHITECTURE.md:20-25 lost indentation for the added internal/cmd entries, so the directory tree renders incorrectly.

Recommendation: either remove/correct the CLAUDE_WORKING_DIR row in docs/ARCHITECTURE.md:186, or update the generated Stop hook/validate path resolution to actually honor it. Also restore indentation on docs/ARCHITECTURE.md:20-25. One adjacent stale-doc note: docs/ARCHITECTURE.md:164 still shows the legacy apiKey config field even though this PR updates the config-key guidance elsewhere.

  

_{Sent by Cursor Automation: chunk-cli risk assessment}

[cursor]

Required

[docs/ARCHITECTURE.md:20] Directory tree indentation is broken

The new hook.go through validate.go entries lost the │ prefix used by the surrounding internal/cmd/ children, so the rendered tree shows those files outside internal/cmd/. That makes the architecture map misleading for the layering rules this doc is meant to explain.

[docs/ARCHITECTURE.md:185] Env var usage does not match the code

CLAUDE_PROJECT_DIR is now listed as used by validate, and CLAUDE_WORKING_DIR is listed as used by validate, but chunk validate resolves the project from --project or os.Getwd(), and CLAUDE_WORKING_DIR is not referenced in Go code. Could this table be narrowed to the env vars the code actually reads, or the implementation updated if these are intended inputs?

[docs/HOOKS.md:105] Hook disabling is documented too broadly

This says hooks are skipped when CHUNK_HOOKS_DISABLED is set, and docs/CLI.md:155 similarly says hooks are disabled by the sentinel/env var. In code, generated PreToolUse hooks run the configured commands directly, while the disabled check is only in chunk validate Stop-hook handling and hook status. As written, users may expect chunk hook disable to suppress pre-commit PreToolUse commands when it does not.

[README.md:122] Sidecar setup summary still says it snapshots

The README command table still describes chunk sidecar setup as Detect env, install deps, snapshot, but the implementation now completes setup and tells users to run chunk sidecar snapshot create manually. Since this PR updates the same command table and fixes the CLI docs wording, this summary should be brought in sync too.

  

_{Sent by Cursor Automation: chunk-cli PR review}

[hanabel1]

@cursoragent can u resolve the merge conflicts ;-;

[cursor]

Perfect! I've successfully resolved the merge conflicts. Here's what I did:

Conflict Resolution Summary

File with conflicts: docs/CLI.md

Conflict details: The init command section had conflicting flag order and descriptions for --skip-skills and --skip-test-suites.

Resolution:

• Kept the more detailed description from main for --skip-test-suites: "Skip .circleci/test-suites.yml scaffolding (default: true; pass =false to generate)"
• Maintained consistent flag order: --skip-completions, --skip-test-suites, --skip-skills
• Merged all other changes from main cleanly (including keyring support, auth improvements, and skill updates)

Changes committed and pushed: The merge commit is now live on the branch, and the PR is ready for review again.

  

[hanabel1]

wow