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

README.md

@@ -119,10 +119,11 @@ chunk auth set|status|remove               Authentication
 chunk sidecar list|create|exec|ssh         Manage cloud sidecar environments
 chunk sidecar sync|env|build               Sync files, detect env, build images
 chunk sidecar use|current|forget           Manage active sidecar
-chunk sidecar setup                        Detect env, install deps, snapshot
+chunk sidecar setup                        Detect env and install deps
 chunk sidecar snapshot create|get          Manage sidecar snapshots
 chunk init                                 Initialize project configuration
 chunk validate [name]                      Run quality checks
+chunk hook disable|enable|status           Manage hook execution
 chunk skill install|list                   Manage AI agent skills
 chunk task config|run                      Configure and trigger CI tasks
 chunk build-prompt                         Generate review context from PR comments

docs/ARCHITECTURE.md

@@ -17,9 +17,10 @@ chunk-cli/
     │   ├── completion.go      # completion install/uninstall/zsh
     │   ├── config.go          # config show/set
     │   ├── init.go            # init (project setup, settings.json generation)
-    │   ├── sidecar.go         # sidecar list/create/exec/add-ssh-key/ssh/sync/env/build
+    │   ├── hook.go            # hook disable/enable/status
+    │   ├── sidecar.go         # sidecar list/create/exec/add-ssh-key/ssh/sync/env/build/setup
     │   ├── skills.go          # skill install/list
-    │   ├── task.go            # task run
+    │   ├── task.go            # task run/config
     │   ├── upgrade.go         # upgrade
     │   └── validate.go        # validate
     ├── anthropic/             # Anthropic Messages API client
@@ -34,11 +35,13 @@ chunk-cli/
     ├── sidecar/               # CircleCI sidecar operations
     ├── skills/                # Skill definitions (go:embed) and installation
     ├── task/                  # Task run config and CircleCI trigger
+    ├── secrets/               # Secret resolution (env var value expansion)
+    ├── session/               # Session ID tracking for Stop hook context
+    ├── settings/              # .claude/settings.json build and merge
     ├── testing/recorder/      # HTTP recorder for tests
     ├── tui/                   # Terminal UI components (confirm, input, select)
     ├── ui/                    # Colors, formatting, spinner
     ├── upgrade/               # CLI self-upgrade
