Align generated llms.txt identity header with apex

Context

Parent epic: #12225

The neo-identity-update skill explicitly treats generated SEO as an identity surface: buildScripts/docs/seo/generate.mjs owns apps/portal/llms.txt and apps/portal/sitemap.xml; generated output must not be hand-edited.

V-B-A on current origin/dev after the #12231 / PR #12245 merge shows the generator is still only partially covered:

• buildScripts/docs/seo/generate.mjs still has getLlmsTxt() headed by # Neo.mjs: The Application Engine for the AI Era and a runtime-first description.
• PR #12245 touched getLlmsTxt() only to correct the MCP-server fact wording; it did not update the identity framing.
• #12236 explicitly excludes generated SEO output from the portal-index work.
• #12244 is facts-only coherence tooling; it should not absorb this framing repair.

The epic body names generated SEO as affected surface class 2, but no executable sub currently owns the llms.txt identity header as an LLM-crawler-facing framing surface.

The Problem

llms.txt is one of the most direct machine-reader entry points into Neo.mjs. Today its generated header undersells Neo by leading with the older Body/runtime register:

<h1 class="neo-h1" data-record-id="4">Neo.mjs: The Application Engine for the AI Era</h1>

> Neo.mjs is not a framework, but a multi-threaded Application Engine for the web.

That copy is compatible as a deeper engineer-discovery cluster, but it is wrong as the lead for an LLM-facing identity surface after ADR 0018 §2.7 OD-1 and #12234. It makes crawlers and agents learn Neo primarily as an application engine, while the canonical apex is now the self-evolving software organism / professional AI engineering team whose Brain and Body are two hemispheres beneath that apex.

This is exactly the generated-output trap ADR 0018 warns about: if we update apps/portal/llms.txt directly it will be clobbered; if we only fix facts inside the generator, the stale framing remains machine-visible.

The Architectural Reality

The owning source is buildScripts/docs/seo/generate.mjs, specifically getLlmsTxt(). apps/portal/llms.txt is generated output.

Authority stack:

• ADR 0018 §2.7 OD-1: canonical apex and audience/register discipline.
• neo-identity-update skill: generated outputs are fixed at buildScripts/docs/seo/generate.mjs, not output files.
• #12225: affected-areas taxonomy includes generated-output-source as class 2.
• #12231/#12244 boundary: facts convergence and facts checks are not enough to repair framing debt.

The operator-provided draft paragraph in the originating turn is a strong target shape, but it includes dated metrics. Per facts-ledger.md, dated proof counts must be regenerated from git / GitHub API at implementation time or omitted from generated output until a durable derivation exists. Do not paste stale absolute counts.

The Fix

Update getLlmsTxt() so the generated llms.txt header leads with the organism apex in a concise LLM-crawler register, then routes into Body/runtime and Brain/Agent OS specifics.

Expected implementation shape:

1. Replace the runtime-first lead with a concise apex-first header.
2. Preserve the Application Engine / Off-Main-Thread / JSON scene-graph value as a subordinate Body section, not the headline.
3. Add Brain / Agent OS substance: cross-model swarm, Memory Core / Active Hybrid GraphRAG, DreamService, self-healing loops, and Neural Link as the possession interface.
4. Keep the environment URL explanation accurate.
5. If dated proof counts are included, derive them from the correct source in the generator or a small helper; otherwise omit them rather than hard-coding.
6. Regenerate apps/portal/llms.txt through the build script and review the generated diff.

Contract Ledger Matrix

Decision Record Impact

aligned-with ADR 0018. No ADR change expected unless implementation discovers that llms.txt needs a distinct audience cluster beyond the existing framing-governance register list.

Acceptance Criteria

• getLlmsTxt() no longer leads with Application Engine for the AI Era as the primary identity header.
• The generated llms.txt header leads with the canonical organism apex in LLM-crawler-appropriate prose.
• Body/runtime capabilities remain present but are subordinate to the apex.
• Brain / Agent OS capabilities are materially present in the header, not just one MCP-count sentence.
• Neural Link is described as a live-runtime possession interface, not a generic bridge/chat feature.
• Any dated proof counts are regenerated/verified at implementation time or omitted.
• apps/portal/llms.txt is regenerated from buildScripts/docs/seo/generate.mjs; no hand-edited generated-output diff.
• Focused validation inspects the generated header and confirms route sections remain present.
• Cross-family review completed before merge because this is an identity-surface change.

Out of Scope

• Rewriting portal index.html JSON-LD/meta; covered by #12236.
• Facts-only drift checks; covered by #12244.
• Package keywords / GitHub topics; covered by #12227 / #12241 and external metadata updates.
• Changing the canonical apex wording itself.
• Redesigning sitemap priority ordering beyond what the header repair requires.

Avoided Traps

• Editing apps/portal/llms.txt directly.
• Treating the Application Engine register as the global lead after #12234.
• Hard-coding May 2026 proof counts without a derivation path.
• Collapsing all audience registers into one phrase; llms.txt needs a machine-reader register, not README paste.
• Burying framing debt inside the facts-only #12244 guard.

Related

• Parent: #12225
• Boundary: #12231, #12244
• Portal machine-surface sibling: #12236
• ADR 0018: Neo Identity Source-of-Truth Model
• Skill: neo-identity-update

Origin Session ID: 87203e0b-c9ff-4a82-a67b-9a0dda760c32

Retrieval Hint: "llms.txt getLlmsTxt generated SEO identity apex Application Engine for AI Era" Retrieval Hint: "buildScripts/docs/seo/generate.mjs generated-output trap ADR 0018"