# Docs Layer Gap Analysis

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

This analysis drives the Sub-Track 1 work in the parent track `documentation_refresh_comprehensive_20260602`.

---

## Existing Guides and Their Coverage

| Guide | Lines | Covers | Does NOT cover (gaps) |
|---|---|---|---|
| `docs/guide_architecture.md` | 824 | Threading model, events, AI client, HITL Execution Clutch, MMA Engine architecture, MCP allowlist, comms logging, telemetry, state machines | RAG integration with event system, Beads lifecycle hooks, Hot Reload interaction with threading model, Command Palette rendering details, NERV theme FX |
| `docs/guide_mma.md` | 470 | 4-tier MMA, Ticket/Track data structures, DAG engine, WorkerPool, ConductorEngine, Tier 2 ticket generation, Tier 3 worker lifecycle, Tier 4 QA, abort propagation, pause/resume, model escalation | Persona assignment to tiers, RAG-augmented worker context, Beads-backed track state, Hot Reload interaction with worker spawning, workspace profile auto-switching |
| `docs/guide_tools.md` | 489 | MCP Bridge 3-layer security, 26 native tools, Hook API endpoints, ApiHookClient, shell runner, parallel tool execution, session logging | New RAG tools, new Beads tools, new persona tools, new structural file editor tools, new cost tracker tools |
| `docs/guide_simulations.md` | 395 | `live_gui` fixture, Puppeteer pattern (8 stages), mock provider strategy, visual verification, supporting analysis modules | Extended simulations (RAG, Beads, Hot Reload), async tool tests, discussion metrics tests, structural file editor tests, command palette tests |
| `docs/guide_context_curation.md` | 273 | Granular AST control, fuzzy anchor slices, interactive AST tree masking, batch operations, context snapshotting, aggregation pipeline | Updates for new view modes (None, Outline, Sliced), updates for new Structural File Editor (unified AST inspector + slice editor), view presets |
| `docs/guide_shaders_and_window.md` | 33 | Hybrid shader injection (ImDrawList + PyOpenGL FBO), pure ImGui borderless window, event metrics integration | NERV theme shader effects, CRT scanline implementation, status flickering, pywin32-specific code |
| `docs/guide_meta_boundary.md` | 41 | Application domain vs Meta-Tooling domain, inter-domain bridges, `mcp_client.py` overlap, guidelines for future tiers | Whether `claude_mma_exec.py` is still in active use, whether `cli_tool_bridge.py` is still relevant, OpenCode and Gemini CLI superpowers/skills as meta-tooling |

---

## Subsystems Without Dedicated Guides

These subsystems are explicitly listed in `conductor/product.md` (or implied by major modules in `src/`) but lack dedicated guides:

