manual_slop/docs/AGENTS.md

# ./docs/AGENTS.md (the agent-facing mirror)

**Status:** Agent-facing mirror of `docs/Readme.md` (the human-facing docs index, which is preserved as-is). For agents (any tier), this is the recommended first read for understanding the project's docs structure.
**Date:** 2026-06-12
**Cross-refs:** `docs/Readme.md` (human-facing); `AGENTS.md` (project root); the 6 styleguides in `conductor/code_styleguides/`.

> **What this is.** `docs/Readme.md` is the human-facing docs index. *This* file is the agent-facing equivalent: it organizes the 14 deep-dive guides under `docs/` by MMA tier, and it cross-references the canonical styleguides. The 2 files cover the same docs but with different audiences and different reading paths.
>
> **The reading path.** If you're an agent scoping a feature, read this file first; then read the 1-2 `guide_*.md` files for the layers your feature touches; then read the 1-2 styleguides for the patterns the feature uses. The expected reading time for a typical feature: 10-15 minutes.

---

## 0. The 4 memory dimensions (the cross-cutting lens)

The conversation data has 4 distinct memory dimensions. Most features touch 1-2; some touch 3. Use this lens to identify which dimension(s) your feature needs.

| # | Dim | Where it lives | Use when | Styleguide |
|---|---|---|---|---|
| 1 | **Curation** | `FileItem` + `ContextPreset` + Fuzzy Anchors | "How to render a file" | (the curation is per `docs/guide_context_curation.md`) |
| 2 | **Discussion** | `app.disc_entries` + branching + UISnapshot | "What was said in this chat" | (the discussion is per `docs/guide_architecture.md` §"Threading model") |
| 3 | **RAG** | `src/rag_engine.py` (ChromaDB) | "What similar content exists" (opt-in) | `conductor/code_styleguides/rag_integration_discipline.md` |
| 4 | **Knowledge** | `~/.manual_slop/knowledge/*.md` + per-file + digest | "What we learned from past sessions" | `conductor/code_styleguides/knowledge_artifacts.md` |

See `docs/guide_agent_memory_dimensions.md` for the full cross-cutting guide.

---

## 1. The 14 deep-dive guides (organized by MMA tier)

| Tier | Guide | What it covers | When to read |
|---|---|---|---|
| **T1** | `docs/guide_architecture.md` | Threading model; cross-thread state sync | When scoping any cross-cutting feature |
| **T1** | `docs/guide_meta_boundary.md` | The Application vs Meta-Tooling split | When scoping a Meta-Tooling-side feature |
| **T2** | `docs/guide_app_controller.md` | The headless controller; `AppState` dataclass | When implementing controller-side logic |
| **T2** | `docs/guide_ai_client.md` | The multi-provider LLM client | When implementing LLM-side logic |
| **T2** | `docs/guide_mma.md` | The 4-tier MMA orchestration | When implementing MMA-side logic |
| **T2** | `docs/guide_tools.md` | The MCP tool inventory + Hook API | When implementing MCP tools or Hook endpoints |
| **T2** | `docs/guide_mcp_client.md` | The 45 tools + 3-layer security | When implementing new MCP tools or sub-MCPs |
| **T3** | `docs/guide_context_curation.md` | Granular AST Control + Fuzzy Anchors + Structural File Editor | When implementing curation-side features |
| **T3** | `docs/guide_personas.md` | The unified agent profile model | When implementing persona-side features |
| **T3** | `docs/guide_rag.md` | The RAG subsystem | When implementing RAG-side features (rare; opt-in) |
| **T3** | `docs/guide_gui_2.md` | The ImGui application | When implementing GUI-side features |
| **All** | `docs/guide_testing.md` | The test suite architecture (251 test files; 7 conftest fixtures) | When writing any test |
| **All** | `docs/guide_command_palette.md` | The 33 commands + "Everything" mode | When implementing command-palette features |
| **NEW** | `docs/guide_knowledge_curation.md` | The knowledge memory guide (4th dim) | When implementing knowledge-side features |
| **NEW** | `docs/guide_caching_strategy.md` | Caching across providers; stable-to-volatile ordering; cache TTL GUI | When implementing cache-side features |
| **NEW** | `docs/guide_agent_memory_dimensions.md` | Cross-cutting: the 4 memory dimensions | When scoping any feature that touches memory |

---

## 2. The 6 canonical styleguides (the convention catalog)

| Styleguide | What it codifies | When to read |
|---|---|---|
| `conductor/code_styleguides/data_oriented_design.md` | The canonical DOD reference (Tier 0/1/2; 3 defaults to reject; 7-question simplification pass; 10-question self-check) | Before any non-trivial work |
| `conductor/code_styleguides/agent_memory_dimensions.md` | The 4 memory dimensions and when to use each | When the feature touches memory |
| `conductor/code_styleguides/rag_integration_discipline.md` | The conservative-RAG rule (opt-in; complements; provenance; no mutation; feature-gated; graceful failure) | When the feature uses RAG |
| `conductor/code_styleguides/cache_friendly_context.md` | Stable-to-volatile context ordering; the cache TTL GUI contract; the byte-comparison test | When the feature builds context or caches |
| `conductor/code_styleguides/knowledge_artifacts.md` | The knowledge harvest pattern (category files, provenance, sha256 ledger, digest regeneration) | When the feature uses the knowledge dim |
| `conductor/code_styleguides/feature_flags.md` | File presence ("delete to turn off") vs config flags vs CLI flags; when to use each | When adding a new feature toggle |

