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 (curation / discussion / RAG / knowledge). Most features touch 1-2; some touch 3. Use this lens to identify which dimension(s) your feature needs.

**The full canonical 4-dim table is in `conductor/code_styleguides/agent_memory_dimensions.md` §0** (with the SSDL shape tag per dim). The cross-cutting guide is `docs/guide_agent_memory_dimensions.md`.

**The one-line summary:** curation is per-file structural; discussion is per-turn conversational; RAG is opt-in semantic; knowledge is per-project durable. Pick the matching dimension; don't reach for the wrong shape.

---

## 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:** the full table is in `conductor/code_styleguides/cache_friendly_context.md` §1. The short version: layers 1-7 (role, schema, tools, system prompt, persona, project context, knowledge digest) are byte-identical across turns and cacheable; layers 8-12 (discussion metadata, active preset, per-file details, prior tool results, user message) are per-turn and NOT cached. Cache boundary is at layer 7/8.

**The byte-comparison test** (the design contract for the stable prefix): the test in `tests/test_aggregate_caching.py` ensures the first N characters of the context are identical across turns. The implementation is `aggregate.stable_prefix_length(ctrl) -> N`. See `conductor/code_styleguides/cache_friendly_context.md` §2.

**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. 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.

**The canonical reference is `conductor/code_styleguides/knowledge_artifacts.md` §0-§4** (the directory layout + the 5 category files + the digest + the ledger + the harvest workflow). The user-facing guide is `docs/guide_knowledge_curation.md`.

**The one-line summary:** the user can `rm ~/.manual_slop/knowledge/digest.md` to turn off the knowledge injection (file presence as the feature flag). Re-enable by running `python -m src.knowledge_harvest --apply`. The LLM output is strict JSON with 7 categories; the retry budget is 2 attempts.

---

## 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 canonical reference is `conductor/code_styleguides/rag_integration_discipline.md`** (the 6 rules: opt-in, complement, provenance, no mutation, feature-gated, graceful failure). The user-facing guide is `docs/guide_rag.md`.

---

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

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

**The canonical reference is `conductor/code_styleguides/feature_flags.md`** (file presence vs config flag vs CLI flag vs track metadata flag; the decision tree; the forbidden patterns). The short version:

- **File presence** ("delete to turn off") — the feature produces a side artifact; the user might want to clean up by `rm`-ing it (e.g., `~/.manual_slop/knowledge/digest.md`)
- **Config flag** — the feature is always on; the flag is a persistent preference (e.g., `[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.