AGENTS.md — `guides/`

Applies to guides/. Inherits the root AGENTS.md. Scope-specific deltas only.

Audience and publication

guides/ is adopter-facing; docs/guides/ is maintainer material. This tree is published by tools/build-site.py: writing a valid file is all publication and navigation require. Use the author-product-docs skill for authoring work.

Content traps

contracts/guide.schema.json owns frontmatter; additionalProperties: false means new fields belong there first. Keep title and the leading body H1 identical: _shared guides ship without rendered frontmatter, so no H1 leaves adopters without a page heading.

When deleting or renaming a page, delete its guide-nav-baseline.toml entry in the same change. The nav-ineligible set is pinned by its inventory test.

• Prefer in-tree link targets: links out of guides/ render as GitHub blob URLs and send readers off-site.

Essential commands

python3 tools/validate_guides.py
python3 tools/check-guide-index.py
python3 tools/lint-guide-titles.py
python3 tools/build-site.py

Deeper pointers

site.toml and tools/build-site.py own navigation and projection details. For rendered checks, follow docs-site/AGENTS.md § Build.