Correct portal machine surfaces to organism apex

Context

Discussion #12235 graduated the portal machine-surface shape for the identity apex rollout under Epic #12225. The work belongs under the existing identity rollout instead of a parallel portal contract because ADR 0018 and #12225 already define the affected-areas taxonomy for identity surfaces.

Observed evidence from the discussion and peer review:

• apps/portal/index.html still leads machine readers with the older "Application Engine for the AI Era" description register.
• The page has no og:* or twitter:* tags.
• The current JSON-LD includes two SoftwareApplication blocks: one for the Body/runtime and one for the Brain/Agent OS. The second shape is the Brain-as-SoftwareApplication mistag resolved by Discussion #12234.
• The portal schema also overlaps fact-drift work, but this ticket is the ontology/social/meta surface; facts-only updates remain scoped to #12231.

Pre-creation checks:

• Knowledge Base ticket search for portal machine surfaces JSON-LD Open Graph apps/portal/index.html identity discussion 12235 duplicate issue found no equivalent issue.
• GitHub issue search for the same lane returned only parent Epic #12225.
• Labels verified live: ai, enhancement, documentation, and architecture exist.
• Project attachment target: Project 12, the v13 release board.

The Problem

The portal's most crawlable identity surface still describes Neo through the older runtime-only register and misclassifies the Brain / Agent OS as another application. That makes machine consumers read Neo as a web/application framework with a secondary product-like app node, instead of the now-canonical organism 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.

This is the exact category drift #12234 resolved. Leaving the portal JSON-LD, meta description, and social preview tags stale weakens the public machine-facing version of the identity rollout even after the apex itself graduated.

The Architectural Reality

This ticket touches apps/portal/index.html and only the visible portal copy needed to make JSON-LD claims page-backed. It is part of Epic #12225's Structured-facts-in-code surface class, aligned with ADR 0018 and the neo-identity-update skill.

The target machine topology is inherited from #12234 rather than redesigned here:

• root entity: Neo.mjs
• alternate shorthand: Neo
• Body/runtime: SoftwareApplication
• Brain / Agent OS under /ai: SoftwareSourceCode
• maintainer / institution: Organization or Project, connected to the root graph
• FAQ: FAQPage, still Schema.org-valid and page-visible

Generated outputs such as apps/portal/llms.txt and sitemap files remain governed by buildScripts/docs/seo/generate.mjs under #12225. Do not hand-edit generated output for this ticket.

The Fix

Update the portal's machine-facing head and the minimum backing visible copy so crawlers, social previews, and AI readers receive the organism apex coherently.

Expected implementation shape:

• Replace the duplicated sibling SoftwareApplication JSON-LD shape with a connected @graph, unless implementation V-B-A proves a minimal separate-script bridge is safer for validation.
• Retag the Brain / Agent OS as SoftwareSourceCode, not SoftwareApplication.
• Add Open Graph tags for title, description, type, and URL; only add image fields if a verified social asset exists.
• Keep Twitter/X cards optional; if omitted, record the reason in the PR.
• Use a concise <meta name="description"> cut suitable for snippets, not the longer package-description form.
• Inspect the portal's visible-copy files before adding JSON-LD claims, and update only the visible copy needed to back those claims.

Contract Ledger Matrix

Signal Ledger

• Author signal: @neo-gpt proposed [RESOLVED_TO_AC] mapping in #12235 comment DC_kwDODSospM4BBTne on 2026-05-31.
• Non-author peer signal: @neo-opus-ada posted [GRADUATION_APPROVED by @neo-opus-ada] in #12235 comment DC_kwDODSospM4BBTng on 2026-05-31.
• Prior peer Step Back: @neo-opus-ada comment DC_kwDODSospM4BBTjL verified the current portal evidence and endorsed Option B.
• Operator context: nightshift directive requested graduation of #12234 and #12235 under the identity rollout.

Unresolved Dissent

None recorded after the corrected peer review. The only substantive correction was to fold the work into Epic #12225 and keep generated outputs out of this portal-index ticket; this body incorporates that correction.

Unresolved Liveness

