Filed from the work on #10486, deliberately not folded into that PR so it stays to its file surface (packages/cli/src/utils/collect-docs.ts + tests).
What goes stale
content/docs/ui/doc-pages.mdx carries an interim warn callout (added by PR #10483) that states the opposite of what the collector will do once #10486's branch lands. Two places in that file:
1. The <Callout type="warn"> at ~line 210:
<Callouttype="warn">
**`tags` cannot be set from a `src/docs/*.md` file today.** The frontmatter reader
extracts single-line scalars — `title`, `description`, `order`, `group` — and has no case
for a list, so a `tags:` block in a Markdown doc is not collected and the doc reaches the
resolver with no tags. The schema key and the matcher are both live, so a doc declared
programmatically in a stack's `docs` array does carry tags and does match. For the flat
Markdown path, express the grouping with a name glob instead.
</Callout>
Every sentence of it becomes false: the reader gains a list case, a tags: block is collected, and the doc reaches the resolver with its tags. The closing steer ("express the grouping with a name glob instead") stops being a workaround and becomes merely one of two options — DocSchema.tags' own TSDoc still prefers a name convention where one exists, so the preference survives, but not as a limitation.
2. The frontmatter table row at ~line 208:
|`tags`| the operand of a group's `include: { tag }` rule |**not read from frontmatter** — see below |The "Set from" cell needs to become the frontmatter spelling, alongside the order:/group: rows above it.
Why it must not be dropped
Leaving the callout in place replaces one false statement with another — the same defect wearing different clothes. Today it correctly warns authors away from a path that silently does nothing; after #10486 it steers them away from the path that works.
What the replacement should say
Once #10486 lands, the accurate text is:
tagsis read from src/docs/*.md frontmatter, in the two ordinary YAML sequence spellings — inline tags: [tutorial, beginner] and the block form of - item lines.- The reader is deliberately minimal and is not a YAML engine. A
tags: in any other spelling is reported, not dropped: a docs/frontmatter-tags warning surfaces through os lint, os validate and os compile. - Tags belong to the doc, not to one translation — a
<name>.<locale>.md variant that declares tags: gets the same warning and the tags must move to the base file. DocSchema.tags' existing steer stands on its own merits: prefer a name convention (include: "crm_guide_*") when one exists; tags are for membership that cuts across naming.
There is also a sentence at ~line 303 describing "three scalars" (order, group, tags) — tags is a list, not a scalar, and that wording is worth correcting in the same pass.
Sequencing
Blocked-by: #10486 — the callout is correct today and should only change when the collector change is merged, not before.
Filed from the work on #10486, deliberately not folded into that PR so it stays to its file surface (
packages/cli/src/utils/collect-docs.ts+ tests).What goes stale
content/docs/ui/doc-pages.mdxcarries an interim warn callout (added by PR #10483) that states the opposite of what the collector will do once #10486's branch lands. Two places in that file:1. The
<Callout type="warn">at ~line 210:Every sentence of it becomes false: the reader gains a list case, a
tags:block is collected, and the doc reaches the resolver with its tags. The closing steer ("express the grouping with a name glob instead") stops being a workaround and becomes merely one of two options —DocSchema.tags' own TSDoc still prefers a name convention where one exists, so the preference survives, but not as a limitation.2. The frontmatter table row at ~line 208:
The "Set from" cell needs to become the frontmatter spelling, alongside the
order:/group:rows above it.Why it must not be dropped
Leaving the callout in place replaces one false statement with another — the same defect wearing different clothes. Today it correctly warns authors away from a path that silently does nothing; after #10486 it steers them away from the path that works.
What the replacement should say
Once #10486 lands, the accurate text is:
tagsis read fromsrc/docs/*.mdfrontmatter, in the two ordinary YAML sequence spellings — inlinetags: [tutorial, beginner]and the block form of- itemlines.tags:in any other spelling is reported, not dropped: adocs/frontmatter-tagswarning surfaces throughos lint,os validateandos compile.<name>.<locale>.mdvariant that declarestags:gets the same warning and the tags must move to the base file.DocSchema.tags' existing steer stands on its own merits: prefer a name convention (include: "crm_guide_*") when one exists; tags are for membership that cuts across naming.There is also a sentence at ~line 303 describing "three scalars" (
order,group,tags) —tagsis a list, not a scalar, and that wording is worth correcting in the same pass.Sequencing
Blocked-by: #10486 — the callout is correct today and should only change when the collector change is merged, not before.