# Docs Layer Refresh Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Refresh all human-facing documentation (`Readme.md`, `docs/Readme.md`, all `docs/guide_*.md`, plus new guides for subsystems that emerged since Feb 2026) to textbook / Microsoft "purple-tomb" SDK documentation fidelity. No source code changes. No new tooling. Per-file atomic commits with git notes.

**Architecture:** Single-agent sequential execution. Each guide is a self-contained task: audit current state, identify gaps against `conductor/product.md`, rewrite affected sections in VEFontCache-Odin style (Philosophy → Architectural Boundaries → Implementation Logic → Verification), validate cross-doc links, commit per-file, attach git note. New guides are written only for subsystems explicitly listed in `conductor/product.md` that lack coverage.

**Tech Stack:** Manual Slop's MCP research tools (`manual-slop_get_file_summary`, `manual-slop_py_get_skeleton`, `manual-slop_py_get_code_outline`, `manual-slop_get_git_diff`, `manual-slop_search_files`). Git for version control. Markdown for documentation.

**Spec:** `docs/superpowers/specs/2026-06-02-comprehensive-documentation-refresh-design.md` §4 (Sub-Track 1).

---

## Execution Constraints

These apply to every task in this plan:

- **No subagents.** Execute as a single agent. No Tier 3/Tier 4 delegation. No parallel workers.
- **Pre-edit checkpoint:** Before any file edit, run `git add .` to stage current state. Protects against any subsequent `git restore` mishap.
- **Per-file atomic commits:** One file = one commit. Never batch.
- **Commit message format:** `docs(<scope>): <imperative description>` (e.g., `docs(architecture): document RAG engine integration`).
- **Git note format:** Attach a 3-8 line rationale to each commit via `git notes add -m "<note>" <sha>`. The note should list: source files cross-referenced, subsystems updated, any decisions made.
- **Style baseline:** VEFontCache-Odin pattern. Philosophy → Architectural Boundaries → Implementation Logic → Verification. No "In this section..." filler. Symbol names match source exactly.
- **Link validation:** For every `[text](./relative/path)` link in a modified file, verify the target exists via `manual-slop_search_files` or `manual-slop_list_directory`.
- **"Textbook / purple-tomb fidelity" concretely means:** for every public class/function/event mentioned, the doc states its signature, threading constraints, side effects, and at least one usage example. Internal algorithms explained step-by-step. State machines include the full transition table.
- **No new comments added to source code.** Docs live in `/docs`, not inline.

---

## Task 1: Inventory and Gap Analysis

**Files:**
- Read: `conductor/product.md`
- Read: `docs/Readme.md`
- Read: each `docs/guide_*.md` (use `manual-slop_get_file_summary` for first pass)
- Read: `docs/MMA_Support/*` (use `manual-slop_get_file_summary` for first pass)

**Output:** A gap table written into the parent track's `conductor/tracks/documentation_refresh_comprehensive_20260602/gap_analysis.md` (create the parent track directory in this task if it doesn't exist).

- [ ] **Step 1.1: Pre-edit checkpoint**

```powershell
git -C C:\projects\manual_slop add .
```

- [ ] **Step 1.2: Create the parent track directory**

```powershell
New-Item -ItemType Directory -Path "C:\projects\manual_slop\conductor\tracks\documentation_refresh_comprehensive_20260602" -Force
```

- [ ] **Step 1.3: Read `conductor/product.md` to get the canonical feature list**

Use `manual-slop_get_file_summary` first. If the file is summarized well, proceed to extract feature names. If you need the full list, use `manual-slop_get_file_slice` with a generous range.

Identify every distinct feature/subsystem mentioned (e.g., Beads mode, RAG, Hot Reload, 4-Tier MMA, 26 MCP tools, Multi-Provider, etc.).

- [ ] **Step 1.4: Read every `docs/guide_*.md` to map current coverage**

For each guide:
- Use `manual-slop_get_file_summary` for a quick read
- Note which subsystems from `conductor/product.md` it covers
- Note which subsystems it does NOT cover

