What is the Neural Link?

The Neural Link is a bi-directional bridge that connects AI agents directly to the Neo.mjs runtime. It lets agents inspect the Scene Graph, component state, event listeners, computed styles, and DOM rectangles, and mutate the running application in real time.

Why is Neo.mjs called an Application Engine instead of a framework?

Neo.mjs maintains persistent application objects in a worker-backed Scene Graph instead of compiling application state away into ephemeral DOM nodes. That architecture enables multi-window orchestration, runtime permutation, and deep AI introspection.

What is Context Engineering?

Context Engineering shapes the information and tool environment around AI agents. Neo.mjs implements it through Knowledge Base, Memory Core, GitHub Workflow, and Neural Link MCP servers for frontier harnesses, plus a File System MCP server for internal Neo.ai.Agent local loops.

What is the Neo.mjs Agent OS?

The Neo.mjs Agent OS is the repository Brain: source code and services for Memory Core, Knowledge Base, Active Hybrid GraphRAG, DreamService, Golden Path synthesis, A2A coordination, and Neural Link tooling.

Frontmatter

id	15679
title	README: replace the duplicate brand H1 with the identity proposition
state	Closed
labels	documentationenhancementdesignai
assignees	neo-gpt
createdAt	Jul 22, 2026, 3:43 AM
updatedAt	Jul 22, 2026, 4:04 AM
githubUrl	https://github.com/neomjs/neo/issues/15679
author	neo-gpt
commentsCount	0
parentIssue	null
subIssues	[]
subIssuesCompleted	0
subIssuesTotal	0
contentTrust
projected
quarantined	0
signals	[]
blockedBy	[]
blocking	[]
closedAt	Jul 22, 2026, 4:04 AM

README: replace the duplicate brand H1 with the identity proposition

Closed Backlog/active-chunk-8 documentationenhancementdesignai

neo-gpt commented on Jul 22, 2026, 3:43 AM

Context

After #15671 / PR #15672 and #15674 / PR #15675 strengthened the README hero with the final-film poster and a light/dark wordmark, an operator visual review of the rendered header exposed a hierarchy problem: the brand is presented as the large wordmark, then again as the bare # Neo.mjs heading, then immediately again at the start of the identity lead.

The current source at 57a0a98b73 confirms those three hierarchy-level beats. This is not a global string-count problem: the Slack badge, image alt text, film caption, and later prose all have legitimate reasons to name Neo.mjs.

The Problem

The middle # Neo.mjs consumes the README's strongest textual heading without adding information beyond the wordmark and the next sentence. Simply deleting it would be the wrong fix: a live heading census confirms that it is the README's only Markdown H1, so deletion would remove the top-level document heading.

The hierarchy needs one semantic H1 that contributes meaning, while the first prose sentence still names the entity explicitly and the canonical identity remains intact.

The Architectural Reality

README.md is a human-facing FRAMING surface governed by ADR 0018, not a FACT or ACTION surface.
ADR 0018 §2.7 OD-1 defines the canonical apex: “Neo.mjs is a self-evolving software organism — a professional, end-to-end AI engineering team that lives in its own open-source repository.”
#12228 / PR #12243 established that apex in the README; #12251 / PR #12252 refined its presentation. Both retained the pre-existing bare brand H1 and neither addressed wordmark/H1 repetition.
#15671 and #15674 explicitly put README prose outside their asset-focused scopes, so this is a distinct follow-up rather than an extension of those closed lanes.
Per .agents/skills/neo-identity-update/references/framing-governance.md, the README must lead with the apex, retain Neo.mjs on first named mention, and receive cross-family review. The proposed change preserves those constraints compositionally across the heading and lead; no other identity surface needs to change because no identity claim changes.

The Fix

Replace the redundant brand-only H1 and split the existing apex into a proposition heading plus a named lead:

<h1 class="neo-h1" data-record-id="6">A self-evolving software organism</h1>

**Neo.mjs is a professional, end-to-end AI engineering team that lives in its own open-source repository.**

Together, the H1 and lead preserve both clauses of the canonical apex while giving each hierarchy level a distinct job:

the wordmark identifies the brand visually;
the H1 states what the entity is;
the lead names Neo.mjs and defines the team.

Keep the wordmark <picture>, badges, poster, film link/caption, and the rest of the opening unchanged.

Contract Ledger

Target Surface	Source of Authority	Proposed Behavior	Fallback / Edge Case	Docs	Evidence
`README.md` top-level H1	ADR 0018 §2.7 OD-1 + the operator visual review	Remain the single semantic H1, but state `A self-evolving software organism` instead of repeating the bare brand	If the split cannot preserve readable hierarchy, retain one semantic H1 and the intact canonical apex; never delete the H1 outright	`README.md` only	Heading census + rendered branch receipt
`README.md` identity lead	ADR 0018 §2.3 / §2.7 OD-1 + framing-governance naming discipline	Begin with `Neo.mjs` and carry the professional-team clause without adding or dropping an identity claim	Fall back to the current full canonical sentence rather than paraphrasing away meaning	`README.md` only	Exact-copy diff + cross-family identity review
Header assets, badges, poster, and caption	#15671 / PR #15672 and #15674 / PR #15675	Stay byte-for-byte unchanged; only the H1 and lead copy move	No asset fallback is introduced by this ticket	None	Scoped diff + GitHub render

Decision Record impact

aligned-with ADR 0018 §2.3 and §2.7 OD-1. No ADR change: this alters the README's presentation hierarchy, not the canonical identity.

Acceptance Criteria

README.md still contains exactly one Markdown H1.
The H1 states the identity proposition rather than the bare duplicate Neo.mjs name.
The first prose lead begins with Neo.mjs; the combined H1 + lead preserves the complete canonical-apex meaning without adding or dropping a claim.
The wordmark <picture>, badges, poster, film link/caption, and remaining README prose are unchanged.
A GitHub branch render is checked at representative desktop and narrow widths, with light and dark color schemes covered across the receipts; the heading hierarchy is clear and has no awkward wrap/orphan.
Cross-family review is completed per ADR 0018.
Verification does not use a global “Neo.mjs occurrence count”; legitimate badge, alt-text, caption, and prose mentions remain allowed.

Out of Scope

Changing the canonical apex or ADR 0018.
Rewriting the wider README opening.
Modifying wordmark, badge, poster, film-link, or caption assets.
Propagating copy to other identity surfaces; this is presentation-only and introduces no framing drift.
Removing legitimate Neo.mjs mentions elsewhere in the document.

Avoided Traps

Delete the middle line outright: removes the README's only semantic H1.
Count every Neo.mjs string: confuses visual hierarchy with accessibility text, badge copy, captions, and ordinary prose.
Run a cross-surface find/replace: violates ADR 0018's audience-segmented framing model for a change that does not alter identity meaning.

Identity authority and prior README work: #12225, #12228 / PR #12243, #12251 / PR #12252
Current header visual work: #15671 / PR #15672, #15674 / PR #15675

Live latest-open sweep: checked the latest 20 open issues at 2026-07-22T01:42:38Z; no equivalent found. A2A in-flight sweep: checked the latest 30 messages across all read states at the same timestamp; no overlapping README prose/heading claim. Exact GitHub, local archive, and Knowledge Base searches found no duplicate.

Origin Session ID: 123cd4c7-0154-4252-976f-32564fc1a47d

Retrieval Hint: "README duplicate brand H1 wordmark identity proposition canonical apex"