---
id: 12255
title: Prioritize new identity guides in generated SEO
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
  - architecture
  - build
assignees:
  - neo-gpt
createdAt: '2026-05-31T13:33:57Z'
updatedAt: '2026-05-31T14:10:54Z'
githubUrl: 'https://github.com/neomjs/neo/issues/12255'
author: neo-gpt
commentsCount: 0
parentIssue: 12225
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-31T14:10:54Z'
---
# 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

| Target Surface | Source of Authority | Proposed Behavior | Fallback | Docs | Evidence |
|---|---|---|---|---|---|
| `buildScripts/docs/seo/generate.mjs#PRIORITIES` | ADR 0018 + #12225 + current `learn/tree.json` | Explicit priorities include current identity, Benefits, and cloud-deployment discovery routes | If a route is intentionally left at default, document why in PR body | PR body | Source diff + route audit |
| `apps/portal/sitemap.xml` | Generated from `getSitemapXml()` | Generated sitemap reflects updated priority values for the new high-value routes | Do not hand-edit; rerun generator | PR body | Regeneration command + generated diff |
| `learn/tree.json` route coverage | Current learn navigation | Newly prominent identity / deployment routes are considered in sitemap priority review | If route naming changes, derive from current tree before editing | PR body | `rg` / script output listing covered routes |

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

## Timeline

- 2026-05-31T13:33:58Z @neo-gpt added the `documentation` label
- 2026-05-31T13:33:58Z @neo-gpt added the `enhancement` label
- 2026-05-31T13:33:59Z @neo-gpt added the `ai` label
- 2026-05-31T13:33:59Z @neo-gpt added the `architecture` label
- 2026-05-31T13:33:59Z @neo-gpt added the `build` label
- 2026-05-31T13:34:21Z @neo-gpt added parent issue #12225
- 2026-05-31T13:48:14Z @neo-gpt assigned to @neo-gpt
- 2026-05-31T13:51:42Z @neo-opus-ada cross-referenced by #12256
- 2026-05-31T13:56:42Z @neo-gpt cross-referenced by PR #12258
- 2026-05-31T14:10:54Z @tobiu closed this issue
- 2026-05-31T14:10:54Z @tobiu referenced in commit `2acc869` - "fix(seo): prioritize identity routes in sitemap (#12255) (#12258)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-31T14:12:21Z @neo-gpt cross-referenced by #12259
- 2026-05-31T14:58:27Z @neo-gpt cross-referenced by #12225

