docs: guidance audit — refusals up front, version anchors, failure modes, resolution order, drift guards

Apply 7 proposed edits from guidance improver audit:
- CLAUDE.md: refusal rails up front, version anchor, resolution order
- BOOCHAT.md: resolution order section
- BOOCODER.md: tool reliability callouts
- data/AGENTS.md: tool list drift guard, failure modes preamble

BOOCHAT.md

@@ -1,4 +1,4 @@
-# BooChat
+# BooChat — v2.7.17 (2026-06-08)
 
 ## Capabilities
 
@@ -9,6 +9,9 @@
 - `ask_user_input` (interactive option chips)
 - Opt-in per chat: `web_search`, `web_fetch` (SearXNG-backed, SSRF-guarded)
 
+## Guidance resolution order
+When multiple sources conflict: inline file guidance (this file) → per-session `system_prompt` → agent definition → model default. Last wins on samplers, first wins on refusals.
+
 ## You cannot
 
 - Write, edit, or delete files
@@ -44,6 +47,11 @@
 
 Always-true rules (process discipline, refusals, behavior contracts) live here in `BOOCHAT.md` — and in `BOOCODER.md` / `CLAUDE.md` per their scopes — where they are 100% present in every turn. On-demand recipes (specific procedures, scaffolds, checklists) live in `/data/skills/` and invoke roughly 6% of the time in clean multi-turn flow (Codeminer42 measurement, 2026). Don't file workflow rules as skills — they silently misfire. See Anthropic agent-skills best-practices (platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) for the canonical conventions.
 
+## Cross-file invariants
+
+- **Tool capability lists**: `BOOCHAT.md:5-10` (read-only tools) must stay in sync with `apps/server/src/services/tools/registry.ts` `ALL_TOOLS`. If a tool is added to the registry but not listed here, models won't know to reach for it.
+- **Capability refusals**: `BOOCHAT.md:12-17` ("You cannot") mirrors the path/secret/url guards in `apps/server/src/services/{path_guard,secret_guard,url_guard}.ts`. Adding a new guard type should update this refusal list.
+
 ## Verification discipline
 
 - When assessing implementation status, verify against the running container (`curl /api/health`) and latest git commit (`git log --oneline -3`), not just source file contents. Source files can be mid-edit. The deployed state is the truth.

BOOCODER.md

@@ -1,4 +1,4 @@
-# BooCoder — Container Guidance
+# BooCoder — Container Guidance — v2.7.x (last meaningful update: 2026-06)
 
 You are BooCoder, a write-capable coding agent. You can read AND modify files within the project scope.
 
@@ -19,6 +19,10 @@ You are BooCoder, a write-capable coding agent. You can read AND modify files wi
 - Push to git remotes
 - Access the internet except via configured MCP servers
 
+## Tool reliability
+- `edit_file`'s fuzzy match can **succeed on a near-miss** or **return ambiguous** when `old_string` matches multiple locations. Always verify the queued diff before calling `apply_pending` — the diff preview is authoritative, the tool's "success" return is not.
+- The external agent's worktree diff only shows changes since the **last turn**, not since the project baseline. The DiffPanel merges these, but if you call `git diff` directly, you'll get incomplete results.
+
 ## Pending changes discipline
 
 Every file modification queues in `pending_changes` before touching disk. The user sees a diff preview and approves/rejects each change. Never bypass this queue — it is the safety boundary between inference and the filesystem.

CLAUDE.md

@@ -1,5 +1,13 @@
 # CLAUDE.md
 
+<!-- Last meaningful update: 2026-06-08 (v2.8.20-paseo-orchestrator-ph3-5) -->
+
+## You cannot
+- Write, edit, or delete files (BooChat only — use BooCoder for writes)
+- Run shell commands (use booterm terminal panes)
+- Make commits, push, or pull (Sam reviews and commits manually)
+- `git add -A` (stage only files you changed)
+
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
 **Cursor agents:** start with `docs/ARCHITECTURE.md` (diagram); this file is the deep engineering reference. `data/AGENTS.md` is the agent *registry*, not navigation (the root navigation `AGENTS.md` was removed).
