docs(truth): reconcile README uncalled claims and invalid guide surfaces

Execute the top-ranked follow-ups from the origins/dormant-surfaces refresh
(G-P2-7). Every claim was re-verified against code before editing.

README (documented-but-uncalled -> match code):
- Failure warnings are surfaced on demand via `teaagent memory failures`, not
  auto-injected (`get_failure_warnings` has no caller).
- Pinned-file context refresh is TUI-session only (`FileWatcher` is TUI-only).
- Removed the false pin-count prompt indicator (`_prompt()` renders no pin count).
- Validation is static analysis (ruff/mypy/tsc/eslint), not LSP, and runs post-run
  via `--validate` (it does not gate commits).
- RAG archival is a helper (`ContextBus.archive_to_rag`), not auto-invoked.

Guides (invalid CLI/API -> real surfaces):
- `audit export --audit-log <run_id>` -> `audit export <run_id>` (positional).
- `audit verify --audit-log <file>` -> `audit verify --root .`.
- Replaced nonexistent `audit analyze` / `audit archive` with real commands
  (`audit list`/`audit tail`/`audit prune`) in the security onboarding guide.
- Rewrote the hooks integration section to the real API: build a `HookRegistry`,
  `register_pre_hook`/`register_post_hook` with real signatures, attach via
  `ChatAgentConfig(hook_registry=...)`; corrected the event table to `HookEvent`
  names (PreToolUse/PostToolUse/...).

D7 (stale 650->663 acceptance count in the constitution-tier harness-first doc)
is deferred to Human Review, as its own governance header requires.

Action: G-P2-7
Roadmap-Status: unchanged
Constraint: docs-only truth corrections; no code/behavior change; each claim verified against code before editing; constitution-tier D7 left for Human Review
Tested: validate_docs_consistency.py passes (29/29 risk, 21/21 ticket, consistency passed); command-snippet + docs inventories regenerated; audit/agent CLI signatures and hooks.py API verified via --help and source
Confidence: high

Author: johnteee

README.md

@@ -130,23 +130,22 @@ TeaAgent includes persistent memory features to learn from past mistakes and syn
 
 **Failure Experience Loop:**
 - Background tasks that fail automatically create "failure cards" capturing error context
-- Future similar tasks automatically receive warnings about past failures
+- Review those failure cards before retrying similar work via `teaagent memory failures` (surfaced on demand, not auto-injected into new runs)
 - Automated invalidation rules prevent memory corruption (file signature changes, test refactors, dependency updates)
 - Commands: `teaagent memory failures` (list), `teaagent memory failures auto-invalidate` (apply rules), `teaagent memory failures prune` (cleanup)
 
 **Live Context Anchors:**
 - Pin files with `/pin <file>` to watch for changes in your IDE
-- CLI automatically refreshes context when you save pinned files
+- The interactive TUI refreshes context when you save pinned files (the file watch runs in the TUI session)
 - Commands: `/pin <file>`, `/unpin <file>`, `/pinned` (list)
-- Visual indicator in prompt shows pinned file count (e.g., `teaagent📌2>`)
 
 ### 8. Self-Healing Validation (Beta)
 
-LSP/static analysis validation is integrated with the agent runner and workflow engine:
+Static analysis validation (ruff, mypy, tsc, eslint) is integrated with the agent runner and workflow engine:
 
 **Validation Tools:**
 - Auto-detects available tools (ruff, mypy, tsc, eslint)
-- Validates code before committing changes
+- Runs the configured validation profile after an agent run (post-run; it does not gate commits)
 - Supports Python, TypeScript, and JavaScript projects
 - Enable with `--validate` on `agent run` or via workflow self-healing steps
 