Gemini is operator_benched in ai/graph/identityRoots.mjs as of the graduation window. This is not a Tier-2 substrate change, so no extra Tier-2 revalidation AC is required. Cross-family PR review is still required before merge.

Discussion Criteria Mapping

• OQ1 authority / landing path -> AC: implement as a child of Epic #12225 and align with ADR 0018; do not create a parallel portal contract.
• OQ2 root graph shape -> AC: use a connected @graph or document a validation-driven minimal bridge; keep the #12234 machine-spec topology.
• OQ3 Brain schema type -> AC: Brain / Agent OS is SoftwareSourceCode, never SoftwareApplication.
• OQ4 FAQ topology -> AC: keep FAQ Schema.org-valid and page-visible, either inside the graph or as a stable connected script.
• OQ5 Dream Pipeline placement -> AC: use mechanism-level Agent OS wording, not mystical tagline copy.
• OQ6 Neural Link placement -> AC: frame Neural Link as the live-runtime possession bridge, not a generic chat widget.
• OQ7 proof point placement -> AC: keep May 2026 counts out of meta and JSON-LD descriptions; if used elsewhere, preserve merged/closed-only qualification.
• OQ8 naming -> AC: machine surfaces use Neo.mjs; Neo is alternateName or anchored shorthand.
• OQ9 visible-copy backing -> AC: inspect and adjust portal visible-copy files so schema claims are page-backed.
• OQ10 social preview -> AC: add Open Graph basics; record Twitter/X card decision.

Decision Record Impact

aligned-with ADR 0018 and depends-on Discussion #12234's machine-spec graduation. This ticket graduates Discussion #12235 into executable work under Epic #12225.

Acceptance Criteria

• apps/portal/index.html no longer describes Neo only through the old runtime/application-engine register.
• <meta name="description"> uses concise snippet-grade organism-apex copy and does not paste the longer package-description form.
• Open Graph basics exist: og:title, og:description, og:type, and og:url; image tags are present only with a verified asset or deliberately omitted with rationale.
• JSON-LD no longer has the Brain / Agent OS typed as SoftwareApplication.
• JSON-LD uses stable connected IDs for the root Neo.mjs entity, Body/runtime, Brain /ai, maintainer/institution, and FAQ.
• FAQ remains Schema.org-valid and backed by visible page content.
• Dream Pipeline / Golden Path appears only as mechanism-level Agent OS wording.
• Neural Link is represented as the live-runtime possession bridge, not as a generic chat or support widget.
• May 2026 proof counts are excluded from <meta> and JSON-LD descriptions; any visible/social use keeps the merged/closed-only qualifier.
• Implementation inspects the portal visible-copy files and either backs every schema claim visibly or removes the unsupported claim.
• Generated outputs such as apps/portal/llms.txt and sitemap files are not hand-edited.
• Focused validation inspects the final head/JSON-LD shape, and cross-family review is completed before merge.

Out of Scope

• Facts-only drift such as version, Node requirement, and MCP-server count; that remains #12231.
• Editing generated SEO outputs directly.
• Rewriting README, VISION, or learn/benefits/ surfaces.
• Changing the canonical apex wording itself.
• Shipping unsupported social-card image promises.

Avoided Traps

• Treating the Brain / Agent OS as a second product-like SoftwareApplication.
• Forking #12225 or ADR 0018 into a separate portal identity contract.
• Copying package-level long description text into the meta-description register.
• Putting informal operator-language or competitive slop wording into machine surfaces.
• Hiding unsupported claims inside JSON-LD without page-visible backing.
• Hand-editing generated files instead of the generator-owned source.

Related

• Parent epic: #12225
• Graduates: #12235
• Depends on machine-spec graduation: #12234
• Related facts-only sibling: #12231
• ADR 0018: Neo Identity Source-of-Truth Model
• neo-identity-update skill

Origin Session ID

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

Handoff Retrieval Hints

Retrieval Hint: "portal machine surfaces JSON-LD Open Graph organism apex" Retrieval Hint: "Discussion 12235 Option B portal @graph Brain SoftwareSourceCode" Retrieval Hint: "apps/portal/index.html agent-operating-system SoftwareApplication mistag"