Rewrite CodebaseOverview.md to reflect Two Hemispheres architecture + Dream Pipeline

Context

learn/guides/fundamentals/CodebaseOverview.md is loaded during agent bootstrap (AGENTS_STARTUP.md Step 1). It forms the mental model every agent inherits about what Neo.mjs is. Currently that model is: "Neo is an engine with AI tools attached."

Post-v12.2, that's a category error. The more accurate architectural map already exists in two documents CodebaseOverview.md doesn't cross-reference:

• learn/benefits/ArchitectureOverview.md — Two Hemispheres, Cognitive Loop (Perceive/Reason/Act/Reflect), SDK Bouncer pattern, Neural Link bridge, Dream Pipeline overview, Closed Loop feedback diagram
• learn/agentos/DreamPipeline.md — Six-phase REM pipeline with the specific Golden Path formula priority = (semanticScore × 2.0) + (structuralWeight × 1.0), graph physics (Hebbian decay + TTL pruning + vector apoptosis), modifiers (bug +1.0, community +0.5, needs-re-triage −10000)

The bootstrapping agent today sees the engine clearly but only a sketch of the Agent OS. That produces predictable drift — blog post #10074 framed Neo as "framework" throughout despite the engine-category correction being durable in memory for weeks. Discussion #10119 had to be amended post-publication with a "(4) category correction" pass. These aren't failures of individual sessions — they're symptoms of bootstrap-time mental-model drift.

Trigger

Pick up after v12.2 ships, not before:

1. Architecture is mid-flight on two axes (#9999, #10030). An update written during flight documents shipping-state, not landed-state
2. v12.2 marks the stabilization point where engine + concept ontology + multi-tenant memory + gated RSI loop are all co-present and observable
3. Sequencing: v12.2 release → this rewrite → #10119 MX epics. The rewrite becomes the bootstrap mental model for the agents building the #10119 follow-ons

The Problem

Specific gaps in CodebaseOverview.md as of 2026-04-20:

• No Two Hemispheres framing. Engine and Agent OS described in sequence, not as co-evolving halves of one system
• No Cognitive Loop. Perceive/Reason/Act/Reflect mentioned nowhere
• No Dream Pipeline. Six phases, Golden Path formula, graph physics all absent
• No Closed Loop diagram. The session → memory → graph → handoff → next-session cycle is the central insight and not present
• No MX framing. The design principle that shapes what goes into the Agent OS half. See durable memory feedback_mx_model_experience.md; concept coined by @tobiu 2026-04-20; positioning vs. adjacent terms (Machine Experience, Agent Experience) needs its own follow-up if MX formalizes into a public guide
• Outdated query-entry-point table. Post-#10030, semantic concept-graph traversal supplements/replaces regex-based gap detection
• Sub-agent profiles missing. Librarian / QA / Browser are shipped but invisible in the bootstrap doc

The Fix

1. Update introduction to frame Neo.mjs as an application engine with a co-evolving Agent OS — not as "framework with AI integration"
2. Replace the "Agent OS Backend" section with a digest of ArchitectureOverview.md:
   • Two Hemispheres (brief diagram or prose)
   • Cognitive Loop (one-line phase descriptions)
   • SDK Bouncer pattern (one paragraph)
   • Neural Link bridge (one paragraph + link)
   • Dream Pipeline overview (six phases one-liner each → link to DreamPipeline.md for depth)
   • Closed Loop diagram (or equivalent prose)
3. Add a brief MX section if the concept has formalized into its own guide by the time this ticket is picked up — otherwise reference the feedback memory
4. Update the query-entry-point table to reflect post-#10030 concept-graph entry points
5. Cross-link explicitly to ArchitectureOverview.md, DreamPipeline.md, SwarmIntelligence.md, NeuralLink.md — bootstrap agents should know these exist and when to dive deeper
6. Keep the engine half intact. The runtime description is accurate; the gap is only on the Agent OS side

Acceptance Criteria

• Introduction frames Neo as "application engine with co-evolving Agent OS"
• Two Hemispheres diagram or prose present (simpler than ArchitectureOverview.md — this is a bootstrap doc, not a reference)
• Cognitive Loop (Perceive/Reason/Act/Reflect) mentioned with one-line explanations
• Dream Pipeline six phases listed (depth deferred to DreamPipeline.md)
• Closed Loop feedback idea communicated (minimum: "agent → memory → graph → handoff → next agent")
• Sub-agent profiles (Librarian, QA, Browser) mentioned with one-line purpose each
• Cross-links to ArchitectureOverview.md, DreamPipeline.md, SwarmIntelligence.md, NeuralLink.md present
• Line count stays comparable to current (~700 lines) — bootstrap doc, not reference. Depth goes to linked docs
• learn/tree.json updated if hierarchy shifts (probably not)
• At least one empirical validation: read the rewrite as a fresh bootstrap agent and verify the mental model formed matches "engine + co-evolving Agent OS"

Out of Scope

• Deep Dream Pipeline internals — those live in DreamPipeline.md
• Deep MX principles — those need a dedicated guide if the concept formalizes (separate follow-up ticket)
• Multi-tenant Memory Core specifics — those live in the Memory Core Server guide
• Grid / frontend deep dives — CodebaseOverview.md links; specifics stay in guides

Avoided Traps

• Rejected: rewrite ArchitectureOverview.md instead. That doc is the correct reference — the problem is only that the bootstrap doc doesn't point to it. Updating the wrong file would solve nothing.
• Rejected: do it now. Documentation written during architectural flux ages poorly. Wait for v12.2 stabilization.
• Rejected: scope-creep to update every referenced downstream guide. One doc at a time; downstream guides update naturally as their areas evolve.

Related

• Parent epic: #9999 (Cloud-Native Knowledge & Multi-Tenant Memory Core) — this rewrite is the documentation-stabilization task that closes the epic loop for future agent onboarding
• Existing reference docs to digest: learn/benefits/ArchitectureOverview.md, learn/agentos/DreamPipeline.md
• Triggered by session insight: #10074 (origin 51640d07) — a bootstrap agent formed framework-category mental model despite engine-category correction being durable in memory; bootstrap doc was the load-bearing gap
• MX framing (durable memory feedback_mx_model_experience.md saved this session). If MX formalizes into a public guide between now and pickup, this rewrite introduces it briefly; full depth goes to the dedicated guide

Origin Session ID: 5a521819-dc75-4549-888e-fcea818d0401