@@ -177,7 +176,7 @@ Self-healing validation is described in [section 8](#8-self-healing-validation-b
 - Real-time Delta sharing between parallel agents via WAL-mode SQLite (per-thread connections; see `docs/context-bus-and-federated-sync.md`)
 - Delta cards for code changes, discoveries, errors, and context updates
 - Filtered subscriptions by agent, type, and timestamp
-- Automatic RAG archive after workflow completion
+- RAG archival helper (`ContextBus.archive_to_rag`) is available for callers; it is not auto-invoked after runs
 
 **Evolutionary Prompt Tuning:**
 - Performance-based agent prompt evolution

docs/api/integration-guide.md

@@ -283,32 +283,47 @@ from teaagent.cli._handlers.my_command import handle_my_command
 
 ## Registering Hook Handlers
 
-Hooks fire at key points in the agent lifecycle. Register with `hook_registry`:
+Hooks fire at key points in the agent lifecycle. Build a `HookRegistry`, register
+handlers, and attach it to your agent config:
 
 ```python
-from teaagent.hooks import hook_registry
+from teaagent.hooks import HookRegistry, HookError
 
-@hook_registry.register('before_tool_call')
-def my_before_hook(context: dict) -> None:
-    print(f"About to call: {context['tool_name']}")
+registry = HookRegistry()
 
-@hook_registry.register('after_tool_call')
-def my_after_hook(context: dict) -> None:
-    print(f"Tool returned: {context['result']}")
+def my_pre_hook(tool_name: str, arguments: dict) -> dict | None:
+    # Return modified arguments, None to allow unchanged, or raise HookError to veto.
+    print(f"About to call: {tool_name}")
+    return None
+
+def my_post_hook(tool_name: str, arguments: dict, result: dict) -> dict | None:
+    # Return a modified result, or None to keep the original.
+    print(f"Tool returned: {result}")
+    return None
+
+registry.register_pre_hook(my_pre_hook)
+registry.register_post_hook(my_post_hook)
 ```
 
+Attach the registry when you construct the agent —
+`ChatAgentConfig(hook_registry=registry)` — and it is wired into the tool registry at
+run start.
+
 ### Available hook events
 
-| Event | Context keys | Description |
-|-------|-------------|-------------|
-| `before_tool_call` | `tool_name`, `call_id`, `arguments` | Before dispatching a tool |
-| `after_tool_call` | `tool_name`, `call_id`, `result`, `elapsed_ms` | After tool returns |
-| `on_tool_error` | `tool_name`, `call_id`, `error` | When tool raises |
-| `before_model_call` | `messages`, `model`, `iteration` | Before sending to LLM |
-| `after_model_call` | `response`, `cost_cents`, `tokens` | After LLM responds |
-| `on_run_start` | `run_id`, `task`, `config` | Run begins |
-| `on_run_end` | `run_id`, `result` | Run completes |
-| `on_approval_request` | `approval_request` | Approval prompt triggered |
+The lifecycle is Claude Code-compatible (`teaagent.hooks.HookEvent`); register each via
+the matching `HookRegistry` method:
+
+| Event (`HookEvent`) | Register with | Handler signature |
+|---------------------|---------------|-------------------|
+| `SessionStart` | `register_session_start_hook` | `(session_id, context)` |
+| `UserPromptSubmit` | `register_user_prompt_submit_hook` | `(session_id, context)` |
+| `PreToolUse` | `register_pre_hook` | `(tool_name, arguments)` -> modified args or None; raise `HookError` to veto |
+| `PostToolUse` | `register_post_hook` | `(tool_name, arguments, result)` -> modified result or None |
+| `PreCompact` | `register_pre_compact_hook` | `(context)` -> modified context or None |
+| `Stop` | `register_stop_hook` | `(session_id, context)` |
+| `SubagentStop` | `register_subagent_stop_hook` | `(session_id, context)` |
+| `SessionEnd` | `register_session_end_hook` | `(session_id, context)` |
 
 ---
 

docs/cli.md

@@ -924,7 +924,7 @@ teaagent agent show <run_id> --root /path/to/repo
 Export a compliance audit bundle with hash-chain verification for a completed run:
 
 ```bash
-teaagent audit export --audit-log <run_id> --output compliance.json
+teaagent audit export <run_id> --output compliance.json
 ```
 
 The compliance bundle includes a signed digest of all audit events, chain verification

docs/generated/command-snippet-inventory.md

@@ -10,19 +10,19 @@ Regenerate: `python3 scripts/generate_command_snippet_inventory.py`
 | --- | --- | --- | --- |
 | `teaagent --config .teaagent/config.json model smoke gpt` | `docs/cli.md:31` (0de72469) | manual | Alternate config path smoke |
 | `teaagent --help` | `docs/cli.md:25` (d09b09bd) | manual | CLI help smoke |
-| `teaagent agent daily gpt "Summarize the tests" --permission-mode read-only` | `README.md:367` (05bc391c) | smoke | tests/acceptance/test_daily_cli.py |
+| `teaagent agent daily gpt "Summarize the tests" --permission-mode read-only` | `README.md:366` (05bc391c) | smoke | tests/acceptance/test_daily_cli.py |
 | `teaagent agent daily gpt "map subsystem boundaries" --context-profile deep` | `docs/USAGE.md:371` (3ac367a2) | smoke | tests/acceptance/test_daily_cli.py |
 | `teaagent agent daily gpt "plan test fix" --context-profile balanced` | `docs/USAGE.md:370` (291ea4fe) | smoke | tests/acceptance/test_daily_cli.py |
 | `teaagent agent daily gpt "review auth flow" --context-profile lean` | `docs/USAGE.md:369` (efe69395) | smoke | tests/acceptance/test_daily_cli.py |
 | `teaagent agent daily gpt "what I want to do today" --permission-mode read-only --root .` | `docs/USAGE.md:330` (41b8128d) | smoke | tests/acceptance/test_daily_cli.py |
 | `teaagent agent preflight gpt "fix tests/test_foo.py" --route-model` | `docs/USAGE.md:372` (d6336bc5) | manual | Preflight smoke with configured provider |
-| `teaagent agent run gpt "Analyze this codebase" --permission-mode read-only` | `README.md:336` (a8e6903c) | manual | Agent run smoke with configured provider |
-| `teaagent agent run gpt "Improve this project" --clarify` | `README.md:361` (d2ccc65c) | manual | Agent run smoke with configured provider |
-| `teaagent agent run gpt "Inspect this repo and summarize the test suite"` | `README.md:355` (528345e2) | manual | Agent run smoke with configured provider |
-| `teaagent agent run gpt "Update README" --permission-mode workspace-write --route-model` | `README.md:358` (5ef6ae13) | manual | Agent run smoke with configured provider |
+| `teaagent agent run gpt "Analyze this codebase" --permission-mode read-only` | `README.md:335` (a8e6903c) | manual | Agent run smoke with configured provider |
+| `teaagent agent run gpt "Improve this project" --clarify` | `README.md:360` (d2ccc65c) | manual | Agent run smoke with configured provider |
+| `teaagent agent run gpt "Inspect this repo and summarize the test suite"` | `README.md:354` (528345e2) | manual | Agent run smoke with configured provider |
+| `teaagent agent run gpt "Update README" --permission-mode workspace-write --route-model` | `README.md:357` (5ef6ae13) | manual | Agent run smoke with configured provider |
 | `teaagent agent run gpt "fix tests/test_foo.py" --permission-mode workspace-write` | `docs/USAGE.md:373` (76f03456) | manual | Agent run smoke with configured provider |
-| `teaagent agent run gpt "inspect src/app.py" --code-analysis` | `README.md:378` (153bc54d) | manual | Agent run smoke with configured provider |
-| `teaagent agent runs` | `README.md:364` (0493189b) | manual | Run list smoke |
+| `teaagent agent run gpt "inspect src/app.py" --code-analysis` | `README.md:377` (153bc54d) | manual | Agent run smoke with configured provider |
+| `teaagent agent runs` | `README.md:363` (0493189b) | manual | Run list smoke |
 | `teaagent agent undo --last --root .` | `docs/USAGE.md:34` (6dc512e7) | manual | Undo smoke after mutating run |
 | `teaagent approval check workspace_write_file --path src/foo.py --root .` | `docs/USAGE.md:67` (a85952bb) | manual | Scoped grant check smoke |
 | `teaagent approval grant workspace_run_shell_mutate --command-prefix 'pytest ' --root .` | `docs/USAGE.md:65` (f0759ae5) | manual | Scoped grant smoke in prompt mode |

docs/generated/docs-aging-dashboard.md

@@ -21,7 +21,7 @@ Regenerate: `python3 scripts/report_docs_aging.py`
 
 | Document | Status | Last reviewed | File mtime | Notes |
 | --- | --- | --- | --- | --- |
-| `docs/cli.md` | stale_by_mtime | 2026-06-06 | 2026-06-21 | Missing owner banner; File modified after last reviewed date |
+| `docs/cli.md` | stale_by_mtime | 2026-06-06 | 2026-07-01 | Missing owner banner; File modified after last reviewed date |
 
 ### daily-driver
 
@@ -49,7 +49,7 @@ Regenerate: `python3 scripts/report_docs_aging.py`
 
 | Document | Status | Last reviewed | File mtime | Notes |
 | --- | --- | --- | --- | --- |
-| `README.md` | stale_by_mtime | 2026-06-17 | 2026-06-21 | Missing owner banner; File modified after last reviewed date |
+| `README.md` | stale_by_mtime | 2026-06-17 | 2026-07-01 | Missing owner banner; File modified after last reviewed date |
 
 ### release
 

docs/generated/docs-inventory.md

@@ -164,7 +164,7 @@ Do not edit this file manually — regenerate instead.
 | `api/cli-api.md` | working | 12872 | `024709a9633a` |
 | `api/daily-driver-command-contracts-2026-06-02.md` | archive | 1174 | `867a4267cd7e` |
 | `api/data-formats.md` | working | 9607 | `3dbcae1c1785` |
-| `api/integration-guide.md` | working | 13127 | `9b0d324467f8` |
+| `api/integration-guide.md` | working | 13822 | `38ae10c08466` |
 | `api/mcp-api.md` | working | 6766 | `16dc0ff0b9e6` |
 | `api/python-api.md` | working | 18652 | `c74af18ca68a` |
 | `api/README.md` | working | 5308 | `4993082e1bf3` |
@@ -193,7 +193,7 @@ Do not edit this file manually — regenerate instead.
 | `archive/INDEX.md` | working | 8774 | `1efa1af575f5` |
 | `audit-events.md` | working | 2376 | `b83066076fba` |
 | `backlog-priority.md` | working | 32338 | `4fcd06c4782f` |
-| `cli.md` | working | 36528 | `88e79b022406` |
+| `cli.md` | working | 36516 | `c38d3a5e9907` |
 | `cloud-deployment.md` | working | 9431 | `50f6461a2077` |
 | `context-bus-and-federated-sync.md` | working | 1564 | `2dde6eed4bf8` |
 | `daily-driver-current-status.md` | working | 17475 | `3baeefb535f9` |
@@ -239,8 +239,8 @@ Do not edit this file manually — regenerate instead.
 | `DOCUMENTATION_STRATEGY.md` | working | 8211 | `aecb1e6ce6c3` |
 | `error-reference.md` | working | 4897 | `067448aba6f1` |
 | `gateway-oauth-tenants.md` | working | 1818 | `0ff9c7df4652` |
-| `generated/command-snippet-inventory.md` | working | 8128 | `f11e933dfa4d` |
-| `generated/docs-aging-dashboard.md` | working | 4995 | `baa894c82548` |
+| `generated/command-snippet-inventory.md` | working | 8128 | `e6e24d7fb469` |
+| `generated/docs-aging-dashboard.md` | working | 4995 | `6b1cc99575f5` |
 | `generated/release-docs-evidence.md` | working | 2517 | `e28e92734209` |
 | `governance-compliance.md` | constitution | 1645 | `d7665f2f7864` |
 | `governance/code-review-checklist.md` | working | 4379 | `f580da208c75` |
@@ -270,7 +270,7 @@ Do not edit this file manually — regenerate instead.
 | `governance/security-standards.md` | working | 7747 | `fcdf36df8285` |
 | `governance/standards.md` | working | 9573 | `bbf0fa146cb2` |
 | `governance/testing-standards.md` | working | 5818 | `15a44e1078db` |
-| `governance/trust-and-audit-whitepaper.md` | working | 4920 | `641758c5382d` |
+| `governance/trust-and-audit-whitepaper.md` | working | 4908 | `111a0b2046a8` |
 | `graphqlite-production.md` | working | 5127 | `6426aec5caf9` |
 | `graphqlite.md` | working | 1207 | `77e3f89f30c7` |
 | `guides/agent-mode-recipes-2026-06-02.md` | archive | 1421 | `a6802fd18360` |
@@ -280,9 +280,9 @@ Do not edit this file manually — regenerate instead.
 | `guides/chat-surface-semantics.md` | working | 2690 | `24d0ec17e395` |
 | `guides/daily-driver-command-cookbook-2026-06-02.md` | archive | 1943 | `d9155cd0c744` |
 | `guides/daily-driver-guide-index-2026-06-02.md` | archive | 1378 | `441f42fec252` |
-| `guides/getting-started-security-reviewer.md` | working | 2093 | `686b399abc5c` |
+| `guides/getting-started-security-reviewer.md` | working | 2081 | `815983cebe06` |
 | `guides/getting-started-solo-cli.md` | working | 1560 | `943cf2c8eda2` |
-| `guides/getting-started-team-operator.md` | working | 1771 | `39b7d7bba818` |
+| `guides/getting-started-team-operator.md` | working | 1759 | `a4f6a05b934d` |
 | `guides/getting-started-tool-plugin-author.md` | working | 1828 | `bfa469d6c758` |
 | `guides/hybrid-approval-queue-configuration.md` | working | 20139 | `9b9af38453ef` |
 | `guides/integration-guide.md` | working | 14532 | `008880ed29f0` |
@@ -407,8 +407,8 @@ Do not edit this file manually — regenerate instead.
 | `modules/workspace_tools/spec.md` | working | 2155 | `886b45749b93` |
 | `multi-sig-wan-deployment.md` | working | 1585 | `0c35b3606dc9` |
 | `observability-logging.md` | working | 3029 | `591ed74fc38c` |
-| `onboarding-ml-researchers.md` | working | 10059 | `ebaeeb788ee2` |
-| `onboarding-security-engineers.md` | working | 8152 | `dc8bfad3250c` |
+| `onboarding-ml-researchers.md` | working | 10029 | `356f5cb881e3` |
+| `onboarding-security-engineers.md` | working | 8190 | `e72254a0c125` |
 | `operator-trust-model.md` | working | 3439 | `2077a669d958` |
 | `ops/backup-and-recovery.md` | working | 8644 | `0d02d348ab2b` |
 | `ops/configuration-reference.md` | working | 9722 | `04d9ac3d2158` |
@@ -524,7 +524,7 @@ Do not edit this file manually — regenerate instead.
 | `retrospective/03-architecture-quality.md` | working | 27525 | `fd28fdd70665` |
 | `retrospective/04-ux-usability.md` | working | 26253 | `a9350bc35c4b` |
 | `retrospective/05-compliance-matrix.md` | working | 8285 | `cd2568b5eddb` |
-| `retrospective/06-action-register.md` | working | 34588 | `4c105e153ca3` |
+| `retrospective/06-action-register.md` | working | 35782 | `a90fb37388cb` |
 | `retrospective/automation-plan.md` | working | 18716 | `0e0027c4b1c5` |
 | `retrospective/README.md` | working | 8718 | `d93f2a71f6b3` |
 | `retrospective/review-system.md` | working | 15180 | `61db6643e4aa` |

docs/governance/trust-and-audit-whitepaper.md

@@ -79,7 +79,7 @@ teaagent doctor config-lint --root .
 teaagent audit verify --root .
 
 # Compliance bundle export (signed digest)
-teaagent audit export --audit-log <run_id> --output /tmp/bundle.json --root .
+teaagent audit export <run_id> --output /tmp/bundle.json --root .
 
 # Observability on a completed run
 teaagent audit tail <run_id> --human --limit 20 --root .

docs/guides/getting-started-security-reviewer.md

@@ -17,7 +17,7 @@ Enterprise NIST mapping detail: [Security Whitepaper](../security-whitepaper.md)
 
 1. Sample run audit log: `.teaagent/runs/<run_id>.jsonl`
 2. Chain verification output: `teaagent audit verify --root .`
-3. Compliance export: `teaagent audit export --audit-log <run_id> --output bundle.json`
+3. Compliance export: `teaagent audit export <run_id> --output bundle.json`
 4. Config lint: `teaagent doctor config-lint --root .`
 5. Permission policy: `teaagent approval list --root .`
 

docs/guides/getting-started-team-operator.md

@@ -35,7 +35,7 @@ Review `doctor config-lint` findings before enabling destructive modes in CI.
 ```bash
 teaagent approval pending --human --root .
 teaagent audit verify --root .
-teaagent audit export --audit-log <run_id> --output evidence.json --root .
+teaagent audit export <run_id> --output evidence.json --root .
 teaagent doctor config-lint --root .
 ```
 

docs/onboarding-ml-researchers.md

@@ -170,7 +170,7 @@ teaagent run "Train model and log metrics" \
 
 **Reproducibility checks:**
 ```bash
-teaagent audit verify --audit-log experiment-001-audit.jsonl
+teaagent audit verify --root .
 ```
 
 ## Best Practices for ML Research