# Comprehensive Documentation Refresh

**Date:** 2026-06-02
**Status:** Draft (pending review)
**Parent Track:** `documentation_refresh_comprehensive_20260602`
**Sub-Tracks:** 3 (sequential with one parallel pair)

---

## 1. Context & Motivation

Manual Slop is a local GUI orchestrator for LLM-driven coding sessions. Since the last documentation refresh track (`documentation_refresh_20260224`, completed February 2026), the codebase has grown substantially:

- **New subsystems** without dedicated guides: Beads mode (Dolt-backed issue tracking), RAG (ChromaDB + multi-source retrieval), Hot Reload (state-preserving module reloading), Discussion Metrics & Compression, Command Palette, Structural File Editor (unified AST inspector + slice editor)
- **New language support** via tree-sitter: C, C++ (already in docs), plus planned Lua, GDScript, C# (in backlog)
- **Two new guide files** that exist but are not linked from the docs index: `docs/guide_context_curation.md`, `docs/guide_shaders_and_window.md`
- **Drift in agent config files** (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`): the three files overlap on Session Startup, Conductor System, MMA tiers, and anti-patterns; no single source of truth
- **CLAUDE.md is largely vestigial** — Claude Code is no longer the primary toolchain, but the file still receives content updates
- **AGENTS.md contains rich guidance content** that should live in `mma-orchestrator/SKILL.md` or `conductor/workflow.md`, not as a surface-level orientation file

The user has explicitly stated two goals for this refresh:

1. **Human-facing docs (`./docs/`, READMEs)** must reach **textbook / Microsoft "purple-tomb" SDK documentation** fidelity. Every detail: state machines, public APIs, threading constraints, algorithms. No hand-waving, no "left to the reader." A human should be able to use the tool AND maintain/extend the codebase from the docs alone.
2. **Agent-facing docs** (`AGENTS.md`, `GEMINI.md`, skill files in `.agents/`, `.gemini/`) must follow an **explicit divergence model** with no content duplication. `AGENTS.md` becomes a thin pointer; `CLAUDE.md` is deprecated; `GEMINI.md` stays Gemini-CLI-specific.

This refresh is **documentation-only** (no new code, no new tooling, no new scripts). Drift control after the refresh is manual via the track's verification step.

---

## 2. Scope Boundaries

### In Scope

- Top-level `Readme.md`
- `docs/Readme.md` and all `docs/guide_*.md` files
- `conductor/product.md`, `conductor/product-guidelines.md`, `conductor/tech-stack.md`, `conductor/workflow.md`, `conductor/index.md`
- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`
- Light verification pass (read each, confirm role accuracy, fix obvious drift; do NOT rewrite wholesale) on `.agents/skills/*/SKILL.md`, `mma-orchestrator/SKILL.md`, `.gemini/...` mirrors
- Per-file atomic git commits with git notes attached as rationale trails

### Out of Scope

- Source code changes (a separate agent is making code modifications)
- New lint/check scripts (drift control is manual)
- New `docs/` files beyond what's required to document new subsystems
- Re-architecting the conductor system itself
- Removing CLAUDE.md (kept as a stub for compatibility)
- Visual diagrams (ASCII is fine; no image generation)
- Translating the docs to other languages

---

## 3. Track Architecture

The parent track `documentation_refresh_comprehensive_20260602` is a coordinator: it registers the three sub-tracks in `conductor/tracks.md`, sequences them, and produces a final verification report. Each sub-track is an independent conductor track with its own `spec.md`, `plan.md`, and `metadata.json`.

### Dependency Graph

```
Sub-Track 1: docs_layer_refresh
       │
       ├──> Sub-Track 2: conductor_docs_refresh
       │
       └──> Sub-Track 3: agent_config_refresh
                       │
                       └──> Parent verification
```

Sub-Tracks 2 and 3 can run in parallel after Sub-Track 1 establishes the human-facing doc layer. The parent track does the final verification and creates the checkpoint commit.

### Execution Constraints (apply to all 3 sub-tracks)

- **No subagents.** Each sub-track is executed by a single agent (the user or the Tier 2 Tech Lead session) sequentially. No Tier 3 worker delegation, no Tier 4 QA delegation, no parallel worker execution.
- **Per-file atomic commits.** One file = one commit. The git note attached to each commit captures the rationale and the source files cross-referenced during the rewrite.
- **Pre-edit `git add .` checkpoint** before each file edit (protects against `git restore` mishaps).
- **Style baseline:** `conductor/product-guidelines.md` — VEFontCache-Odin pattern (Philosophy → Architectural Boundaries → Implementation Logic → Verification), high information density, structural parity between doc symbols and source code symbols.
- **Symbol parity:** Every class, function, method, and event named in the docs must match the source exactly. If the source uses `AsyncEventQueue`, the doc must use `AsyncEventQueue`, not "the event queue."
- **Link validation:** Every `[text](./relative/path)` link is manually verified via `manual-slop_search_files` to confirm the target exists. Cross-doc links must point to files that exist in this or a future sub-track.
- **No comments added to source code.** Documentation lives in `./docs/`, not inline.

---

## 4. Sub-Track 1: `docs_layer_refresh_20260602`

**Priority:** HIGHEST. This is the dominant work.

### File List

| File | Current Size | Notes |
|---|---|---|
| `Readme.md` | 15.5K | Main project README |
| `docs/Readme.md` | ~3K | Documentation index |
| `docs/guide_architecture.md` | 34.5K | Threading, events, AI client, HITL |
| `docs/guide_mma.md` | unknown | 4-tier hierarchy, DAG, worker lifecycle |
| `docs/guide_tools.md` | 22.9K | MCP tools, Hook API, shell runner |
| `docs/guide_simulations.md` | unknown | live_gui fixture, Puppeteer, mock provider |
| `docs/guide_context_curation.md` | 8K | Skeleton/curated/targeted views, fuzzy anchors |
| `docs/guide_shaders_and_window.md` | 3.4K | Shader pipeline, custom window frame |
| `docs/guide_meta_boundary.md` | 4.6K | Application vs Meta-Tooling domain |
| `docs/MMA_Support/*` | varies | Legacy MMA reference docs — review for archival or merge |

### Tasks (Phases)

**Phase 1.1: Inventory and Gap Analysis**
- Read each existing guide, summarize what subsystems it covers
- Identify subsystems in `conductor/product.md` that have NO corresponding guide
- Identify subsystems that DO have a guide but the guide is stale (e.g., does not cover features added since Feb 2026)
- Produce a gap table: subsystem → current guide → needed changes (rewrite / add / link from index / remove)

**Phase 1.2: Update the Documentation Index**
- Update `docs/Readme.md` so every `docs/guide_*.md` appears in the Guides table
- Currently unlinked: `docs/guide_context_curation.md`, `docs/guide_shaders_and_window.md`
- Decide fate of `docs/MMA_Support/*` (legacy archive or merge into `docs/guide_mma.md`)
- Commit: `docs(index): link guide_context_curation and guide_shaders_and_window`

**Phase 1.3: Rewrite Each Guide (one file at a time, per-file atomic commits)**
- For each guide, follow the per-file workflow:
  1. Read current source code (use `manual-slop_get_file_summary` and `manual-slop_py_get_skeleton`; do NOT read full files >50 lines)
  2. Read current `docs/MMA_Support/*` and `conductor/tracks/*/plan.md` for context on subsystems that have evolved
  3. Cross-reference `conductor/product.md` and `conductor/tech-stack.md` for the canonical feature/tech statement
  4. Identify what changed since the guide was last meaningfully updated
  5. Rewrite affected sections, preserving the VEFontCache-Odin style (Philosophy → Architectural Boundaries → Implementation Logic → Verification)
  6. Validate every internal `[link](./relative/path)` resolves
  7. Commit per-file with `docs(<scope>): <description>` message
  8. Attach git note with: source files cross-referenced, subsystems updated, any decisions made

**Phase 1.4: Update `Readme.md`**
- Add a "Module by Domain" reference table that links to each guide for deep dives
- Add a "Subsystem Index" section cross-referencing each major feature to its dedicated guide
- Update the screenshot/gallery references if needed
- Update setup instructions to reflect any new prerequisites (e.g., Beads CLI, Dolt)
- Commit per-section: `docs(readme): add module-by-domain reference table`, `docs(readme): add subsystem index`, `docs(readme): update setup prerequisites`, etc.

**Phase 1.5: Subsystems Without Guides (write new guides as needed)**
For each subsystem identified in 1.1 that lacks a guide, write a new `docs/guide_<name>.md` using the same per-file workflow. Likely candidates based on the gap analysis:
- RAG (`docs/guide_rag.md`) — vector store, chunking, multi-provider search
- Beads (`docs/guide_beads.md`) — Dolt integration, toolset, context compaction
- Hot Reload (`docs/guide_hot_reload.md`) — `HotReloader` lifecycle, state preservation, UI delegation pattern
- Discussion Metrics & Compression (`docs/guide_discussion_metrics.md`) — per-response token tracking, history compression strategy
- Command Palette (`docs/guide_command_palette.md`) — async context preview, fuzzy command resolution
- Structural File Editor (`docs/guide_structural_editor.md`) — unified AST inspector + slice editor
- NERV Theme (`docs/guide_nerv_theme.md`) — black void palette, CRT-style effects, status flickering

Each new guide must follow the same VEFontCache-Odin style and link from `docs/Readme.md` (which means the index update in 1.2 must accommodate them).

**Phase 1.6: Verification**
- `grep` for every internal link in every rewritten guide to confirm targets exist
- `grep` for stale feature references (e.g., "MMA 4-tier" without the recent persona, RAG, Beads integrations mentioned in `conductor/product.md`)
- Spot-check 3 random sections per guide against the corresponding source code
- Manual user review (per workflow.md Phase Completion Verification protocol)

### Acceptance Criteria

- Every `docs/guide_*.md` is referenced from `docs/Readme.md`
- Every internal cross-doc link resolves
- Every subsystem in `conductor/product.md` has a corresponding guide (either existing or newly written)
- Every public class, function, and event named in any guide matches the source code symbol exactly
- Every guide follows the VEFontCache-Odin pattern (Philosophy → Architectural Boundaries → Implementation Logic → Verification) with all four sections present where applicable
- "Textbook / purple-tomb fidelity" interpreted concretely: for every public class/function/event mentioned, the doc states its signature, threading constraints, side effects, and at least one usage example. Internal algorithms are explained step-by-step, not summarized. State machines include the full transition table
- Per-file commits exist for every change, with git notes attached

---

## 5. Sub-Track 2: `conductor_docs_refresh_20260602`

**Priority:** Medium. Sync the source-of-truth conductor docs to current state.

### File List

| File | Current Size | Notes |
|---|---|---|
| `conductor/product.md` | 23.1K | Product vision, feature list, use cases |
| `conductor/product-guidelines.md` | 6.6K | Style and process guidelines |
| `conductor/tech-stack.md` | unknown | Technology stack constraints |
| `conductor/workflow.md` | 25.2K | Task lifecycle, TDD protocol |
| `conductor/index.md` | 334 bytes | Conductor directory index |

### Tasks (Phases)

**Phase 2.1: Sync `conductor/product.md`**
- Cross-reference every feature claim in `product.md` against the actual codebase
- Add features that exist in code but are missing from `product.md` (Beads, RAG, Hot Reload, Discussion Metrics/Compression, Command Palette, Structural File Editor, NERV theme, persona editor, workspace profiles, etc.)
- Remove features that have been culled or replaced
- Update the "Primary Use Cases" section to reflect current usage patterns
- Commit per-section: `docs(product): sync MMA dashboard section`, `docs(product): add RAG feature`, etc.

**Phase 2.2: Sync `conductor/tech-stack.md`**
- Verify every entry corresponds to an actual Python dep (check `pyproject.toml` / `requirements.txt`) or an actual src/ module
- Add new dependencies: chromadb (RAG), dolt (Beads), any new ones
- Add new src/ modules: rag_engine.py, beads_client.py, hot_reloader.py, history.py, workspace_manager.py, etc.
- Commit per-section.

**Phase 2.3: Sync `conductor/workflow.md`**
- Verify the TDD protocol is followed by recent tracks (spot-check 3 recent tracks)
- Verify the Phase Completion Verification protocol is followed
- Verify the checkpointing protocol is followed
- Update any sections that have drifted from actual practice
- Commit per-section.

**Phase 2.4: Sync `conductor/product-guidelines.md`**
- Verify the AI-Optimized Python Style (1-space indent, no comments, type hints) is actually followed by recent code
- Verify the "Modular Controller Pattern" and "UI Delegation Pattern" are followed in `src/app_controller.py` and `src/gui_2.py`
- Verify the "Mandatory ImGui Verification" linter (`scripts/check_imgui_scopes.py`) is still the source of truth
- Update any sections that have drifted
- Commit per-section.

**Phase 2.5: Update `conductor/index.md`**
- If any new top-level conductor docs were added (e.g., `conductor/code_styleguides/` is referenced but not verified), link them
- Commit.

**Phase 2.6: Verification**
- `grep` for references to features that no longer exist
- `grep` for missing dependencies (every dep in `pyproject.toml` should appear in `tech-stack.md`)
- Spot-check 3 random claims per file
- Manual user review

### Acceptance Criteria

- Every feature in `conductor/product.md` corresponds to a real subsystem in `src/` or `tests/`
- Every entry in `conductor/tech-stack.md` is an actual dep or module
- `conductor/workflow.md` matches the actual workflow used by recent completed tracks
- `conductor/product-guidelines.md` matches the actual coding style used in `src/`
- `conductor/index.md` links to all relevant conductor files
- Per-file commits with git notes

---

## 6. Sub-Track 3: `agent_config_refresh_20260602`

**Priority:** Lower. Apply the explicit divergence model.

### File List

| File | Current Size | Notes |
|---|---|---|
| `AGENTS.md` | 5.4K | Universal agent orientation — target: thin pointer |
| `CLAUDE.md` | 6.7K | DEPRECATE to stub |
| `GEMINI.md` | 3.8K | Keep Gemini-CLI-specific content |
| `.agents/skills/mma-tier1-orchestrator/SKILL.md` | 2.4K | Light verification only |
| `.agents/skills/mma-tier2-tech-lead/SKILL.md` | 3.8K | Light verification only |
| `.agents/skills/mma-tier3-worker/SKILL.md` | unknown | Light verification only |
| `.agents/skills/mma-tier4-qa/SKILL.md` | 813 bytes | Light verification only |
| `.agents/skills/mma-orchestrator/SKILL.md` | 9.7K | Light verification only |
| `mma-orchestrator/SKILL.md` (root copy) | 9.3K | Light verification only |
| `.gemini/skills/*/SKILL.md` | varies | Light verification only (mirrors) |
| `.gemini/agents/*.md` | varies | Light verification only (mirrors) |
| `.claude/commands/*.md` | 9 files | Light verification only (legacy) |

### Tasks (Phases)

**Phase 3.1: Rewrite `AGENTS.md` to a thin pointer**

Target structure (estimated ~1K):

```markdown
# AGENTS.md

## What This Is
Manual Slop is a local GUI orchestrator for LLM-driven coding sessions. It bridges high-latency AI reasoning with a low-latency ImGui render loop via a thread-safe async pipeline; every AI-generated payload passes through a human-auditable gate before execution.

## Guidance for AI Agents
Detailed agent guidance lives in the following locations — read these directly, do not duplicate content here:

- **Operational workflow:** `conductor/workflow.md`
- **Code style and process:** `conductor/product-guidelines.md`
- **Tech stack and constraints:** `conductor/tech-stack.md`
- **Product context:** `conductor/product.md`
- **MMA orchestrator role:** `mma-orchestrator/SKILL.md`
- **Tier 1 (Orchestrator):** `.agents/skills/mma-tier1-orchestrator/SKILL.md`
- **Tier 2 (Tech Lead):** `.agents/skills/mma-tier2-tech-lead/SKILL.md`
- **Tier 3 (Worker):** `.agents/skills/mma-tier3-worker/SKILL.md`
- **Tier 4 (QA):** `.agents/skills/mma-tier4-qa/SKILL.md`

## Human-Facing Documentation
For understanding, using, and maintaining the tool, see `docs/Readme.md` and the guides it indexes.

## Critical Anti-Patterns
- Do not read full files >50 lines without first using `py_get_skeleton` or `get_file_summary`
- Do not modify the tech stack without updating `conductor/tech-stack.md` first
- Do not implement code directly as Tier 2 — delegate to Tier 3 workers
- Do not skip TDD — write failing tests before implementation
- Do not batch commits — commit per-task for atomic rollback
```

**Phase 3.2: Replace `CLAUDE.md` with a 1-line stub**

Target content:

```markdown
# CLAUDE.md

This project is no longer actively used with Claude Code. For project context, see `AGENTS.md`. The conductor system in `./conductor/` is the cross-tool abstraction and works with any agent toolchain.
```

(Keep the file as a stub to avoid breaking any external tooling that may still reference it.)

**Phase 3.3: Lightly refresh `GEMINI.md`**

- Verify it covers only Gemini-CLI-specific content (no shared content that should live in `AGENTS.md`)
- Update any stale references to features, models, or paths
- If any content was previously shared with `AGENTS.md` and has been relocated, update `GEMINI.md` to point to `AGENTS.md` instead
- Commit: `docs(gemini): refresh Gemini CLI orientation`

**Phase 3.4: Verify `.agents/skills/*/SKILL.md` and `.gemini/...` mirrors for coherence**

For each skill file:
- Read it; confirm it covers the role accurately
- Compare with the canonical role description in `mma-orchestrator/SKILL.md`
- If drift is found, fix it (small surgical edits)
- If the file is outdated, flag for a separate track — do not rewrite wholesale in this track
- Commit per file: `docs(skills): fix drift in tier1 orchestrator skill`

**Phase 3.5: Verify `.claude/commands/*.md` (legacy)**

- These exist for backward compatibility
- Lightly verify they still work and don't reference removed features
- Do not rewrite — they are legacy
- If a file is broken, flag for separate track

**Phase 3.6: Verification**
- `grep` for the section headers that should have been relocated (Session Startup, Conductor System, MMA 4-Tier, Anti-Patterns) across `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`
- Confirm each appears in at most one file (or in multiple files only as short pointers)
- Spot-check 2 random skills files against their canonical description
- Manual user review

### Acceptance Criteria

- `AGENTS.md` is ≤ 1.5K and contains only project orientation + pointers
- `CLAUDE.md` is ≤ 200 bytes and contains only the deprecation stub
- `GEMINI.md` contains only Gemini-CLI-specific content
- No section header appears in 2+ of these files unless it's a short pointer (≤3 lines)
- `.agents/skills/*/SKILL.md` and `.gemini/...` mirrors are verified for coherence
- `.claude/commands/*.md` legacy files are verified to not reference removed features
- Per-file commits with git notes

---

## 7. Parent Track: Final Verification

After all 3 sub-tracks complete, the parent track produces a final verification report:

1. **Cross-track link audit:** For every markdown file modified in any sub-track, run `grep` for `[text](./relative/path)` patterns and verify each target exists
2. **Symbol parity audit:** Spot-check 5 random symbols named in any doc against the source — confirm exact match
3. **Drift audit:** `grep` for the relocated section headers (`Session Startup`, `Conductor System`, `MMA 4-Tier`, `Anti-Patterns`, etc.) across `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` — confirm explicit divergence holds
4. **Subsystem coverage audit:** For every feature in `conductor/product.md`, confirm a corresponding guide exists in `docs/`
5. **User review gate:** Present the final verification report and request user sign-off per workflow.md Phase Completion Verification protocol

The parent track then creates a single checkpoint commit: `conductor(checkpoint): Comprehensive documentation refresh complete` and attaches the verification report as a git note.

---

## 8. Risks & Mitigations

| Risk | Mitigation |
|---|---|
| A source code change by the other agent makes a doc claim stale mid-refresh | Per-file atomic commits + pre-edit `git add .` checkpoint; if drift is found during a later file's rewrite, fix the earlier file in a follow-up commit |
| Scope creep — adding new guides balloons the track | The gap analysis in 1.1 is the gating step; new guides are written only for subsystems explicitly listed in `conductor/product.md` |
| The 3 sub-tracks drift in style consistency | Style baseline is `conductor/product-guidelines.md` (single source); reviewed by user per sub-track |
| Manual link validation misses broken links | Per-file commit immediately after each rewrite; a broken link is caught in the next file's cross-reference work |
| User reviews take long enough that the codebase evolves underneath | Sub-tracks are independent; each can resume from its last commit if interrupted |
| The legacy `CLAUDE.md` deprecation breaks external tooling | The file is kept as a 1-line stub, not removed; any external tooling that reads it will see a graceful pointer to `AGENTS.md` |

---

## 9. Out of Scope (Reminder)

- Source code changes
- New lint scripts (drift control is manual)
- Image/diagram generation
- Translations
- Removing CLAUDE.md
- Visual layout of the docs site (Manual Slop is a GUI app, not a docs site)

---

## 10. Success Criteria

The track is complete when:

1. All 3 sub-tracks have completed all their phases with per-file atomic commits and git notes
2. The parent track's verification report shows zero broken cross-doc links, zero symbol mismatches in spot-checks, and confirmed explicit divergence in agent config files
3. Every subsystem in `conductor/product.md` has a corresponding guide
4. `Readme.md`, `docs/Readme.md`, and every `docs/guide_*.md` is at textbook / purple-tomb fidelity (verified by user review)
5. `AGENTS.md` is a thin pointer document; `CLAUDE.md` is a deprecation stub
6. The user has signed off on the final verification report per workflow.md