Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs(roadmap): add pre-cut documentation why/when pass as item 8

AkitaOnRailsdc310cdee0d3
diff --git a/docs/ROADMAP-2.0.md b/docs/ROADMAP-2.0.md
index 83cf8821..39fa2d7a 100644
--- a/docs/ROADMAP-2.0.md
+++ b/docs/ROADMAP-2.0.md
@@ -194,10 +194,32 @@ the final surface, not a moving one.
- Tests: each status line gets a test that breaks the underlying state
and proves the line changes (logic broken, never a destination).
+## Item 8 - Documentation why/when pass (pre-cut)
+
+*Why:* feature docs written alongside code default to "what it does";
+readers deciding whether to ADOPT a feature need "why it exists",
+"when to reach for it" (and when not to), and a real-world example
+showing the possibility — the way `docs/local-embeddings.md` leads
+with the egress/paraphrase-recall story before the mechanics.
+
+- Sweep every user-facing doc (README sections, docs/*.md, the
+ config template comments) and grade each feature's coverage: what /
+ why / when / example. Fix the gaps — a short scenario ("two
+ teammates on one server", "resuming on the laptop what the desktop
+ left off", "asking what we knew about X before the rewrite") beats a
+ flag list.
+- Real examples over abstractions: pick from this project's own
+ history where possible (the eval harness catching the FTS5 bug is a
+ better typed-edges/`contradicts` story than an invented one).
+- When-not-to guidance is part of honesty: every feature doc names the
+ case where the simpler default is the right call.
+- Runs after items 1-6 so it covers the final surface, alongside the
+ item 7 status audit.
+
## Sequencing and the cut
```
-1 harness → 2 OKF (+migration) → 3 typed edges → 4 temporal → 5 local-embed → 6 abstraction → 7 status audit
+1 harness → 2 OKF (+migration) → 3 typed edges → 4 temporal → 5 local-embed → 6 abstraction → 7 status audit → 8 docs why/when pass
```
Each lands on main individually gated (fmt, clippy -D warnings, full