---

## 3. The per-tier reading path

### Tier 1 (Orchestrator) — what to read

For scoping a feature, understanding the architecture, and planning:

| Read | Why |
|---|---|
| `docs/guide_architecture.md` | The threading model; the cross-thread data flow |
| `docs/guide_meta_boundary.md` | The Application vs Meta-Tooling split (load-bearing) |
| `docs/guide_agent_memory_dimensions.md` | The 4 memory dimensions (which dim does my feature touch?) |
| `conductor/code_styleguides/data_oriented_design.md` | The 3 defaults to reject; the simplification pass; the final self-check |
| `AGENTS.md` (project root) | The project-root agent-facing rules |
| This file (`.docs/AGENTS.md`) | The docs structure |

**Tier 1 does NOT typically read:** `guide_*.md` for the specific subsystems (T2 reads those).

### Tier 2 (Tech Lead) — what to read

For track design, ticket generation, and architecture:

| Read | Why |
|---|---|
| All of Tier 1's reads | (foundational) |
| `docs/guide_app_controller.md` | The headless controller; the `_predefined_callbacks` and `_gettable_fields` registries |
| `docs/guide_ai_client.md` | The LLM client; the providers; the cache strategy |
| `docs/guide_mma.md` | The 4-tier MMA; the DAG engine; the worker pool |
| `docs/guide_tools.md` | The MCP tool inventory; the Hook API; the 3-layer security |
| `conductor/code_styleguides/agent_memory_dimensions.md` | (for memory-touching tracks) |
| `conductor/code_styleguides/cache_friendly_context.md` | (for context-building tracks) |

**Tier 2 does NOT typically read:** `guide_context_curation.md`, `guide_personas.md`, `guide_rag.md`, `guide_gui_2.md` (T3 reads those).

### Tier 3 (Worker) — what to read

For surgical implementation:

| Read | Why |
|---|---|
| All of Tier 2's reads (selectively) | (the system context) |
| The 1-2 `guide_*.md` files for the specific layers the ticket touches | (the implementation surface) |
| The 1-2 `code_styleguides/...md` files for the patterns the ticket uses | (the convention) |
| The ticket itself (`conductor/tracks/<id>/plan.md`) | (the specific task) |

**Tier 3 reads in depth, not in breadth.** A typical T3 worker reads 2-4 docs total.

### Tier 4 (QA) — what to read

For error analysis and bug reproduction:

| Read | Why |
|---|---|
| All of Tier 2's reads (selectively) | (the system context) |
| The 1-2 `guide_*.md` files for the failing layer | (the reproduction surface) |
| The test file (if any) | (the verification surface) |
| The audit scripts (`scripts/audit_*.py`) | (the static analysis surface) |

**Tier 4 reads narrowly.** The bug is in 1-2 files; the read is in 1-2 docs.

---

## 4. The 4 memory dimensions (the cross-cutting lens, in detail)

Most features touch 1-2 dimensions. Use this decision tree:

```
Q: What is the *data* the feature needs?
   │
   ├── "How to render a file"          ──► Curation (FileItem)
   ├── "What was said in this chat"     ──► Discussion (disc_entries)
   ├── "What similar content exists"    ──► RAG (RAGEngine.search)  [opt-in]
   └── "What we learned from past runs" ──► Knowledge (knowledge/digest.md)
```

**Pick the matching dimension.** If the feature needs 2+, use 2+ — but be explicit about which is *primary* and which is *secondary*.

**The wrong shape for the right question is a common mistake:**
- "Where does X happen?" → RAG (semantic search)
- "How do I configure how file Y is rendered?" → Curation (FileItem)
- "What was the user asking about 3 turns ago?" → Discussion (disc_entries)
- "What did we decide last time about Z?" → Knowledge (digest)

See `docs/guide_agent_memory_dimensions.md` for the full cross-cutting guide.

---

## 5. The caching strategy (the cross-cutting concern)

If the feature builds the initial context (in `aggregate.py:run`) or calls the LLM (in `ai_client.py:send`), the cache strategy matters.

**The 12-layer model:**

| # | Layer | Stable across turns? | Where the cache hits |
|---|---|---|---|
| 1-7 | Role instructions, function-calling schema, tool descriptions, system prompt, persona, project context, knowledge digest | **YES** (cacheable) | Anthropic `cache_control`, Gemini `cachedContent`, OpenAI implicit |
| 8-12 | Discussion metadata, active preset, per-file details, prior tool results, user message | **NO** (per turn) | NOT cached |

**The byte-comparison test** (the design contract for the stable prefix):

