Documentation & learning-experience overhaul (v13.1)

Update 2026-06-29: Grounding hardened to a 3-step discipline (memory-mine → use-the-tools → V-B-A) and the content rubric extended with the bar items the MemoryCore/KnowledgeBase arc proved (render-verified TD Mermaid · conceptual≠reference · current-paradigm · dual-audience). This is the bar-ensurance wiring for all subs.

Problem scope

learn/ (served via the portal → neomjs.com) is the primary adoption surface for humans AND AI, and it is the organism's weakest link. v13 shipped a real cross-family engineering institution — deployable multi-tenant around your codebase, on local OR remote models, self-healing so it runs unattended — behind ~1,300 merged PRs. But a reader entering from the top cannot understand what Neo is, why they'd want it, or how to deploy it. The failure is structure + comprehension + quality + freshness, in that priority order (verified 2026-06-29):

1. No comprehension path / broken IA.

• learn/benefits/ is ~19 flat items with no sub-structure — Body benefits (ObjectPermanence, Speed, MultiWindow…) and Brain benefits (AIEngineeringTeam, AgentMemory, DeployingTheAgentOS…) jumbled into one undifferentiated list, no "start here → what → why → how" reading order.
• Comprehension-first ordering is inverted: nobody reads cloud-deployment guides if they don't first understand what the Agent OS is and why they need it. Benefits + architecture comprehension come first; cloud deployment is the downstream payoff.

2. The top-level intro is mis-cast.

• benefits/Introduction.md ("The Application Engine for the AI Era") is fine as a Body/engine doc — but it is the main intro, so a first-time reader meets a Body-only, pre-v13 framing (no Brain, no Agent OS, no cloud; "four MCP servers"; Gemini-only). It needs to be renamed (→ ApplicationEngine.md), demoted under Body-benefits, and replaced at the front door by a new comprehension-first main intro.

3. Quality, not just freshness.

• benefits/AgentOSOnYourCodebase.md is ~2/10: vague capability prose, no concrete proof, missing the local-model + self-heal value. The cloud-deployment guides are weak (below the bar) and need real quality work, not just discoverability wiring.

4. Stale facts contradict the running system.

• Guides drift from reality (e.g. stale embedding-model/topology/server-count claims). Server counts, model names, topology, and version must match the deployed system.

5. Missing keystones.

• The v13.1 self-healing immune system (ADRs 0025/0026/0027) has no guide. The hard-won local-models achievement (gemma4 / qwen3 — privacy, zero API cost, on-prem / air-gap; a ~1,000-PR effort) has no first-class guide; the local-vs-remote model choice is scattered.

Why an Epic: this spans the learn/ information architecture, ~20 benefits docs, the core agentos/ guides, two net-new keystone guides, the entire cloud-deployment/ corpus, AND the portal-app learning navigation — many interdependent surfaces that must converge on one coherent, comprehension-first learning experience. Far beyond one PR; one accountable driver coordinating leaf subs.

Intended solution shape

A comprehension-first, top-down learning experience — a reader (human or AI) lands, immediately understands what Neo is and why it matters, then descends by choice through benefits → architecture → deployment, guided by a real navigation tree.

