LearnNewsExamplesServices
Frontmatter
id12228
titleRewrite README opening to the canonical apex
stateClosed
labels
documentationenhancementai
assigneesneo-gpt
createdAtMay 30, 2026, 11:25 PM
updatedAtJun 7, 2026, 7:17 PM
githubUrlhttps://github.com/neomjs/neo/issues/12228
authorneo-opus-ada
commentsCount0
parentIssue12225
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtMay 31, 2026, 12:25 PM

Rewrite README opening to the canonical apex

Closed v13.0.0/archive-v13-0-0-chunk-15 documentationenhancementai
neo-opus-ada
neo-opus-ada commented on May 30, 2026, 11:25 PM

Parent epic: #12225

Context

The README opening should lead with the canonical apex (ADR 0018 §2.7 OD-1, graduated via Discussion #12234): 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 README's current framing ("self-evolving digital organism / Four Pillars") is close on the organism noun but undersells: it misses the institution / Brain-as-headline gloss (the cross-family engineering team) and treats Swarm + Evolution as co-equal pillars rather than capabilities inside the Brain. Body /src/ runtime + Brain /ai/ Agent OS are the two hemispheres beneath the apex (structure, not the lead noun). The Neural Link was historically over-weighted as a headline; it is a flagship capability, not the apex.

The Fix

Rewrite the README opening to lead with the canonical apex:

  • Open with the self-evolving-software-organism apex sentence (a professional end-to-end AI engineering team; Body runtime + Brain cross-family engineering team beneath it; human at the merge gate).
  • Demote the Neural Link from headline to a supporting capability mention.
  • Demote "Four Pillars" from the top-level scaffold to a deeper-doc elaboration of what the Brain contains (Swarm + Evolution live inside the Brain).
  • Preserve adoption substrate (badges, quickstart, license); the deeper organism / Four-Pillars framing relocates to VISION / deeper docs, not deleted.
  • Keep all numeric facts (version, counts, dated metrics) sourced from their SSOT; the May-2026 proof point (706 merged / 800 closed, merged/closed-only) is proof-layer, not the lead.

Acceptance Criteria

  • README opening leads with the canonical apex (self-evolving software organism + professional AI engineering team; Body/Brain the two hemispheres beneath it)
  • Neural Link demoted from headline; Four-Pillars relocated to deeper doc (not deleted)
  • Adoption substrate (badges/quickstart/license) preserved
  • Dated metrics still lock-step with CodebaseOverview.md
  • Cross-family review per ADR 0018 §2.6

Out of Scope

  • VISION.md rewrite (sibling sub)
  • learn/benefits/ Brain docs (sibling sub)
  • Heritage facts (sibling sub)

Related

  • Parent: #12225 · Apex: ADR 0018 §2.7 OD-1 (graduated via Discussion #12234)

Origin Session ID: 94a91ebc-d325-4d32-a746-4ff8c26c0342 Retrieval Hint: "README opening canonical apex self-evolving software organism demote Neural Link Four Pillars"

tobiu referenced in commit d9c5f59 - "docs(readme): lead with organism apex (#12228) (#12243) on May 31, 2026, 12:25 PM
tobiu closed this issue on May 31, 2026, 12:25 PM