-    ├── usererr/               # User-facing error wrapper
     └── validate/              # Validation command logic
 ```
 
@@ -179,7 +182,8 @@ in `config.Resolve` and makes clients testable.
 | `GITHUB_API_URL` | github | GitHub API endpoint override |
 | `CIRCLE_TOKEN` / `CIRCLECI_TOKEN` | circleci | CircleCI authentication |
 | `CIRCLECI_BASE_URL` | circleci | CircleCI endpoint override |
-| `CLAUDE_PROJECT_DIR` | init | IDE-provided project directory |
+| `CLAUDE_PROJECT_DIR` | settings | IDE-provided project directory used by generated `PreToolUse` hooks |
+| `CHUNK_HOOKS_DISABLED` | validate, hook | Disable Stop-hook validation when set (any non-empty value) |
 | `XDG_CONFIG_HOME` | config | User config directory (default: `~/.config`) |
 | `XDG_DATA_HOME` | sidecar | Per-project state directory (default: `~/.local/share`) |
 

docs/CLI.md

@@ -24,24 +24,30 @@ chunk
 │
 ├── config
 │   ├── show                        # Display resolved configuration
-│   └── set <key> <value>           # Set a config value (keys: model, apiKey)
+│   │   --json                      # Output as JSON
+│   └── set <key> <value>           # Set a config value
+│                                   #   User keys: model
+│                                   #   Project keys: orgID, validation.sidecarImage
 │
 ├── init                            # Initialize project configuration
 │   --force                         # Overwrite existing config
 │   --skip-hooks                    # Skip hook file generation
 │   --skip-validate                 # Skip validate command detection
-│   --skip-completions               # Skip shell completion installation
+│   --skip-completions              # Skip shell completion installation
 │   --skip-test-suites              # Skip .circleci/test-suites.yml scaffolding (default: true; pass =false to generate)
 │   --skip-skills                   # Skip agent skill installation
 │   --project-dir <path>            # Project directory (defaults to cwd)
 │
 ├── task
-│   └── run                         # Trigger a task run
-│       --definition <name|uuid>    # Definition name or UUID (required)
-│       --prompt <text>             # Prompt text (required)
-│       --branch <branch>           # Branch override
-│       --new-branch                # Create a new branch
-│       --no-pipeline-as-tool       # Disable pipeline-as-tool mode
+│   ├── run                         # Trigger a task run
+│   │   --definition <name|uuid>    # Definition name or UUID (required)
+│   │   --prompt <text>             # Prompt text (required)
+│   │   --branch <branch>           # Branch override
+│   │   --new-branch                # Create a new branch
+│   │   --no-pipeline-as-tool       # Disable pipeline-as-tool mode
+│   │   --json                      # Output as JSON
+│   └── config                      # Set up .chunk/run.json for this repository
+│       --force                     # Overwrite existing configuration without confirmation
 │
 ├── skill
 │   ├── install                     # Install all skills
@@ -51,24 +57,30 @@ chunk
 │   [name]                          # Optional: run a specific named command
 │   --dry-run                       # Print commands without executing
 │   --list                          # List all configured commands
+│   --json                          # Output as JSON (only applies with --list)
 │   --cmd <command>                 # Run an inline command
 │   --save                          # Save --cmd to config
 │   --remote                        # Run on the active sidecar
 │   --sidecar-id <id>               # Remote execution in specific sidecar
+│   --org-id <id>                   # Organization ID (used when creating a new sidecar)
 │   --identity-file <path>          # SSH identity file for sidecar
 │   --workdir <path>                # Working directory on sidecar
 │   --project <path>                # Override project directory
 │   -e / --env KEY=VALUE            # Set env var in remote sidecar session (repeatable)
 │   --env-file <path>               # Env file to load (default: .env.local; pass a path to override)
 │
 ├── sidecar
-│   ├── list --org-id <id>          # List sidecars
+│   ├── list                        # List sidecars
+│   │   --org-id <id>               # Organization ID
+│   │   --all                       # List all sidecars in the org (requires org admin)
+│   │   --json                      # Output as JSON
 │   ├── create                      # Create a sidecar
-│   │   --org-id <id>               # Organization ID (required)
-│   │   --name <name>               # Sidecar name (required)
+│   │   --org-id <id>               # Organization ID (interactive picker when omitted)
+│   │   --name <name>               # Sidecar name (auto-generated when omitted)
 │   │   --image <image>             # E2B template ID or container image
 │   ├── use <id>                    # Set the active sidecar for this project
 │   ├── current                     # Show the active sidecar
+│   │   --json                      # Output as JSON
 │   ├── forget                      # Clear the active sidecar
 │   ├── exec                        # Execute command in sidecar
 │   │   --sidecar-id <id>           # Sidecar ID (defaults to active sidecar)
@@ -93,15 +105,13 @@ chunk
 │   ├── build                       # Generate Dockerfile and build test image from env spec
 │   │   --dir <path>                # Directory to write Dockerfile.test and build from
 │   │   --tag <tag>                 # Image tag (e.g. myapp:latest)
-│   ├── setup                       # Detect env, sync files, run install steps, snapshot
+│   ├── setup                       # Detect env, sync files, and run install steps
 │   │   --dir <path>                # Directory to detect environment in (default: .)
 │   │   --sidecar-id <id>           # Sidecar ID (defaults to active sidecar)
 │   │   --org-id <id>               # Organization ID (used when creating a new sidecar)
 │   │   --name <name>               # Sidecar name (used when creating a new sidecar)
 │   │   --identity-file <path>      # SSH identity file
-│   │   --snapshot-name <name>      # Snapshot name (defaults to <sidecar-name>-setup)
 │   │   --skip-sync                 # Skip syncing files to the sidecar
-│   │   --skip-snapshot             # Skip creating a snapshot after install
 │   │   --force                     # Re-detect environment even if cached
 │   │   -e / --env KEY=VALUE        # Set env var in remote sidecar session (repeatable)
 │   │   --env-file <path>           # Env file to load (default: .env.local; pass a path to override)
@@ -110,6 +120,13 @@ chunk
 │       │   --sidecar-id <id>       # Sidecar ID (defaults to active sidecar)
 │       │   --name <name>           # Snapshot name (required)
 │       └── get <snapshot-id>       # Get a snapshot by ID
+│           --json                  # Output as JSON
+│
+├── hook                            # Manage chunk hook execution
+│   --project <path>                # Override project directory
+│   ├── disable                     # Disable chunk validate hooks
+│   ├── enable                      # Re-enable chunk validate hooks
+│   └── status                      # Show whether hooks are enabled or disabled
 │
 ├── completion
 │   ├── install                     # Install zsh completion
@@ -126,7 +143,7 @@ chunk
 - `build-prompt --since` defaults to 3 months before the current date.
 - `task run` defaults to pipeline-as-tool mode; use `--no-pipeline-as-tool`
   to disable.
-- `config set` accepts only `model` and `apiKey` as keys.
+- `config set` accepts `model` as a user config key and `orgID` / `validation.sidecarImage` as project config keys. Use `chunk auth set` to store credentials.
 - `chunk init` uses Claude to auto-detect the test command for the project.
   It generates `.claude/settings.json` with pre-commit hooks. It never touches
   CircleCI — tokens are prompted inline only when a command actually needs them.
@@ -135,6 +152,7 @@ chunk
   failing with an error.
 - `chunk auth set github` stores a GitHub token in the config file; previously
   only the `GITHUB_TOKEN` environment variable was supported.
+- `chunk hook disable` creates a `.chunk/hooks-disabled` sentinel file inspected by the `chunk validate` Stop hook; `hook enable` removes it. Stop-hook validation is also disabled when `CHUNK_HOOKS_DISABLED` is set in the environment.
 
 ## Flag Conventions
 

docs/GETTING_STARTED.md

@@ -207,17 +207,20 @@ chunk sidecar create --image myimg                   # name auto-generated
 
 ### Environment variables
 
-`chunk sidecar ssh` and `chunk sidecar setup` automatically load `.env.local` from your working directory and forward its variables to the remote sidecar session. This lets you pass secrets and configuration without embedding them in your shell or committing them to the repo.
+`chunk sidecar ssh`, `chunk sidecar setup`, and `chunk validate` (when running remotely) automatically load `.env.local` from your working directory and forward its variables to the remote sidecar session. This lets you pass secrets and configuration without embedding them in your shell or committing them to the repo.
 
 ```bash
 # .env.local is loaded automatically — no flag needed
 chunk sidecar ssh
