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):

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.