Files to inventory:
- `docs/guide_architecture.md`
- `docs/guide_mma.md`
- `docs/guide_tools.md`
- `docs/guide_simulations.md`
- `docs/guide_context_curation.md`
- `docs/guide_shaders_and_window.md`
- `docs/guide_meta_boundary.md`

- [ ] **Step 1.5: Read `docs/Readme.md` to confirm what's indexed**

Verify which guides are linked from the documentation index. Flag any `docs/guide_*.md` that is NOT in the index (likely candidates: `guide_context_curation.md`, `guide_shaders_and_window.md`).

- [ ] **Step 1.6: Write the gap analysis**

Create `conductor/tracks/documentation_refresh_comprehensive_20260602/gap_analysis.md` with this structure:

```markdown
# Docs Layer Gap Analysis

**Date:** 2026-06-02
**Source of truth for features:** `conductor/product.md`
**Source of truth for guides:** `docs/Readme.md` and `docs/guide_*.md`

## Existing Guides and Their Coverage

| Guide | Covers | Does NOT cover (gaps) |
|---|---|---|
| `docs/guide_architecture.md` | [list] | [list] |
| `docs/guide_mma.md` | [list] | [list] |
| ... | ... | ... |

## Subsystems Without Dedicated Guides

| Subsystem | Source module(s) | Recommendation |
|---|---|---|
| RAG | `src/rag_engine.py` | NEW: `docs/guide_rag.md` |
| Beads | `src/beads_client.py` | NEW: `docs/guide_beads.md` |
| ... | ... | ... |

## Existing Guides That Are Stale

| Guide | Last meaningful update | Stale sections |
|---|---|---|
| ... | ... | ... |

## Cross-Cutting Issues

- Files in `docs/MMA_Support/*` not linked from `docs/Readme.md`: [list]
- Guides that reference each other via broken links: [list]
- Symbols in docs that don't match current source: [list, if any found during the read pass]
```

- [ ] **Step 1.7: Commit the gap analysis**

```powershell
git -C C:\projects\manual_slop add conductor/tracks/documentation_refresh_comprehensive_20260602/gap_analysis.md
git -C C:\projects\manual_slop commit -m "docs(track): docs layer gap analysis for comprehensive refresh"
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Subsystem coverage map for docs layer refresh. Each existing guide's coverage and gaps listed. New guides recommended for unlisted subsystems." $_ }
```

- [ ] **Step 1.8: Record SHA in plan**

After committing, note the commit SHA. This gap analysis becomes the source of truth for all subsequent tasks in this plan.

```markdown
Gap analysis commit SHA: [paste here]
```

---

## Task 2: Update the Documentation Index (`docs/Readme.md`)

**Files:**
- Modify: `docs/Readme.md`
- Test: Manual link validation (every `[text](./relative/path)` target exists)

- [ ] **Step 2.1: Pre-edit checkpoint**

```powershell
git -C C:\projects\manual_slop add .
```

- [ ] **Step 2.2: Read current `docs/Readme.md`**

Use `manual-slop_read_file` (file is small enough).

- [ ] **Step 2.3: Identify missing guide links**

Cross-reference the Guides table in `docs/Readme.md` against the list of `docs/guide_*.md` files (from Task 1). Flag every guide that is NOT in the index.

- [ ] **Step 2.4: Add the missing guide entries**

For each missing guide, add a row to the Guides table:

```markdown
| [Context Curation](guide_context_curation.md) | [contents summary] |
| [Shaders & Window](guide_shaders_and_window.md) | [contents summary] |
```

The "[contents summary]" should be 1-2 lines describing the guide's scope, written in the same high-density style as the existing rows.

- [ ] **Step 2.5: If Task 1.6 recommended new guides, add placeholder rows for them too**

```markdown
| [RAG](guide_rag.md) | [contents summary — written in Task N] |
| [Beads](guide_beads.md) | [contents summary — written in Task N] |
```

Use `[contents summary — written in Task N]` as a placeholder if the new guide has not been written yet. Update the row once the new guide is complete.

- [ ] **Step 2.6: Decide fate of `docs/MMA_Support/*`**

Options:
- (a) Keep as legacy, add a "Legacy MMA Reference" section to the index that links them
- (b) Merge into `docs/guide_mma.md` and delete the MMA_Support directory
- (c) Leave as-is, not linked

Default: (a) — keep as legacy, add a "Legacy MMA Reference (Deprecated)" section at the bottom of the index. This preserves historical context without confusing new readers.

- [ ] **Step 2.7: Verify every link in the modified file resolves**

For every `[text](./relative/path)` in the updated `docs/Readme.md`:
- Use `manual-slop_search_files` to confirm the target exists
- If broken, either fix the link or remove the row

- [ ] **Step 2.8: Commit**

```powershell
git -C C:\projects\manual_slop add docs/Readme.md
git -C C:\projects\manual_slop commit -m "docs(index): link guide_context_curation and guide_shaders_and_window; add legacy MMA section"
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Linked previously-unlinked guides. Added Legacy MMA Reference section per gap analysis decision. All cross-doc links verified." $_ }
```

---

## Task 3: Rewrite `docs/guide_architecture.md`

**Files:**
- Modify: `docs/guide_architecture.md` (current size ~34.5K)
- Reference: `src/gui_2.py`, `src/ai_client.py`, `src/multi_agent_conductor.py`, `src/dag_engine.py`, `src/events.py`, `src/app_controller.py`, `src/api_hooks.py`

**Scope:** Cover all threading domains, all event types, all state machines, the Execution Clutch HITL flow, multi-provider AI client architecture, caching strategies, and any new subsystems that interact with these (RAG retrieval, Beads sync, Hot Reload lifecycle hooks).

- [ ] **Step 3.1: Pre-edit checkpoint**

```powershell
git -C C:\projects\manual_slop add .
```

- [ ] **Step 3.2: Read the current guide**

```powershell
# Use skeleton/summary first
manual-slop_get_file_summary path="C:\projects\manual_slop\docs\guide_architecture.md"
```

Then read sections as needed. The file is large (~34.5K) so use `manual-slop_get_file_slice` with explicit ranges.

- [ ] **Step 3.3: Audit the source code for changes since the last update**

For each major source file referenced:
- Use `manual-slop_get_git_diff path="<file>" base_rev="HEAD~30"` to see what changed in the last 30 commits
- Use `manual-slop_py_get_skeleton` and `manual-slop_py_get_code_outline` to map current structure
- Note any new classes, methods, events, state machines

- [ ] **Step 3.4: Identify which sections need rewriting**

Based on the diff, mark each section as:
- **Stale:** Needs rewrite
- **Missing:** Subsystem not covered at all
- **Current:** No changes needed

If you find that a major subsystem is missing (e.g., RAG integration with the event system, Beads lifecycle hooks, Hot Reload interaction with the threading model), add a new section to the guide.

- [ ] **Step 3.5: Rewrite stale and missing sections**

Apply the VEFontCache-Odin style:
- **Philosophy:** Mental model. Why does this subsystem exist? What problem does it solve? What are the trade-offs?
- **Architectural Boundaries:** Which thread/domain owns it? What are the interfaces? What cannot cross?
- **Implementation Logic:** State machines with full transition tables. Locking strategy. Event flow with sequence. Public class/function signatures.
- **Verification:** How is it tested? What edge cases are covered? What can fail?

For "textbook / purple-tomb fidelity": for every public class/function/event mentioned, state its signature, threading constraints, side effects, and at least one usage example.

- [ ] **Step 3.6: Validate all cross-doc links**

For every `[text](./relative/path)` in the modified file:
- Use `manual-slop_search_files` to confirm target exists
- If broken, fix the link

- [ ] **Step 3.7: Spot-check 3 random symbols against the source**

Pick 3 random public class/function names mentioned in the rewritten sections. Use `manual-slop_py_find_usages` to confirm the symbol exists in the source with the same name.

- [ ] **Step 3.8: Commit**

```powershell
git -C C:\projects\manual_slop add docs/guide_architecture.md
git -C C:\projects\manual_slop commit -m "docs(architecture): refresh for RAG, Beads, Hot Reload, and post-Feb-2026 changes"
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Rewrote [list specific sections]. Cross-referenced [list source files]. New sections: [list]. Decisions: [list any judgment calls]." $_ }
```

---

## Task 4: Rewrite `docs/guide_mma.md`

**Files:**
- Modify: `docs/guide_mma.md`
- Reference: `src/multi_agent_conductor.py`, `src/dag_engine.py`, `src/conductor_tech_lead.py`, `src/mma_prompts.py`, `src/models.py`

**Scope:** The 4-Tier MMA hierarchy, Ticket/Track/WorkerContext data structures, DAG engine (Kahn's algorithm, cycle detection, transitive blocking propagation), ConductorEngine execution loop, Tier 2 ticket generation, Tier 3 worker lifecycle with Context Amnesia, Tier 4 QA integration, token firewalling, model escalation. Add: persona assignment, RAG-augmented worker context, Beads-backed track state, Hot Reload integration with worker spawning.

- [ ] **Step 4.1: Pre-edit checkpoint**

```powershell
git -C C:\projects\manual_slop add .
```

- [ ] **Step 4.2: Read the current guide and source code**

Use `manual-slop_get_file_summary` for the guide, then `manual-slop_py_get_skeleton` for each source file.

- [ ] **Step 4.3: Audit changes since last update**

Use `manual-slop_get_git_diff` for each source file. Note: the MMA system has evolved substantially (personas, RAG, Beads, Hot Reload interaction).

- [ ] **Step 4.4: Identify stale / missing sections**

Pay particular attention to:
- **Persona integration:** How are personas assigned to MMA tiers? Where in the worker lifecycle?
- **RAG augmentation:** When does a worker receive RAG-retrieved context? How is the chunk selection made?
- **Beads integration:** Are tracks stored in Beads when Beads mode is active? How does the transition work?
- **Hot Reload interaction:** When a Tier 3 worker finishes and the GUI is reloaded, what happens to the worker's session?

- [ ] **Step 4.5: Rewrite stale and missing sections**

VEFontCache-Odin style. The DAG engine algorithms in particular should be explained step-by-step (Kahn's algorithm pseudocode, cycle detection using iterative DFS, cascade_blocks with transitive propagation).

- [ ] **Step 4.6: Validate all cross-doc links**

- [ ] **Step 4.7: Spot-check 3 random symbols against the source**

- [ ] **Step 4.8: Commit**

```powershell
git -C C:\projects\manual_slop add docs/guide_mma.md
git -C C:\projects\manual_slop commit -m "docs(mma): refresh for personas, RAG augmentation, Beads integration, Hot Reload interaction"
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Rewrote [sections]. Cross-referenced [files]. New sections: [list]." $_ }
```

---

## Task 5: Rewrite `docs/guide_tools.md`

**Files:**
- Modify: `docs/guide_tools.md` (current size ~22.9K)
- Reference: `src/mcp_client.py`, `src/api_hooks.py`, `src/api_hook_client.py`, `src/shell_runner.py`

**Scope:** All 26+ MCP tools (current count), the 3-layer security model (Allowlist Construction → Path Validation → Resolution Gate), the Hook API GET/POST endpoints, `ApiHookClient` method reference, the `/api/ask` synchronous HITL protocol, the shell runner. Add: any new tools added since Feb 2026 (RAG tools, Beads tools, tree-sitter Lua/GDScript/C# tools if implemented, persona tools, structural file editor tools).

- [ ] **Step 5.1: Pre-edit checkpoint**

```powershell
git -C C:\projects\manual_slop add .
```

- [ ] **Step 5.2: Read the current guide**

- [ ] **Step 5.3: Audit current tool inventory in `src/mcp_client.py`**

Use `manual-slop_py_get_skeleton` and `manual-slop_py_get_code_outline` to get the current list of registered tools. Count them. Compare to the count in the guide.

- [ ] **Step 5.4: For each tool, document or update its entry**

For every tool:
- **Signature:** Exact function signature
- **Security constraints:** Which of the 3 layers it passes through
- **Side effects:** What does it mutate? What does it return?
- **Edge cases:** Empty input, missing file, permission denied, etc.
- **Usage example:** At least one example showing the call site and expected return

If a tool is missing from the guide, add a full entry. If an entry is stale, rewrite it.

- [ ] **Step 5.5: Update the Hook API endpoint reference**

Use `manual-slop_py_get_skeleton` on `src/api_hooks.py` to get the current list of routes. For each route, document request/response format.

- [ ] **Step 5.6: Update the `ApiHookClient` method reference**

Use `manual-slop_py_get_class_summary` for the `ApiHookClient` class. Document each public method.

- [ ] **Step 5.7: Validate all cross-doc links**

- [ ] **Step 5.8: Spot-check 3 random symbols against the source**

- [ ] **Step 5.9: Commit**

```powershell
git -C C:\projects\manual_slop add docs/guide_tools.md
git -C C:\projects\manual_slop commit -m "docs(tools): refresh tool inventory, Hook API, and ApiHookClient reference"
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Updated tool count to [N]. Rewrote [sections]. New tool entries: [list]." $_ }
```

---

## Task 6: Rewrite `docs/guide_simulations.md`

**Files:**
- Modify: `docs/guide_simulations.md`
- Reference: `tests/conftest.py`, `simulation/sim_base.py`, `simulation/workflow_sim.py`, `simulation/user_agent.py`, `tests/mock_gemini_cli.py`, `src/api_hook_client.py`

**Scope:** The `live_gui` pytest fixture (lifecycle, readiness polling, failure path, teardown, session isolation via `reset_ai_client`), the Puppeteer pattern (8-stage MMA simulation), the mock provider strategy, the VerificationLogger, process cleanup (`kill_process_tree`), visual verification patterns. Add: any new test infrastructure added since Feb 2026 (extended simulations, async tool tests, discussion metrics tests, structural file editor tests, command palette tests).

- [ ] **Step 6.1: Pre-edit checkpoint**

```powershell
git -C C:\projects\manual_slop add .
```

- [ ] **Step 6.2: Read the current guide**

- [ ] **Step 6.3: Audit current simulation infrastructure**

Use `manual-slop_get_file_summary` on `tests/conftest.py` and each `simulation/*.py` file. Note any new fixtures, base classes, or patterns.

- [ ] **Step 6.4: Identify stale / missing sections**

- [ ] **Step 6.5: Rewrite stale and missing sections**

VEFontCache-Odin style. Particular attention to:
- The `live_gui` fixture's full lifecycle (startup → readiness polling → test execution → teardown)
- The mock provider's JSON-L protocol (input mechanisms, response routing, output protocol)
- Process cleanup for Windows (the `kill_process_tree` implementation)
- The new extended simulation patterns (if any)

- [ ] **Step 6.6: Validate all cross-doc links**

- [ ] **Step 6.7: Spot-check 3 random symbols against the source**

- [ ] **Step 6.8: Commit**

```powershell
git -C C:\projects\manual_slop add docs/guide_simulations.md
git -C C:\projects\manual_slop commit -m "docs(simulations): refresh test infrastructure, mock provider, and Puppeteer pattern"
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Rewrote [sections]. New content: [list]." $_ }
```

---

## Task 7: Refresh `docs/guide_context_curation.md` and `docs/guide_shaders_and_window.md`

**Files:**
- Modify: `docs/guide_context_curation.md` (current size ~8K)
- Modify: `docs/guide_shaders_and_window.md` (current size ~3.4K)
- Reference: `src/file_cache.py`, `src/summarize.py`, `src/outline_tool.py`, `src/summary_cache.py`, `src/fuzzy_anchor.py`, `src/shaders.py`, `src/bg_shader.py`, `src/imgui_scopes.py`

**Scope:** For `guide_context_curation.md`: skeleton/curated/targeted view algorithms, fuzzy anchor algorithm, summary cache strategy, file aggregation pipeline, view modes. For `guide_shaders_and_window.md`: shader pipeline, custom window frame manipulation, pywin32 integration, NERV theme FX.

- [ ] **Step 7.1: Pre-edit checkpoint**

```powershell
git -C C:\projects\manual_slop add .
```

- [ ] **Step 7.2: Read both guides**

- [ ] **Step 7.3: Audit changes in referenced source files**

- [ ] **Step 7.4: Rewrite stale sections in `guide_context_curation.md`**

- [ ] **Step 7.5: Commit `guide_context_curation.md`**

```powershell
git -C C:\projects\manual_slop add docs/guide_context_curation.md
git -C C:\projects\manual_slop commit -m "docs(context-curation): refresh view algorithms and fuzzy anchor"
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Rewrote [sections]. Cross-referenced [files]." $_ }
```

- [ ] **Step 7.6: Rewrite stale sections in `guide_shaders_and_window.md`**

- [ ] **Step 7.7: Commit `guide_shaders_and_window.md`**

```powershell
git -C C:\projects\manual_slop add docs/guide_shaders_and_window.md
git -C C:\projects\manual_slop commit -m "docs(shaders): refresh shader pipeline and window frame"
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Rewrote [sections]. Cross-referenced [files]." $_ }
```

- [ ] **Step 7.8: Validate all cross-doc links in both files**

---

## Task 8: Refresh `docs/guide_meta_boundary.md`

**Files:**
- Modify: `docs/guide_meta_boundary.md` (current size ~4.6K)
- Reference: `scripts/mma_exec.py`, `scripts/claude_mma_exec.py`, `scripts/tool_call.py`, `scripts/mcp_server.py`, `mma-orchestrator/SKILL.md`, `.gemini/`, `.claude/`, `.opencode/`

**Scope:** The Application domain (Strict HITL — `gui_2.py`, `ai_client.py`, `multi_agent_conductor.py`, `dag_engine.py`) vs the Meta-Tooling domain (agent skill files and orchestration scripts). Inter-Domain Bridges (`cli_tool_bridge.py`, `claude_tool_bridge.py`). The `GEMINI_CLI_HOOK_CONTEXT` environment variable. Safety model separation.

- [ ] **Step 8.1: Pre-edit checkpoint**

```powershell
git -C C:\projects\manual_slop add .
```

- [ ] **Step 8.2: Read the current guide and the meta-tooling files**

- [ ] **Step 8.3: Rewrite stale sections**

Pay attention to:
- Is `claude_mma_exec.py` still in active use? (User indicated Claude is no longer the primary toolchain — may be vestigial.)
- Is `cli_tool_bridge.py` still in active use?
- Are there new meta-tooling scripts not yet documented?

- [ ] **Step 8.4: Validate all cross-doc links**

- [ ] **Step 8.5: Commit**

```powershell
git -C C:\projects\manual_slop add docs/guide_meta_boundary.md
git -C C:\projects\manual_slop commit -m "docs(meta-boundary): refresh Application vs Meta-Tooling domain separation"
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Rewrote [sections]. Cross-referenced [files]." $_ }
```

---

## Task 9: Update `Readme.md` (top-level)

**Files:**
- Modify: `Readme.md` (current size ~15.5K)
- Reference: every `docs/guide_*.md` (for the new Subsystem Index)

**Scope:** Add a "Module by Domain" reference table (links to each guide), a "Subsystem Index" (cross-references each major feature to its dedicated guide), update setup prerequisites (Beads CLI, Dolt, ChromaDB, etc.), update the Tech Stack section to reflect current dependencies.

- [ ] **Step 9.1: Pre-edit checkpoint**

```powershell
git -C C:\projects\manual_slop add .
```

- [ ] **Step 9.2: Read the current `Readme.md`**

- [ ] **Step 9.3: Add a "Module by Domain" section**

Insert a table that links to each `docs/guide_*.md`:

```markdown
## Module by Domain

For deep dives into each subsystem, see the dedicated guide:

| Subsystem | Guide |
|---|---|
| Threading, events, AI client, HITL | [docs/guide_architecture.md](docs/guide_architecture.md) |
| 4-Tier MMA, DAG, worker lifecycle | [docs/guide_mma.md](docs/guide_mma.md) |
| MCP tools, Hook API, shell runner | [docs/guide_tools.md](docs/guide_tools.md) |
| Test infrastructure, mock provider, Puppeteer | [docs/guide_simulations.md](docs/guide_simulations.md) |
| Skeleton/curated/targeted views, fuzzy anchors | [docs/guide_context_curation.md](docs/guide_context_curation.md) |
| Shader pipeline, custom window frame | [docs/guide_shaders_and_window.md](docs/guide_shaders_and_window.md) |
| Application vs Meta-Tooling domain | [docs/guide_meta_boundary.md](docs/guide_meta_boundary.md) |
| [RAG, Beads, etc. once new guides exist] | [docs/guide_rag.md](docs/guide_rag.md) |
```

- [ ] **Step 9.4: Add a "Subsystem Index" section**

A cross-reference of every major feature to its dedicated guide. Use the gap analysis from Task 1 as the source.

- [ ] **Step 9.5: Update setup prerequisites**

Check the current `pyproject.toml` (use `manual-slop_get_file_summary`) and confirm the README's prerequisites are accurate. Add any missing dependencies (e.g., `chromadb` for RAG, `dolt` for Beads).

- [ ] **Step 9.6: Update the Tech Stack section**

Add providers (MiniMax if not already there), new SDKs (any new ones), new tooling (e.g., ChromaDB).

- [ ] **Step 9.7: Commit**

```powershell
git -C C:\projects\manual_slop add Readme.md
git -C C:\projects\manual_slop commit -m "docs(readme): add Module by Domain, Subsystem Index, and updated setup"
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "Added Module by Domain table. Added Subsystem Index. Updated prerequisites to include [list]. Updated Tech Stack." $_ }
```

---

## Task 10: Write New Guides for Unlisted Subsystems

**Files:**
- Create (one per new guide): `docs/guide_<name>.md`
- Reference: the relevant `src/<module>.py` and tests

**Scope:** Per the gap analysis from Task 1, write new guides for any subsystem that:
1. Is explicitly listed in `conductor/product.md`
2. Does NOT have a corresponding guide yet
3. Is substantial enough to warrant a dedicated guide (>500 lines of code in the primary module)

**Likely candidates** (confirm via gap analysis):
- RAG (`docs/guide_rag.md`) — `src/rag_engine.py`
- Beads (`docs/guide_beads.md`) — `src/beads_client.py`
- Hot Reload (`docs/guide_hot_reload.md`) — `src/hot_reloader.py`
- Discussion Metrics & Compression (`docs/guide_discussion_metrics.md`) — `src/ai_client.py` (relevant section)
- Command Palette (`docs/guide_command_palette.md`) — `src/gui_2.py` (relevant section)
- Structural File Editor (`docs/guide_structural_editor.md`) — `src/gui_2.py` (relevant section)
- NERV Theme (`docs/guide_nerv_theme.md`) — `src/theme_nerv.py`, `src/theme_nerv_fx.py`

- [ ] **Step 10.1: Pre-edit checkpoint**

```powershell
git -C C:\projects\manual_slop add .
```

- [ ] **Step 10.2: For each new guide (one per subsystem), follow this per-subsystem workflow**

For each subsystem in the gap analysis's "Subsystems Without Dedicated Guides" table:

**10.2.1: Read the source module(s)**
- Use `manual-slop_py_get_skeleton` and `manual-slop_py_get_code_outline` first
- Read specific sections via `manual-slop_get_file_slice` for implementation details

**10.2.2: Read any existing tests for the subsystem**
- Use `manual-slop_get_file_summary` on the relevant `test_*.py` files
- Note what's tested (gives you the public API surface)

**10.2.3: Write the new guide in VEFontCache-Odin style**
- **Philosophy:** What problem does this subsystem solve? What design alternatives were considered?
- **Architectural Boundaries:** Which thread/domain owns it? What are the public interfaces? What cannot cross?
- **Implementation Logic:** State machines, algorithms step-by-step, public class/function signatures with side effects, threading constraints
- **Verification:** How is it tested? What edge cases? What can fail?

**10.2.4: Commit per-guide**
```powershell
git -C C:\projects\manual_slop add docs/guide_<name>.md
git -C C:\projects\manual_slop commit -m "docs(<name>): new guide for [subsystem]"
git -C C:\projects\manual_slop log -1 --format="%H" | ForEach-Object { git -C C:\projects\manual_slop notes add -m "New guide covering [subsystem]. Cross-referenced [files]. Public API surface documented." $_ }
```

**10.2.5: Update `docs/Readme.md` to link the new guide**
- Go back to Task 2's modified `docs/Readme.md` and update the placeholder row for this guide with the real "[contents summary]"
- Commit as a separate small commit: `docs(index): finalize [subsystem] guide link`

- [ ] **Step 10.3: Validate all cross-doc links across all new guides**

For every `[text](./relative/path)` in any new guide, verify the target exists.

---

## Task 11: Sub-Track 1 Verification

**Files:**
- Read: every modified `docs/guide_*.md` and `Readme.md`

- [ ] **Step 11.1: Cross-link audit**

For every modified markdown file, run a manual grep for `[text](./relative/path)` and verify each target exists via `manual-slop_search_files`.

- [ ] **Step 11.2: Symbol parity spot-check**

For 3 random public symbols mentioned in each rewritten guide, use `manual-slop_py_find_usages` to confirm the symbol exists with the same name in the source.

- [ ] **Step 11.3: Subsystem coverage check**

For every feature listed in `conductor/product.md`, confirm either (a) a dedicated guide exists, or (b) the feature is covered in a related guide with a link from `Readme.md`.

- [ ] **Step 11.4: Per-file commit verification**

Run `git log --oneline conductor/tracks/documentation_refresh_comprehensive_20260602/.. -- docs/ Readme.md` and confirm every file change has its own commit.

- [ ] **Step 11.5: Git note verification**

Run `git log --format="%H" -- docs/ Readme.md | ForEach-Object { git notes show $_ }` and confirm every commit has a non-empty git note.

- [ ] **Step 11.6: Phase completion checkpoint**

Per the project's Phase Completion Verification protocol in `conductor/workflow.md`:
- Run the automated test suite (or at least the docs-related tests, if any)
- Run the API hook verification if applicable
- Present the verification report to the user
- Get user sign-off
- Create the checkpoint commit: `conductor(checkpoint): Sub-Track 1 (docs layer refresh) complete`
- Attach the verification report as a git note

---

## Self-Review (after writing this plan)

1. **Spec coverage:** Sections 4.3-4.6 of the spec (Phase 1.3-1.6) are covered by Tasks 3-11. Phase 1.1 (Inventory) is Task 1. Phase 1.2 (Index update) is Task 2. Phase 1.5 (New guides) is Task 10. Phase 1.6 (Verification) is Task 11. ✓ All phases covered.
2. **Placeholder scan:** No "TBD" / "TODO" / "similar to Task N" markers. Specific file paths and commit commands throughout. ✓
3. **Type/symbol consistency:** Tasks reference consistent file paths, module names, and symbol names throughout. The VEFontCache-Odin pattern is applied consistently. ✓
4. **Risk check:** Pre-edit checkpoints, per-file commits, and git notes mitigate the codebase-evolving-underneath risk. Manual link validation mitigates broken links. User sign-off at the end of each sub-track is enforced via the Phase Completion Verification protocol. ✓