LearnNewsExamplesServices
Frontmatter
id12256
titleREADME: remove centralized-SPOF undersell, elevate v13 cloud-on-your-codebase, strengthen compelling "why try it"
stateClosed
labels
documentation
assigneesneo-opus-ada
createdAtMay 31, 2026, 3:51 PM
updatedAtMay 31, 2026, 4:16 PM
githubUrlhttps://github.com/neomjs/neo/issues/12256
authorneo-opus-ada
commentsCount0
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
blockedBy[]
blocking[]
closedAtMay 31, 2026, 4:16 PM

README: remove centralized-SPOF undersell, elevate v13 cloud-on-your-codebase, strengthen compelling "why try it"

neo-opus-ada
neo-opus-ada commented on May 31, 2026, 3:51 PM

Context

Follow-up to the README apex/presentation rollout (Epic #12225; #12251 / PR #12252 merged). Operator review of the merged README on dev (2026-05-31) flagged three issues — the first an undersell correction, the latter two a compellingness gap.

The Problems (operator-flagged)

  1. The "Honest Caveat: A Centralized Brain" section is false / underselling. It frames the Brain as running "on a single operator's infrastructure… a Single Point of Failure… not yet immortal." Operator: "we have cloud deployments ready… 'runs on a single machine' is NOT true… I can easily backup the graph data to a different machine or apple time capsule." The Brain is cloud-deployable (v13 multi-tenant) and its entire state is portable files (SQLite Native Edge Graph + vector store). This is the recurring undersell pattern — framing current reality as a fragility.
  2. v13 multi-tenant cloud reads as a side note. The "deploy the Agent OS on your own codebase" capability — one of the strongest reasons to try Neo.mjs — is buried as a mid-document section with a version-led headline. Operator: "cloud => v13 multi tenant item is a side note."
  3. Few compelling arguments for why to try Neo.mjs. The README is strong at what Neo is and who it's for (the "Who This Is For" filter is strong) but thin on what you walk away with. Operator: "there are little compelling arguments on why to even try out neo."

The Fix

  1. Delete ## The Honest Caveat: A Centralized Brain. Fold a resilience-as-strength statement into the v13 section: Body distributed (every clone a backup); Brain state = portable files (snapshot/back-up/redeploy anywhere); v13 runs it as a cloud deployment, not one operator's box. Keep #10291 referenced as forward-hardening (self-defense + sustainable funding), not present fragility.
  2. Elevate + rewrite v13. Move the section up (after the hero, before the deep ## The Two Hemispheres), rename to a benefit headline ("Deploy a Cross-Model AI Engineering Team on Your Own Codebase"), and strengthen it into a compelling pitch (persistent memory + cross-family review + self-improvement on your repo; "a config entry, not a fork").
  3. Strengthen compelling "why try it" arguments — lead the Body with the engineer outcome (40k+ ops/sec without jank; multi-window object permanence; zero build/zero deps) and surface the proof-of-life (the swarm already runs its own lifecycle: 706 merged PRs, cross-family review).

Acceptance Criteria

  • ## The Honest Caveat: A Centralized Brain removed; no "single machine / SPOF / not yet immortal" framing remains.
  • Resilience reframed as strength (distributed Body + portable/cloud-deployable Brain) within the v13 section; #10291 referenced as forward-hardening only.
  • v13 section moved above ## The Two Hemispheres, benefit-headlined, and strengthened into a compelling deploy-on-your-codebase pitch.
  • At least one strengthened compelling "why try it" argument per audience (engineer outcome + proof-of-life).
  • No client name (capability framing only); no framework-negation anti-pattern (grep framework|React|Angular|Vue → 0); all relative links resolve; hygiene clean.
  • Operator wording-eyes (front-page taste) + cross-family review (@neo-gpt) before merge.

Out of Scope

  • The two-hemispheres structure, MX-loop block + motto, Institution table (keep — operator-confirmed).
  • Other identity surfaces (VISION, llms.txt — separate merged subs).
  • SEO priority map (#12255 — @neo-gpt's lane).

Related

  • Parent epic: #12225
  • Predecessor: #12251 / PR #12252 (README apex + presentation — merged; this is the operator's follow-up review of the merged result)
  • Canonical apex: Discussion #12234 + ADR 0018 §2.7 OD-1
  • v13 topology: ADR 0014 + ai/deploy/
  • Forward-hardening: #10291 (organism self-defense + sustainable funding)

Origin Session ID: d2fbe3b2-44c4-4aab-b8c7-62621babc790 Retrieval Hint: "README compelling SPOF centralized Brain undersell v13 cloud side-note why try Neo"

tobiu referenced in commit de248b7 - "docs(identity): elevate v13 cloud, drop centralized-SPOF undersell, sharpen README pitch (#12256) (#12257) on May 31, 2026, 4:16 PM
tobiu closed this issue on May 31, 2026, 4:16 PM