Prioritize new identity guides in generated SEO

Parent epic: #12225

Context

The recent identity PR wave has merged into origin/dev, including the README / benefits / cloud-deployment framing work. The generated SEO surface still has one missed source-side priority map: buildScripts/docs/seo/generate.mjs defines const PRIORITIES = new Map([...]), and getSitemapXml() uses getPriority(id) to emit <priority> tags for sitemap entries.

Creation V-B-A on current origin/dev:

• buildScripts/docs/seo/generate.mjs still prioritizes older Body / runtime benefit pages such as benefits/ConfigSystem, benefits/FormsEngine, benefits/OffTheMainThread, benefits/Speed, plus old comparison pages.
• The same map does not include the newly important identity / Brain / deployment routes from learn/tree.json, including benefits/ArchitectureOverview, benefits/AIEngineeringTeam, benefits/AgentMemory, benefits/SelfEvolution, benefits/AgentOSOnYourCodebase, benefits/DeployingTheAgentOS, benefits/ObjectPermanence, benefits/JSONFirstUIs, or the agentos/cloud-deployment/* guide cluster.
• learn/tree.json now puts the new Benefits identity pages at the top of the Benefits subtree and exposes the Agent OS cloud-deployment guides under AgentOS/CloudDeployment.
• Duplicate sweep: Knowledge Base MCP is unavailable (Failed to access collections: The requested resource could not be found); exact rg across local issue/discussion archives found no dedicated SEO priority-map ticket; live gh issue list --search "buildScripts/docs/seo/generate.mjs PRIORITIES sitemap priority benefits cloud deployment" returned [].

The Problem

The sitemap priority map is now behind the identity rollout. Crawlers still receive elevated priority for older runtime/body pages while the new public-facing identity surfaces and v13 deployment guides fall back to DEFAULT_PRIORITY = 0.5 unless they happen to match an older entry.

That is the same class of generated-output-source drift ADR 0018 warns about: if we update apps/portal/sitemap.xml directly it will be clobbered; if we leave PRIORITIES stale, the generated machine-facing discovery surface undersells the current Neo story even after the prose files are correct.

The Architectural Reality

buildScripts/docs/seo/generate.mjs owns this behavior:

• PRIORITIES is the manual route-priority map.
• getPriority(id) normalizes route IDs and returns the explicit map entry or DEFAULT_PRIORITY.
• getSitemapXml() uses that value to emit <priority> in sitemap XML.
• apps/portal/sitemap.xml is generated output and must be regenerated, not hand-edited.
• learn/tree.json is the authoritative navigation source for discoverable learn routes and now encodes the priority ordering that the sitemap map should not contradict.

This is framing/discovery governance, not facts coherence. It is not covered by #12244, which is facts-only by design and explicitly avoids brittle framing/prose gates.

The Fix

Update buildScripts/docs/seo/generate.mjs so PRIORITIES reflects the current identity and deployment discovery priorities.

Expected implementation shape:

1. Audit learn/tree.json against PRIORITIES and identify identity / Brain / deployment routes that should not use the default sitemap priority.
2. Add explicit priority entries for the new Benefits identity pages and Agent OS cloud-deployment guides.
3. Reconsider whether older comparison/body pages should keep their current relative weight now that the apex, Brain, and v13 deployment routes are the higher-value discovery path.
4. Regenerate apps/portal/sitemap.xml from the generator and inspect the generated priority output.
5. Keep llms.txt behavior intact unless the implementation discovers the same route-priority source is reused there.

Contract Ledger Matrix

Decision Record Impact

Aligned-with ADR 0018 (identity source-of-truth model and generated-output-source discipline) and ADR 0014 (cloud deployment topology). No ADR change expected.

Acceptance Criteria

• PRIORITIES includes explicit entries for the new high-value Benefits identity pages: at minimum benefits/ArchitectureOverview, benefits/AIEngineeringTeam, benefits/AgentMemory, benefits/SelfEvolution, benefits/AgentOSOnYourCodebase, benefits/DeployingTheAgentOS, benefits/ObjectPermanence, and benefits/JSONFirstUIs.
• PRIORITIES includes explicit entries for the Agent OS / cloud-deployment guide cluster that should rank above default discovery weight: at minimum agentos/SharedDeployment, agentos/DeploymentCookbook, agentos/cloud-deployment/WhyDeploy, agentos/cloud-deployment/Overview, agentos/cloud-deployment/Day0Tutorial, agentos/cloud-deployment/TenantIngestionModel, and agentos/cloud-deployment/Security.
• Implementation audits the remaining agentos/cloud-deployment/* routes (Configuration, CustomSources, CustomParsers, HookWiring, PipelineWiring, MigrationPath) and either assigns explicit priority or documents why default priority is acceptable.
• Older comparison/body/runtime entries are challenged against the new discovery hierarchy; no stale priority ordering leaves the old web-framework comparison path above the organism / Agent OS / deployment path without rationale.
• apps/portal/sitemap.xml is regenerated from buildScripts/docs/seo/generate.mjs.
• Focused validation proves the generated sitemap contains updated <priority> values for representative Benefits and cloud-deployment routes.
• Cross-family review completed before merge because this touches an identity/discovery surface.

Out of Scope

• Rewriting README / VISION / Benefits prose; those landed in the identity PR wave.
• Changing learn/tree.json ordering; this ticket consumes the tree, it does not reshape it.
• Package keywords / GitHub topics; those are separate discovery metadata surfaces.
• Facts-only Node/MCP coherence checks; covered by #12244.
• Introducing a brittle exact-match prose coherence gate.

Avoided Traps

• Editing generated apps/portal/sitemap.xml without changing generate.mjs.
• Letting old framework-comparison routes outrank the current category-defining Agent OS / organism routes by accident.
• Treating all new cloud-deployment docs as equal; the operator-facing overview / why / Day-0 / tenant model / security routes likely deserve higher weight than deep implementation details.
• Folding this into #12244; #12244 is explicitly facts-only and should not absorb framing / priority governance.

Related

• Parent: #12225
• Related: #12244 (facts-only guard; not a duplicate)
• Related: #12252 (README v13 deployment framing)
• Related: #12254 (generated llms.txt identity header)
• ADR 0018: Neo Identity Source-of-Truth Model
• ADR 0014: Cloud Deployment Topology + Scheduler Task Taxonomy

Origin Session ID: 87203e0b-c9ff-4a82-a67b-9a0dda760c32 Retrieval Hint: "buildScripts docs seo generate PRIORITIES sitemap priority identity benefits cloud deployment"