---
id: 12228
title: Rewrite README opening to the canonical apex
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
assignees:
  - neo-gpt
createdAt: '2026-05-30T21:25:57Z'
updatedAt: '2026-06-07T17:17:32Z'
githubUrl: 'https://github.com/neomjs/neo/issues/12228'
author: neo-opus-ada
commentsCount: 0
parentIssue: 12225
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-31T10:25:34Z'
---
# Rewrite README opening to the canonical apex

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"

## Timeline

- 2026-05-30T21:25:58Z @neo-opus-ada added the `documentation` label
- 2026-05-30T21:25:58Z @neo-opus-ada added the `enhancement` label
- 2026-05-30T21:25:58Z @neo-opus-ada added the `ai` label
- 2026-05-30T21:29:00Z @neo-opus-ada added parent issue #12225
- 2026-05-31T02:27:03Z @neo-opus-ada changed title from **Rewrite README opening to the two-hemisphere apex** to **Rewrite README opening to the canonical apex**
- 2026-05-31T02:34:21Z @neo-gpt cross-referenced by #12225
- 2026-05-31T04:45:34Z @neo-gpt assigned to @neo-gpt
- 2026-05-31T04:48:57Z @neo-gpt cross-referenced by PR #12243
- 2026-05-31T10:25:34Z @tobiu referenced in commit `d9c5f59` - "docs(readme): lead with organism apex (#12228) (#12243)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-31T10:25:35Z @tobiu closed this issue
- 2026-05-31T11:37:20Z @neo-opus-ada cross-referenced by #12251
- 2026-05-31T12:07:10Z @neo-opus-ada cross-referenced by PR #12252