• Information architecture first. Restructure the Benefits nav into coherent groups — Start Here, The Brain (Agent OS), The Body (Application Engine) — with a deliberate reading order + a real tree nav matching tree.json + prev/next (portal renders this out of the box).
• A new main intro opening on the two-hemisphere organism and "why you need it"; the Application-Engine content preserved as a renamed Body-benefit.
• Comprehension before deployment. Benefits + architecture establish what/why; cloud-deployment is the downstream payoff, itself raised in quality.
• Two keystones authored: the v13.1 self-healing / immune-system guide, and the local-vs-remote model-provider guide.
• The framing spine: the Brain runs in two topologies of one organism — LOCAL (single developer, on-machine; nothing to "deploy") and CLOUD (shared multi-tenant team service; the Deployment Cookbook is cloud-only). There is no "migration" between them — they are two deployment modes. Orthogonal to the two model modes (local gemma4/qwen3; remote Gemini). The excitement hook: a team's shared Memory Core makes the team's reasoning compound.
• Brain-guide moat (must be covered): the disciplines built ON Memory Core — /context-recovery (reconstruct lane state from MC recency + semantic + summaries + A2A after the context window compacts) and /memory-mining (don't re-derive prior reasoning) — are the survive-the-finite-window story, the real answer to "the context window is not a memory system." A2A is the mailbox that lives in MC; treat it first-class, not a footnote.

Surface-by-surface decomposition lives in the linked sub-issues (added incrementally), each a one-PR-deliverable leaf with its own ACs. Driving / planning / cross-family review: @neo-opus-grace. Execution: @neo-gpt (Euclid).

Out of scope

• The ai/-folder code architecture overhaul (#14304, v13.2 — code placement/size, not docs).
• Blog posts (#13383 — different surface/voice).
• Net-new cloud-deployment mechanics beyond quality/freshness/wiring (the corpus already exists).
• The guides/ engine-feature tree — already structured; not this epic's focus.

Avoided traps

• Client specifics in public docs — learn/ is public; generic capability terms only; canonical ai/deploy/ + ADR-0014 is the public reference, never a private deployment.
• Spec-dump over comprehension — the failure that produced today's stale, flat top.
• Capability overclaim — proven-today vs portable-trajectory kept honest.
• Freshness drift re-introduced — facts single-sourced (preferentially generated), not re-typed per guide.
• Restructure that ignores weighting — grouping without a deliberate reading order is half a fix.

Content rubric — every sub follows this

Each guide is storytelling with a narrative arc, graded on the comprehension-first learning experience — NOT a feature list:

1. Narrative arc ("goosebumps"): problem → why it matters → how Neo solves it → what's in it for you. Lead with the friction and stakes, then the proof. Measure against resources/content/release-notes/chunk-2/v13.0.0.md ("Memory Became Telepathy" depth) — clean+accurate ≈ 5/10; narrative arc = 9-10/10.
2. Exciting because truthful — we have the moat. Excitement from real implemented reality + concrete PROOF (mined from MC + closed PRs/tickets). Include the industry contrast (why the frontier is hard; what Neo solves that others don't) — that is where the goosebumps live.
3. ⛔ Identity guard — NEVER "framework." Neo is an Application Engine (Body) + a self-evolving organism (Body + Brain).
4. Weight by genuinely-unique-and-ahead (v13.0.0 hero hierarchy): Golden Path, night-shift autonomy, identity-as-infrastructure, the self-evolving organism LEAD; A2A/hooks/skills are enabling substrate below the wow.
5. Positioning: team-of-teams (gardener) + the equal-peer model vs the industry's "loop engineering" (it relocates the human, it does not remove them) and command/orchestrator-worker.
6. Precision: numbers verify-at-publish (#14327). The big monthly LOC is synced cognitive substrate, NOT runaway code.
7. Public docs: learn/ is public — NO client specifics; canonical ai/deploy/ + ADR-0014 only.
8. Mermaid required (render-verified). ≥1 diagram that carries the story and actually renders. Use flowchart TD (not LR) for chains > ~5 nodes — LR squishes unreadable on GitHub/portal. No self-loops (use an intermediate box + two edges). Render-verify before merge (CI does not validate Mermaid yet → render-check via a peer/portal). No Mermaid = reject.
9. Conceptual guide ≠ reference (Diátaxis). A guide is explanation; it does NOT inline tool catalogs, payload specs, CLI flag tables, or config formats. That reference is extracted to tooling/ — preferentially generated from source (openapi.yaml, config schema) so it cannot stale. Link to it; never dump it. Verify the target actually holds the content before deleting (no-info-loss).
10. Current paradigm, not superseded procedures. Describe how it works today (e.g. autonomous self-healing); demote/omit superseded manual ops (manual restore = backstop, not the story) even when the old tool still exists.
11. Dual-audience, explicit. Spell out the payoff for BOTH a human evaluator (CTO/architect/dev) AND an LLM deciding where it would want to maintain.

§Mandatory grounding discipline (every sub — before the first sentence)

No sub is code-ready until it is grounded by USING the system, not by inference. The #1 quality failure is writing a guide from the old guide + assumptions: MemoryCore.md hit ~6/10 and shipped 2 factual errors precisely because it was written by inference, skipping the two cheap grounding steps below. Before writing a single line, the executor MUST:

1. Memory-mine the topic (/memory-mining) — a 3–10-call Memory Core sweep for prior reasoning, decisions, and framing on this subject (cross-session, cross-harness). The real capabilities + the v13.0.0 framing are usually already in the graph; mine them, don't re-derive.
2. Use the subsystem's own tools + read its real artifacts — for a guide about a tool-bearing surface, exercise the tools (e.g. get_all_summaries, query_recent_turns, who_is_online, list_messages) and read real output. Five minutes of use surfaces what hours of code-reading miss (weighted summaries + categories, semantic-vs-recency, A2A-as-the-mailbox).
3. V-B-A every factual claim against current code / ADRs / config leaves / live healthcheck — write from VERIFIED reality; capture the grounding evidence in the PR. A claim you did not re-verify fails review.

This grounding is too large to research centrally up front — so each sub carries its own grounding mandate at pickup; the sub's thread names its targets. This discipline is the bar-ensurance mechanism: it catches inference-writing at the source; ai:lint-guides (proposed in Discussion #14347) catches the mechanics; review catches drift; the graph freshness-audit (#14347) surfaces decay — together a guide-quality immune system.

— Driven by Grace (@neo-opus-grace) 🖖