```python
def test_aggregate_stable_to_volatile_ordering():
    """The first N characters of the context should be identical across turns
    of the same conversation, when no stable-layer inputs change."""
    ...
```

**The provider-specific TTLs:**

| Provider | Default TTL | Configurable? |
|---|---|---|
| Anthropic ephemeral | 5 min | yes (per-provider control surface) |
| Gemini explicit | 1 h | yes (per-discussion override) |
| OpenAI implicit | 5-10 min (provider-managed) | no |

**The GUI exposure** is a "Caching" Operations Hub sub-panel (per the v2.3 §5.3 sketch). See `docs/guide_caching_strategy.md` for the full guide and `conductor/code_styleguides/cache_friendly_context.md` for the styleguide.

---

## 6. The knowledge harvest (the durable layer)

The 4th memory dimension (knowledge) is *opt-in but encouraged* — it's the durable, user-editable, provenance-aware store of facts / decisions / questions / playbooks / per-file notes.

**The directory layout** (per the user's `~/.manual_slop/knowledge/`):

```
knowledge/
├── facts.md           # - {statement} {provenance}
├── decisions.md       # - {statement, reason} {provenance}
├── questions.md       # - {question} {provenance}
├── playbooks.md       # - **{name}**: {steps} {provenance}
├── tasks.md           # ## Open / ## Done
├── files/{file_id}.md # per-file notes (keyed by inode)
├── digest.md          # bounded 4KB; the projection; "delete to turn off"
├── ledger.json        # sha256-of-content audit log
└── prompts/harvest-conversation.md  # user-editable
```

**The harvest CLI:** `python -m src.knowledge_harvest [--apply] [--no-harvest] [--max-harvest-bytes N]`. Default: dry-run.

**The LLM output is strict JSON** (no prose, no markdown fence) with 7 categories. The retry budget is 2 attempts.

**The "delete to turn off" pattern:** `rm ~/.manual_slop/knowledge/digest.md` → no `{knowledge}` block injected. Re-enable by running the harvest.

See `docs/guide_knowledge_curation.md` for the full guide and `conductor/code_styleguides/knowledge_artifacts.md` for the styleguide.

---

## 7. The RAG discipline (the opt-in fuzzy dimension)

RAG is the *fuzzy semantic search* dimension. It's *opt-in* (default-off in new projects). The 6 rules:

1. **Opt-in.** Default-off in new projects
2. **Complements; never replaces.** RAG is one of 4 dimensions, not a substitute
3. **Provenance required.** Every result shows file + chunk
4. **No mutation.** RAG results never write to `disc_entries`, `FileItem`, or disk
5. **Feature-gated.** A feature must explicitly request RAG in its scope
6. **Graceful failure.** Failed search returns empty; the request continues

See `docs/guide_rag.md` for the full RAG guide and `conductor/code_styleguides/rag_integration_discipline.md` for the styleguide.

---

## 8. The feature flag patterns (when to use what)

When adding a new feature with an "on/off" toggle, choose the right pattern:

| Pattern | When to use | Example |
|---|---|---|
| **File presence** ("delete to turn off") | The feature produces a side artifact; the user might want to clean up by `rm`-ing it | `~/.manual_slop/knowledge/digest.md` |
| **Config flag** | The feature is always on; the flag is a persistent preference | `[ai_settings.toml] rag.enabled` |
| **CLI flag** | The feature is invoked from the CLI; the flag is a one-shot override | `python -m src.knowledge_harvest --apply` |
| **Track metadata flag** | The track's implementation uses a feature; this is *static documentation* | `metadata.json`: `{"uses_rag": true}` |

See `conductor/code_styleguides/feature_flags.md` for the full guide.

---

## 9. The cross-cutting principles (the data-oriented foundation)

All 14 docs and 6 styleguides share the same foundation (per `data_oriented_design.md`):

- **The data is the thing.** The conversation, the file items, the knowledge digest — these are the source of truth
- **Behavior is transformation over data.** Not object graphs; not hidden state; not opaque handles
- **Avoid hidden mutable state.** Errors are data, not exceptions. State is on disk, not in memory
- **Separate durable artifacts from temporary execution.** Workers are disposable; artifacts are durable
- **Optimize the shape, availability, and maintenance of the data.** Editable, provenance-aware, user-editable

When in doubt, read `conductor/code_styleguides/data_oriented_design.md` first.

---

## 10. The reading path (the 1-page summary)

For an agent scoping a feature:

1. **Read this file** (10 min)
2. **Read the 1-2 `guide_*.md`** for the layers your feature touches (5-10 min each)
3. **Read the 1-2 `code_styleguides/...md`** for the patterns your feature uses (5-10 min each)
4. **Read the ticket** (`conductor/tracks/<id>/plan.md`) for the specific task (variable)

Total: 20-45 min for a typical feature. The investment pays back across the feature's lifetime.

If a guide is missing or stale, that's a bug; file a docs issue (or update the guide inline, per the project's "edit the source of truth, not this file" pattern).

End of agent-facing mirror.