docs(claude): document new hooks, skills, and context-mode

CLAUDE.md

@@ -163,20 +163,115 @@ SC2174 (mkdir -p -m), SC2016 (single-quote expressions).
 ## Claude Code Configuration
 
 - **Hooks** (`.claude/settings.json`):
-  - *PreToolUse*: Blocks edits to `fzf-tmux`, `yarn.lock`, `.yarn/`
+  - *PreToolUse*: Blocks edits to `fzf-tmux`, `yarn.lock`,
-  - *PostToolUse*: Auto-runs `shfmt` on shell scripts after Edit/Write
+    `.yarn/`, submodule paths, and real secrets.d files
-  - *PostToolUse*: Auto-runs `fish_indent` on `.fish` files after Edit/Write
+  - *PostToolUse*: Auto-formats files by extension
-  - *PostToolUse*: Auto-runs `stylua` on `.lua` files after Edit/Write
+    (shfmt, fish_indent, stylua, biome, prettier)
+  - *PostToolUse*: Validates Dotbot `install.conf.yaml`
+    after edits
+  - *PostToolUse*: Warns on formatter/linter config changes
+  - *Stop*: Runs `yarn lint` gate before finishing
 - **Skills** (`.claude/skills/`):
-  - `shell-validate`: Auto-validates shell scripts (syntax + shellcheck)
+  - `shell-validate`: Auto-validates shell scripts
-  - `fish-validate`: Auto-validates fish scripts (syntax + fish_indent)
+    (syntax + shellcheck)
+  - `fish-validate`: Auto-validates fish scripts
+    (syntax + fish_indent)
   - `lua-format`: Auto-formats Lua files with stylua
-  - `yaml-validate`: Auto-validates YAML files (yamllint + actionlint)
+  - `yaml-validate`: Auto-validates YAML files
+    (yamllint + actionlint)
+  - `dotbot-validate`: Validates Dotbot install.conf.yaml
+  - `new-script`: Scaffolds helper scripts in local/bin/
+  - `new-fish-function`: Scaffolds fish functions
+  - `host-override`: Creates host-specific config overlays
 - **Subagents** (`.claude/agents/`):
-  - `code-reviewer`: Reviews shell/fish/lua changes for correctness and style
+  - `code-reviewer`: Reviews shell/fish/lua changes
-- **MCP Servers**:
+- **Plugins** (required):
-  - `context7`: Live documentation lookup for tools and libraries
+  - `context-mode`: Context window protection — must be
+    installed for this repo. See routing rules below.
+  - `context7`: Live documentation lookup
 
 ## Package Manager
 
 Yarn (v4+) is the package manager. Do not use npm.
+
+# context-mode — MANDATORY routing rules
+
+You have context-mode MCP tools available. These rules are NOT optional —
+they protect your context window from flooding. A single unrouted command
+can dump 56 KB into context and waste the entire session.
+
+## BLOCKED commands — do NOT attempt these
+
+### curl / wget — BLOCKED
+Any Bash command containing `curl` or `wget` is intercepted and replaced with an error message. Do NOT retry.
+Instead use:
+- `ctx_fetch_and_index(url, source)` to fetch and index web pages
+- `ctx_execute(language: "javascript", code: "const r = await fetch(...)")` to run HTTP calls in sandbox
+
+### Inline HTTP — BLOCKED
+Any Bash command containing `fetch('http`, `requests.get(`,
+`requests.post(`, `http.get(`, or `http.request(` is intercepted
+and replaced with an error message. Do NOT retry with Bash.
+Instead use:
+- `ctx_execute(language, code)` to run HTTP calls in sandbox — only stdout enters context
+
+### WebFetch — BLOCKED
+WebFetch calls are denied entirely. The URL is extracted and you are told to use `ctx_fetch_and_index` instead.
+Instead use:
+- `ctx_fetch_and_index(url, source)` then `ctx_search(queries)` to query the indexed content
+
+## REDIRECTED tools — use sandbox equivalents
+
+### Bash (>20 lines output)
+Bash is ONLY for: `git`, `mkdir`, `rm`, `mv`, `cd`, `ls`, `npm install`, `pip install`, and other short-output commands.
+For everything else, use:
+- `ctx_batch_execute(commands, queries)` — run multiple commands + search in ONE call
+- `ctx_execute(language: "shell", code: "...")` — run in sandbox, only stdout enters context
+
+### Read (for analysis)
+If you are reading a file to **Edit** it → Read is correct (Edit needs content in context).
+If you are reading to **analyze, explore, or summarize** →
+use `ctx_execute_file(path, language, code)` instead. Only your
+printed summary enters context. The raw file stays in the sandbox.
+
+### Grep (large results)
+Grep results can flood context.
+Use `ctx_execute(language: "shell", code: "grep ...")` to run
+searches in sandbox. Only your printed summary enters context.
+
+## Tool selection hierarchy
+
+1. **GATHER**: `ctx_batch_execute(commands, queries)` — Primary
+  tool. Runs all commands, auto-indexes output, returns search
+  results. ONE call replaces 30+ individual calls.
+2. **FOLLOW-UP**: `ctx_search(queries: ["q1", "q2", ...])` —
+  Query indexed content. Pass ALL questions as array in ONE call.
+3. **PROCESSING**: `ctx_execute(language, code)` |
+  `ctx_execute_file(path, language, code)` — Sandbox execution.
+  Only stdout enters context.
+4. **WEB**: `ctx_fetch_and_index(url, source)` then
+  `ctx_search(queries)` — Fetch, chunk, index, query.
+  Raw HTML never enters context.
+5. **INDEX**: `ctx_index(content, source)` — Store content in FTS5 knowledge base for later search.
+
+## Subagent routing
+
+When spawning subagents (Agent/Task tool), the routing block is
+automatically injected into their prompt. Bash-type subagents are
+upgraded to general-purpose so they have access to MCP tools.
+You do NOT need to manually instruct subagents about context-mode.
+
+## Output constraints
+
+- Keep responses under 500 words.
+- Write artifacts (code, configs, PRDs) to FILES — never return
+  them as inline text. Return only: file path + 1-line description.
+- When indexing content, use descriptive source labels so others can `ctx_search(source: "label")` later.
+
+## ctx commands
+
+| Command       | Action                                                                                |
+|---------------|---------------------------------------------------------------------------------------|
+| `ctx stats`   | Call the `ctx_stats` MCP tool and display the full output verbatim                    |
+| `ctx doctor`  | Call the `ctx_doctor` MCP tool, run the returned shell command, display as checklist  |
+| `ctx upgrade` | Call the `ctx_upgrade` MCP tool, run the returned shell command, display as checklist |