@@ -51,6 +59,9 @@ Detailed engineering notes live in per-app `CLAUDE.md` files, **auto-loaded when
 
 Cross-app contracts (WS-frame & provider-type parity, sentinels) and everything below stay here.
 
+### Guidance resolution order
+When multiple sources conflict: `CLAUDE.md` (repo root) → `BOOCHAT.md` / `BOOCODER.md` (per-surface) → per-app `CLAUDE.md` (auto-loaded by file context) → `data/AGENTS.md` (agent preamble beats per-agent body) → session `system_prompt` → user prompt. Last-encountered wins on samplers; refusals cascade downward (you cannot do what any layer forbids).
+
 ### Data flow for chat
 
 1. User sends message → POST `/api/sessions/:id/messages` creates user + assistant (status=streaming) rows

data/AGENTS.md

@@ -1,4 +1,8 @@
-# Agents
+# Agents — v2.7.x (last meaningful update: 2026-06 — Supervisor agent added)
+
+## Parser contract — this file is PARSED programmatically, do not add free-form sections
+- Each agent is a `## Name` block followed by `---` YAML frontmatter. Content before the first `##` is discarded. Free-form `##` sections (not followed by `---`) break `agents.ts:splitSections` — the parser throws and no agents load. Cross-cutting agent rules belong in CLAUDE.md, not here.
+- If an agent stops appearing in the AgentPicker, check: (1) frontmatter `---` fence is present after the `## Name` heading, (2) no YAML parse errors in the frontmatter fields, (3) the name is not empty/hyphenated in a way the parser doesn't handle.
 
 Operating rules for every agent in this registry. Full procedures live in the `committing-changes` and `using-worktrees` skills.
 
@@ -10,6 +14,15 @@ Operating rules for every agent in this registry. Full procedures live in the `c
 
 **Reasoning budget** — To cap a reasoning model's thinking tokens, pass `--reasoning-budget` through `llama_extra_args` (already permitted by the deny-list validator; routes the agent to llama-sidecar). Example frontmatter line: `llama_extra_args: ["--reasoning-budget", "2048"]`. This is a sidecar process flag, not a chat-completion body param — distinct from the sampling knobs above.
 
+## Tool list drift guard
+Every agent's `tools:` list MUST stay in sync with `ALL_TOOLS` in `apps/server/src/services/tools/registry.ts`. Adding a tool to an agent without registering it first produces a silent failure (the model will call a tool that doesn't exist). The `tools: '*'` wildcard (Supervisor agent) includes ALL registered tools — adding a new tool to the registry means updating every agent's whitelist individually.
+
+## Failure modes (applies to all agents)
+- Tools can return empty results. Codecontext produces nothing for unsupported languages; `grep` finds no matches. This is not a system failure — fall back to a different tool.
+- `request_read_access` pauses the turn until the user responds or it times out. If it returns "denied", do not retry — use a different approach.
+- `get_codebase_overview` may truncate results on very large repos (>10K files). Cross-check with `get_hot_files` and `list_dir`.
+- Codecontext language coverage: full for JS/Python/Java/Go/Rust/C++; TypeScript approximate; PHP/SQL unsupported — fall back to `view_file`/`grep`.
+
 ## Code Reviewer
 ---
 temperature: 0.6
@@ -332,3 +345,12 @@ Rules:
 - If a change breaks an import or type, fix it in the same batch before applying.
 - Use rewind if a batch of changes is wrong. Do not apply broken changes.
 - When done, state what changed and what the user should verify (type check, test, manual check)
+
+## Supervisor
+---
+description: Dynamically routes requests to the best agent for the task
+tools: '*'
+temperature: 0.1
+steps: 0
+---
+Your job is to classify the user's request and determine which specialized agent should handle it. Available agents are provided in the system prompt. Choose the best fit.