Roll out the Neo identity apex across all encoding surfaces

Context

The machinery to maintain Neo's identity shipped in #12203 (ADR 0018 + the neo-identity-update skill, PR #12212). #12203 explicitly scoped running the skill out of its own scope. This epic is that separate, larger body of work: bringing every identity-encoding surface into coherence with the now-canonical apex, and filling the gaps a 2026-05-30 cross-substrate audit surfaced. #10452 (CLOSED) did a one-shot README/AGENTS rewrite; this epic is the ongoing application across the full surface, not a one-shot.

This epic body describes the concept. The real tasks live in the sub-issues — not here.

The concept

Neo's identity is a distributed property across ~30+ surfaces, not a single document. Per ADR 0018 it is two materials with opposite update mechanics:

• Facts (version, MCP-server count, Node requirement, dates, counts) — exactly one true value; they must converge to a single source of truth and derive / coherence-check everywhere else.
• Framing (taglines, positioning, audience) — deliberately audience-segmented; governed against a canonical apex, with a drift-vs-intentional-divergence escalation branch.

The canonical apex (ADR 0018 §2.7 OD-1 — GRADUATED via Discussion #12234, full cross-family triad, 2026-05-31; final wording operator-authored):

Neo.mjs is a self-evolving software organism — a professional, end-to-end AI engineering team that lives in its own open-source repository.

(The full apex paragraph + register / naming / proof discipline live in ADR 0018 §2.7 OD-1 and the neo-identity-update skill's framing-governance.md — derive from there, do not copy a frozen value.) The Body (/src/ multi-threaded runtime) and Brain (/ai/ Agent OS) are the two hemispheres beneath this apex — the two-hemisphere institution is the structure, not the lead noun. The Brain (~41% of the module count) is the headline; the Neural Link is a flagship capability, never the lead.

Apex-evolution note (2026-05-31): an earlier draft of this epic — and the current sub bodies #12226–#12232 — led with the flatter "two-hemisphere institution" wording. Discussion #12234 superseded that with the self-evolving software organism apex above. The subs predate that graduation and are being reconciled to the current apex (and a stale Parent epic: #12216 body-reference corrected to #12225; the native sub-issue links are already correct).

Graduations feeding this epic

• Discussion #12234 (apex + machine-spec) — GRADUATED. Beyond the apex wording (now in ADR 0018 §2.7 OD-1, shipped on PR #12212), it emitted a machine-spec for the rollout: the portal ld+json single-@graph shape (#neo root / Body = SoftwareApplication / /ai = SoftwareSourceCode / maintainer = Organization; name = Neo.mjs, alternateName = Neo); the cold machine-surface keyword cluster (self-evolving, software-organism, autonomous-agent-os, professional-ai-engineering-team, self-healing-software-organism, autonomous-code-execution, cross-family-pr-review, dreamservice, active-hybrid-graphrag, neural-link, possession-interface, conversational-application-embodiment, live-application-mutability, agent-os, mcp); and the proof asset blog #10074. These feed sub #12227 (discovery) and the new portal-schema sub below.
• Discussion #12235 (portal machine surfaces) — GRADUATED → sub #12236. apps/portal/index.html ld+json currently mistypes the Brain / Agent OS as a second SoftwareApplication; #12235 (Option B) restructures it to the single @graph above, adds Open Graph + <meta> to the concise apex form, and aligns visible hero copy. Landed as sub #12236 (Correct portal machine surfaces to organism apex), kept distinct from #12231 (facts-only).

The problem this epic resolves — the undersell

The Brain — the larger and more differentiated half (~41% of the module count) — is nearly absent from the surfaces that present Neo:

• learn/benefits/ is 14 files, 100% Body / 0% Brain — the most valuable capability has zero presence in the folder literally named "benefits."
• README / VISION still lead with older or partial framings (Four-Pillars scaffolding; "web applications"; Neural-Link-as-headline) rather than the full canonical apex.
• Machine-facing facts have drifted (stale versions, server counts, requirements).

Net effect: the hardest-to-reproduce capability is invisible to the audience that would value it most. The professional, multi-family, reviewed engineering process — distinct from single-agent output — is not communicated anywhere.

Affected-areas taxonomy (the 5 update-mechanism classes)

1. Hand-edited prose — README, .github/VISION.md, ROADMAP, learn/benefits/**, learn/agentos/*.md, .claude/CLAUDE.md anchors.
2. Generated-output-source — buildScripts/docs/seo/generate.mjs → apps/portal/llms.txt + sitemap.xml (edit the generator, never the output).
3. Structured-facts-in-code — package.json, apps/portal/index.html ld+json, portal hero .mjs.
4. External-platform — GitHub repo description + topics, npm (out-of-git; needs API/operator).
5. Dated-snapshot — README "Platform at Scale" ↔ learn/guides/fundamentals/CodebaseOverview.md.

How this epic is worked

Each surface-class change is a sub-issue. Every sub: derives framing from the canonical apex, fixes facts at their SSOT, runs under the neo-identity-update skill, and takes a cross-family review per ADR 0018 §2.6 (human merge-gate is the documented backstop when only one family is active).

Decision Record impact

aligned-with ADR 0018 (the model this applies) and ADR 0012 (identity-handle boundary). aligned-with #12203 (machinery), #12234 (canonical apex + machine-spec), and the closed #10452 (origin rewrite).

Acceptance Criteria

• All sub-issues resolved
• Every surface in the affected-areas taxonomy is either updated to the apex or explicitly confirmed already-coherent
• No fact (version, MCP-server count, Node requirement, dated metrics) disagrees across surfaces
• README / VISION / learn/benefits/ lead with the canonical apex (self-evolving software organism; Body/Brain the two hemispheres beneath it); older framings preserved as deeper-doc elaborations, not deleted
• learn/benefits/ has Brain coverage (no longer Body-only)
• Portal ld+json restructured to the single @graph (Brain no longer typed SoftwareApplication); concise apex + machine-surface keyword cluster propagated to the discovery surfaces

Out of Scope

• The maintenance machinery itself (shipped in #12203 / PR #12212)
• Engine / runtime code changes
• Each sub carries its own additional out-of-scope

Related

• #12203 — identity maintenance machinery (ADR 0018 + skill); this epic applies it
• #12234 — canonical apex + machine-spec graduation (carried on PR #12212)
• #12235 — portal machine-surfaces design-dialogue (GRADUATED → #12236)
• #12236 — Correct portal machine surfaces to organism apex (graduated sub of #12235)
• #10452 — Identity Rewrite (CLOSED; origin of the current README/AGENTS framing)
• #10074 — proof asset (cross-family self-healing blog)
• ADR 0018 — Neo Identity Source-of-Truth Model
• ADR 0012 — Model-Stats / identity-handle boundary

Origin Session ID

Origin Session ID: 94a91ebc-d325-4d32-a746-4ff8c26c0342

Handoff Retrieval Hints

Retrieval Hint: "neo identity apex rollout self-evolving software organism affected-areas" Retrieval Hint: "learn/benefits Body-only Brain-absent undersell"