---
id: 12253
title: Align generated llms.txt identity header with apex
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
  - architecture
  - build
assignees:
  - neo-gpt
createdAt: '2026-05-31T12:26:19Z'
updatedAt: '2026-05-31T13:02:59Z'
githubUrl: 'https://github.com/neomjs/neo/issues/12253'
author: neo-gpt
commentsCount: 0
parentIssue: 12225
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-31T13:02:59Z'
---
# 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:

```text
# Neo.mjs: The Application Engine for the AI Era

> 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

| Target Surface | Source of Authority | Proposed Behavior | Fallback | Docs | Evidence |
|---|---|---|---|---|---|
| `buildScripts/docs/seo/generate.mjs#getLlmsTxt()` header | ADR 0018 §2.7 OD-1 + #12225 generated-output taxonomy | Apex-first LLM-crawler copy; Body/runtime becomes subordinate | Keep Application Engine phrase only as a Body subsection if concise copy needs it | PR body | Focused source diff |
| `apps/portal/llms.txt` | Generated from `getLlmsTxt()` | Output reflects the new header after regeneration | Do not hand-edit; if regeneration is blocked, document blocker and keep output unchanged | PR body | Regeneration command + generated diff |
| Dated proof metrics | `facts-ledger.md` dated-window stat rule | Metrics are generated/verified at implementation time before inclusion | Omit metrics if derivation is not in scope | PR body evidence | Git/GitHub command output or absent metrics |
| Existing route sections | Current SEO generator behavior | Main Pages, Latest Updates, examples, docs routes remain structurally intact | If output shifts, explain why and add targeted validation | PR body | Generated output spot-check |

## 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"

## Timeline

- 2026-05-31T12:26:20Z @neo-gpt added the `documentation` label
- 2026-05-31T12:26:20Z @neo-gpt added the `enhancement` label
- 2026-05-31T12:26:20Z @neo-gpt added the `ai` label
- 2026-05-31T12:26:20Z @neo-gpt added the `architecture` label
- 2026-05-31T12:26:20Z @neo-gpt added the `build` label
- 2026-05-31T12:26:30Z @neo-gpt added parent issue #12225
- 2026-05-31T12:35:06Z @neo-gpt assigned to @neo-gpt
- 2026-05-31T12:43:00Z @neo-gpt cross-referenced by PR #12254
- 2026-05-31T13:02:59Z @tobiu referenced in commit `beddcb6` - "fix(identity): align generated llms header with apex (#12253) (#12254)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-31T13:02:59Z @tobiu closed this issue
- 2026-05-31T14:58:27Z @neo-gpt cross-referenced by #12225

