LearnNewsExamplesConnect
Frontmatter
assigneesneo-gpt-euclid
createdAtAug 27, 2026, 10:49 AM
updatedAtAug 27, 2026, 1:04 PM
githubUrlhttps://github.com/neomjs/neo/issues/17808
authorneo-gpt-euclid
commentsCount0
parentIssuenull
subIssues[]
subIssuesCompleted0
subIssuesTotal0
contentTrust
projected
quarantined0
signals[]
blockedBy[]
blocking[]
closedAtAug 27, 2026, 1:04 PM

Map the Neo organization from the Engine README

Closed v13.2.0/archive-v13-2-0-chunk-16 documentationenhancementai
neo-gpt-euclid
neo-gpt-euclid commented on Aug 27, 2026, 10:49 AM

Context

The Engine README is the strongest current organization-level identity surface, but the repository split changed what “this repository” contains. The README needs an explicit organization map so readers can distinguish the parent Neo organism from the Engine package they are currently viewing.

The operator selected the five primary repositories and requires a visible “you are here” marker. This ticket changes the Engine README only.

Live latest-open sweep: checked the latest 20 open Engine issues immediately before creation; no equivalent organization-map README ticket exists. A2A in-flight sweep: latest 30 messages across read states contained no competing Engine README claim.

The Problem

The README explains Body and Brain in prose, but it does not provide a compact repository map covering the now-independent Engine, Brain, Institution, DevIndex and Skills products. Cold readers can therefore understand the organism and still miss where they are, which repository owns the next action, or which sibling contains the linked subsystem.

The Architectural Reality

README is the ADR 0018 apex framing surface. It should describe the parent organism first, then segment by the audience of this repository. The Engine README remains the baseline narrative; this ticket adds repository location and tightens Engine-specific doors without rewriting the identity thesis.

The Fix

Update README.md:

  1. Preserve the current organism-level opening and canonical Introduction relationship.
  2. Add a concise five-repository bulleted map near the front:
    • neomjs/neo — Body / Engine ← you are here;
    • neomjs/neo-agent-brain — Brain / Agent OS;
    • neomjs/neo-agent-institution — Institution application;
    • neomjs/devindex — developer/repository intelligence;
    • neomjs/neo-agent-skills — canonical Skills substrate.
  3. Ensure Engine quickstart, architecture and contribution doors remain primary for this repository.
  4. Replace stale filesystem-relative Brain doors with canonical sibling links where necessary.

Contract Ledger Matrix

Target Surface Source of Authority Proposed Behavior Fallback Docs Evidence
README organization map live neomjs repositories + operator direction Five links, one-line ownership, exactly one “you are here” marker Omit a repository only if it is not a public product surface README Link/status check
README apex canonical learn/benefits/Introduction.md + ADR 0018 Preserved organization narrative, audience-segmented toward Engine Reuse current copy when already current README Cross-family framing review
Engine next-step doors Engine package/product authority Engine install/build/learn/contribute remain primary Sibling links remain secondary README Fresh-reader route audit

Decision Record impact

Aligned-with ADR 0018. No ADR change.

Acceptance Criteria

  • README contains the five linked repositories with accurate one-line ownership.
  • neomjs/neo alone carries the visible “you are here” marker.
  • Parent-organism framing remains compatible with the canonical Introduction.
  • Engine quickstart and Engine learning/contribution doors remain primary.
  • Brain/Institution/DevIndex/Skills references use canonical repository links and no dead local paths.
  • README links pass a fresh-clone/readability check.
  • Cross-family identity review completes before merge.

Out of Scope

Engine package.json · Brain README · Portal/Pages/middleware · generated sitemap/llms.txt · product naming · repository extraction.

Avoided Traps

  • Rewriting the entire README when the current organism narrative is the baseline.
  • Turning the Engine README into an organization portal with no Engine-specific primary door.
  • Duplicating detailed sibling documentation instead of linking its canonical owner.

Related

Identity authority: #12203 / ADR 0018
Repository split: #17500

Origin Session ID: 14f81b5f-435b-4f00-92fc-67503eb0602e

Retrieval Hint: Engine README five repository organization map you are here

tobiu cross-referenced by PR #17812 on Aug 27, 2026, 12:34 PM
tobiu closed this issue on Aug 27, 2026, 1:04 PM
tobiu referenced in commit b83ccc5 - "docs(readme): add Engine repository map (#17808) (#17812) on Aug 27, 2026, 1:04 PM