Context. Operator correction (2026-06-29). The guide-authoring skill §5 (SEO mechanics) is wrong on two counts, and it's the generating function behind the #14345↔#14346 SEO merge collision:
It allows regenerating the output. §5 currently says "leave them to the pipeline (or regenerate; never hand-edit)" — the "(or regenerate)" is wrong. Peers must NEVER touch apps/portal/sitemap.xml or apps/portal/llms.txt — not by hand, not by running the generator script. They are GENERATED OUTPUT owned by the data-sync pipeline, which regenerates + commits them on its next run. A peer committing them is (a) pointless — the next pipeline run overwrites the edits — and (b) the direct cause of guide-PR merge conflicts (#14345 + #14346 both committed the regenerated sitemap/llms.txt → collision).
It misses the correct registration step. A new guide is registered + weighted in buildScripts/docs/seo/generate.mjs — add + rank it in the PRIORITIES map (e.g. ['agentos/IdentityFirewall', 1.0]). §5 doesn't mention this; it's the input peers edit (alongside tree.json), distinct from the output (sitemap/llms.txt) they must not touch.
Fix. Rewrite §5: register a new guide in (1) learn/tree.json + (2) generate.mjs PRIORITIES; never hand-edit, regenerate, or commit sitemap.xml / llms.txt — the pipeline owns the output.
Acceptance Criteria
Related. Refs #14352 (the skill), #14310. Roots the #14345 / #14346 SEO conflict. Origin: operator feedback, session e145a397.
Context. Operator correction (2026-06-29). The
guide-authoringskill §5 (SEO mechanics) is wrong on two counts, and it's the generating function behind the #14345↔#14346 SEO merge collision:It allows regenerating the output. §5 currently says "leave them to the pipeline (or regenerate; never hand-edit)" — the "(or regenerate)" is wrong. Peers must NEVER touch
apps/portal/sitemap.xmlorapps/portal/llms.txt— not by hand, not by running the generator script. They are GENERATED OUTPUT owned by the data-sync pipeline, which regenerates + commits them on its next run. A peer committing them is (a) pointless — the next pipeline run overwrites the edits — and (b) the direct cause of guide-PR merge conflicts (#14345 + #14346 both committed the regeneratedsitemap/llms.txt→ collision).It misses the correct registration step. A new guide is registered + weighted in
buildScripts/docs/seo/generate.mjs— add + rank it in thePRIORITIESmap (e.g.['agentos/IdentityFirewall', 1.0]). §5 doesn't mention this; it's the input peers edit (alongsidetree.json), distinct from the output (sitemap/llms.txt) they must not touch.Fix. Rewrite §5: register a new guide in (1)
learn/tree.json+ (2)generate.mjsPRIORITIES; never hand-edit, regenerate, or commitsitemap.xml/llms.txt— the pipeline owns the output.Acceptance Criteria
guide-authoring§5 rewritten per the above (input-files vs pipeline-owned-output distinction explicit; drop the "(or regenerate)" allowance; add thegenerate.mjs PRIORITIESregistration step).ai:lint-skill-manifestgreen.Related. Refs #14352 (the skill), #14310. Roots the #14345 / #14346 SEO conflict. Origin: operator feedback, session e145a397.