| Subsystem | Primary module | Size | Recommendation |
|---|---|---|---|
| RAG | `src/rag_engine.py` | 10.9K | NEW: `docs/guide_rag.md` — substantial module, complex algorithms (vector store, chunking strategies, multi-provider search, ChromaDB integration) |
| Beads | `src/beads_client.py` | 2.7K | NEW: `docs/guide_beads.md` — Dolt integration, JSON-RPC protocol, `bd` CLI interaction, context compaction |
| Hot Reload | `src/hot_reloader.py` | 2.2K | NEW: `docs/guide_hot_reload.md` — state-preserving module reloading, UI delegation pattern, Ctrl+Alt+R trigger, error tint feedback |
| Personas | `src/personas.py` | 4.6K | NEW: `docs/guide_personas.md` — unified profile model, MMA tier assignment, tool bias integration, persona editor modal |
| NERV Theme | `src/theme_nerv.py`, `src/theme_nerv_fx.py` | 3K + 3.8K | NEW: `docs/guide_nerv_theme.md` — Black Void palette, CRT scanline implementation, status flickering, alert animations |
| Workspace Profiles | `src/workspace_manager.py` | 2.9K | NEW: `docs/guide_workspace_profiles.md` — docking layouts, named profiles, global/project scope inheritance, contextual auto-switch |
| Command Palette | `src/gui_2.py` (relevant section) | embedded | NEW: `docs/guide_command_palette.md` OR include in `guide_architecture.md` (Async Context Preview, fuzzy command resolution) |
| Discussion Metrics & Compression | `src/ai_client.py` (relevant section) | embedded | INCLUDE in `guide_architecture.md` rewrite — per-response token tracking, history compression strategy |
| Structural File Editor | `src/gui_2.py` (relevant section) | embedded | INCLUDE in `guide_context_curation.md` rewrite — unified AST inspector + slice editor |
| Tree-sitter (Lua, GDScript, C#) | `src/mcp_client.py` (planned) | planned | OUT OF SCOPE — these are in the backlog, not yet implemented |

---

## Existing Guides That Are Stale

| Guide | Last meaningful update | Stale sections (to rewrite) |
|---|---|---|
| `docs/guide_architecture.md` | Likely Feb 2026 (last doc refresh) | "MMA Engine Architecture" section (WorkerPool + ConductorEngine) — does not include persona assignment, RAG integration, Beads hooks, Hot Reload. "AI Client: Multi-Provider Architecture" section — does not include MiniMax provider. "Anthropic Cache Strategy" — needs verification against current implementation. |
| `docs/guide_mma.md` | Likely Feb 2026 | "Tier 3: Worker Lifecycle" — does not cover RAG-augmented context, persona-driven prompt construction, Beads track state. "ConductorEngine" — does not cover workspace profile auto-switching. |
| `docs/guide_tools.md` | Likely Feb 2026 | "Native Tool Inventory" — current count is uncertain. Need to verify each tool is documented. New tools likely missing. |
| `docs/guide_simulations.md` | Likely Feb 2026 | "Puppeteer Pattern" — may not include new test stages for RAG, Beads, Hot Reload. |
| `docs/guide_context_curation.md` | Likely May 2026 (Phase 6 tracks) | Mostly current. Verify against latest Phase 6 implementation. |
| `docs/guide_shaders_and_window.md` | Likely Feb 2026 | "Custom Shaders and Window Frame Architecture" — does not include NERV theme. |
| `docs/guide_meta_boundary.md` | Likely Feb 2026 | "Meta-Tooling" section — does not include `.gemini/skills/`, `.opencode/skills/`, or `mma-orchestrator/SKILL.md`. |

---

## Cross-Cutting Issues

- **Files in `docs/MMA_Support/*` not linked from `docs/Readme.md`:** All 12 files. They're legacy MMA reference docs from a previous architecture. Decision: keep as a "Legacy MMA Reference (Deprecated)" section at the bottom of the index.

- **Guides that reference each other via broken links:** None found in the initial scan. Will re-verify during each per-file rewrite.

- **Symbols in docs that don't match current source:** Will be caught by symbol parity spot-checks during each rewrite.

- **Tech-stack drift:** `guide_architecture.md` mentions "Gemini API, Anthropic API, DeepSeek" but the project now also has MiniMax. Update needed.

- **Provider model names:** `guide_architecture.md` may have stale model names (e.g., `gemini-3.1-pro-preview`, `gemini-3-flash-preview`, `gemini-2.5-flash-lite` are mentioned in `conductor/tech-stack.md`; verify they're documented in the architecture guide).

---

## Recommended Task Order (for Sub-Track 1)

1. **Task 1 (this analysis)** — done
2. **Task 2: Update `docs/Readme.md`** — link previously-unlinked guides, add legacy MMA section, add new guide placeholder rows
3. **Task 3: Rewrite `docs/guide_architecture.md`** — main architecture guide
4. **Task 4: Rewrite `docs/guide_mma.md`** — MMA guide
5. **Task 5: Rewrite `docs/guide_tools.md`** — tools guide
6. **Task 6: Rewrite `docs/guide_simulations.md`** — simulations guide
7. **Task 7: Refresh `guide_context_curation.md` and `guide_shaders_and_window.md`** — in parallel since they're independent
8. **Task 8: Refresh `docs/guide_meta_boundary.md`** — small file, do after the others
9. **Task 9: Update `Readme.md`** — after all guides are updated, so the new Subsystem Index is accurate
10. **Task 10: Write new guides** — RAG, Beads, Hot Reload, Personas, NERV Theme, Workspace Profiles, Command Palette. Per-guide atomic commits.
11. **Task 11: Verification** — cross-link audit, symbol parity, subsystem coverage, Phase Completion checkpoint

---

## Estimated Effort

| Task | Estimated commits | Estimated time (single agent) |
|---|---|---|
| Task 1: Gap analysis | 1 | done |
| Task 2: docs/Readme.md | 1 | 15-30 min |
| Task 3: guide_architecture.md | 1 | 1-2 hours (largest file, most subsystems) |
| Task 4: guide_mma.md | 1 | 45-60 min |
| Task 5: guide_tools.md | 1 | 1-1.5 hours (26+ tools to document) |
| Task 6: guide_simulations.md | 1 | 45-60 min |
| Task 7: guide_context_curation.md + guide_shaders_and_window.md | 2 | 30-45 min |
| Task 8: guide_meta_boundary.md | 1 | 15-30 min |
| Task 9: Readme.md | 1-3 (per section) | 30-45 min |
| Task 10: 7 new guides | 7-14 (per guide + index update) | 3-5 hours (textbook fidelity for new content) |
| Task 11: Verification | 1 (checkpoint) | 30-45 min |

**Total estimated time:** 8-13 hours of focused single-agent work, spread across many per-file atomic commits.

---

## Risks

1. **Code evolution during the track:** Another agent is making code modifications. Each per-file rewrite starts with a `git add .` pre-edit checkpoint and reads the current source state. If a subsystem is restructured mid-track, the rewrite may need a follow-up commit.

2. **Textbook / purple-tomb fidelity target:** This is ambitious. If we run out of time, we can ship a "good enough" pass on the main guides (3-6) and defer the new guides (10) to a follow-up track.

3. **CLAUDE.md and AGENTS.md divergence:** This is Sub-Track 3 work, but if `AGENTS.md` and `docs/Readme.md` have conflicting pointer targets, the drift will be visible. Defer that conflict resolution to Sub-Track 3.

---

**Gap analysis complete. Ready for Task 2.**