+chunk validate --remote
 
 # Override with a different file
 chunk sidecar ssh --env-file /path/to/other.env
+chunk validate --remote --env-file /path/to/other.env
 
 # Add individual variables (merged on top of the file)
 chunk sidecar ssh --env MY_VAR=value
+chunk validate --remote --env MY_VAR=value
 ```
 
 Variables from `--env` flags take precedence over those in `--env-file`. `.env.local` is gitignored by convention, so it's a safe place to store project-specific secrets.

docs/HOOKS.md

@@ -92,6 +92,20 @@ without prompting.
 | **Claude Code** (CLI / terminal) | Fully supported | Canonical provider |
 | **Cursor** | Supported | Reads `.claude/settings.json` directly |
 
+## Disabling Stop-Hook Validation
+
+Temporarily disable the `chunk validate` Stop hook without modifying `.claude/settings.json`:
+
+```bash
+chunk hook disable   # Creates .chunk/hooks-disabled sentinel file
+chunk hook enable    # Removes the sentinel file
+chunk hook status    # Shows "enabled" or "disabled"
+```
+
+Stop-hook validation is also skipped when the `CHUNK_HOOKS_DISABLED` environment variable is set to any non-empty value. This does not suppress `PreToolUse` commit hooks generated by `chunk init`, because those commands run directly from `.claude/settings.json`.
+
+The `--project` flag overrides the project root used to locate the sentinel file.
+
 ## Manual Validation
 
 Use `chunk validate` to run checks manually (outside of hooks):