DOC-6939 Document feed coverage and the section role vocabulary

[andy-stark-redis]

Documents feed coverage and the section role vocabulary on the AI agent resources page — items B2 and B3 of DOC-6939. Documentation only: no output format changes, no build changes.

Why

Two of the applied AI team's findings were "you don't explain this" rather than "this is broken":

• Their observation 08 — the feed has 27 fewer URLs than sitemap.xml and nothing says why, so anyone diffing the two derives an unexplained shortfall.
• Their observation 06 — role is documented as five examples followed by "etc.", and they flagged that filtering or ranking on an uncontracted vocabulary breaks silently if a value is ever renamed.

What's added

A "What the feeds cover" section. It explains the exclusion as what it actually is rather than as a skip list: JSON and Markdown are configured for Hugo's section and page kinds only, so taxonomy listings, term pages and the home page produce no JSON and therefore no record. There is no filter to document — which is why the difference couldn't be explained by describing one.

It also covers the asymmetry running the other way, which the assessment spotted but couldn't account for: a page carrying _build.list: never is dropped from Hugo's page collections, and the sitemap is generated from those collections, but the page is still rendered — so it has JSON and reaches the feed while being absent from the sitemap. integrate/redis-data-integration/reference/data-transformation/cache is the current example. It's genuine reference material reached by direct link, so publishing it is correct; only the mismatch needed explaining.

A "Section roles" section. All fifteen values, with the trigger words for each, in the order the patterns are tested — because first match wins and the patterns overlap. A heading of "Version history" is history rather than compatibility purely because history is tested first, which looks like a bug from outside if you don't know the order.

The stability caveat is explicit and phrased as guidance rather than a promise: treat an unrecognized role as content rather than discarding the section. We can't offer a contract on these names until there's a schema_version to signal a change, which remains open as ticket item C1.

The sections[].id description now also states that the id matches the heading's anchor on the rendered page, so <url>#<section id> resolves. That became true with #3757 and is worth saying out loud.

Verification

• The documented vocabulary matches the feed exactly — fifteen values documented, fifteen emitted across the corpus, nothing in one set and not the other. Verified against built output rather than transcribed from ROLE_PATTERNS.
• The role table's order and trigger words check out line-by-line against ROLE_PATTERNS in build/transform_json_sections.ts.
• Both new sections reach the JSON and Markdown outputs, not just the rendered page.

One wrinkle worth knowing

This page is documentation about the feed that also appears in the feed, so a caveat written inside a {{< note >}} has to survive the AI-output path. It does — the catch-all shortcode strip removes the {{< >}} delimiters but keeps the text between them — and I confirmed the caveat text is present in the JSON content rather than assuming it.

Follow-up this doesn't do

The commit carries a Constraint trailer recording that the published table is now the vocabulary consumers filter on, so a future change to ROLE_PATTERNS has to update this page or we publish a vocabulary the feed no longer uses. A build-time check would be better than a trailer; not in scope here.

🤖 Generated with Claude Code

---

Note

Low Risk
Markdown-only documentation with no build, output format, or runtime behavior changes.

Overview
Documentation-only updates to the AI agent resources page so feed consumers can reconcile URLs with sitemap.xml and use sections[].role safely.

Adds What the feeds cover, explaining why the NDJSON corpus has fewer URLs than the sitemap (JSON/Markdown only for Hugo section/page kinds—no taxonomy, term, or home records) and the reverse case where _build.list: never pages appear in feeds but not the sitemap, plus a note that counts are snapshots.

Adds Section roles with all fifteen role values, trigger heading prefixes, and priority order (first match wins). The JSON schema now states that sections[].id matches on-page heading anchors for # links, and includes a note that roles are descriptive—not a stable contract—and unknown values should be treated as content.

^{Reviewed by Cursor Bugbot for commit b030675. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

DOC-6939

[github-actions]

Staging links:
https://redis.io/docs/staging/DOC-6939-feed-docs/ai-agent-resources/

[github-actions]

🧠 Redis Memory

Found 5 related items from repository history:

• PR — DOC-6939 Correct stale document count in the NDJSON feed docs

  Fixes the stale document count on the AI agent resources page — item A1 of DOC-6939.

• Commit — DOC-6939 Keep code-block headings out of the TOC, and close a fence that hid three sections

  DOC-6939 Keep code-block headings out of the TOC, and close a fence that hid three sections

• Commit — DOC-6939 Correct stale document count in the NDJSON feed docs

  DOC-6939 Correct stale document count in the NDJSON feed docs

• Commit — DOC-6939 Address Bugbot review on the feed output partials

  DOC-6939 Address Bugbot review on the feed output partials

• Commit — DOC-6939 Fix orphaned code placeholders and duplicate section ids

  DOC-6939 Fix orphaned code placeholders and duplicate section ids

Memory updated at b030675

[dwdougherty]

Approved.

[andy-stark-redis]

Thanks again @dwdougherty !