test(docs): run the documented examples in CI

[kannandreams]

The 2026-08-29 docs review (glyf#104) found two bugs by hand: examples/product-analytics.md documented {{ activation_health(0.82) }}, which the macro's signature rejects, and its YAML had lost the filters: block the page existed to demonstrate. Nothing catches that class — the docs are prose to CI. This makes the documented examples executable.

Part of the public-launch epic.

What the docs actually contain

I surveyed the 25 YAML blocks under docs-site/docs before designing the check:

shape	count
whole dashboard specs	5
fragments (toolbar:, filters:, sections:, summary:, …)	18
a section item (a lone component:)	1
not glyf config at all (a workflow, a glyf.yml)	2

Marking blocks by hand loses either way round: opt-in abandons 19 blocks, opt-out annotates 20. So blocks are routed by shape and nothing in the docs is annotated. A block whose top-level keys are dashboard keys is loaded through glyf.dashboard.loader; a fragment is spliced into a minimal host spec first; an item-shaped block is spliced one level deeper, which matters because a lone component: at top level is ignored by the loader — that block was passing without its macro ever being evaluated.

The four checks

1. Dashboard YAML blocks load. 24 blocks, whole or spliced.
2. Macro expressions resolve. Against the real macros, never pooled across pages: a page presenting a shipped example file resolves against that example project's dashboards/macros.py, any other page against the macros.py it documents itself. guides/dashboard-macros.md teaches a deliberately simpler activation_health than examples/product_analytics ships, and pooling them checks each page against the wrong macro.
3. Example pages match their file. product-analytics.md and finance-metrics.md present a block as shipped; both are byte-identical to product.yml and finance.yml today. This is the only check that catches an omission — a parse check cannot see a block that is no longer there, which is precisely how the filters: bug survived.
4. Every block is accounted for. Routing by shape has a hole: a block that stops looking like a dashboard stops being checked, and a misspelled top-level key is exactly the drift worth catching. Every YAML block must therefore be a dashboard, a section item, on the short list of pages holding other YAML, or explicitly marked to skip.

Mutation-checked

Each mutation was introduced, confirmed red, and reverted:

mutation	caught by
chart_theme: misspelled	every-block-accounted-for
ui.badge(nope=1, …)	macro resolution
item-block macro given a bad kwarg	macro resolution (silently passed before the item route existed)
shipped page loses its filters: block	example-matches-file
toolbar.visibility set to a value the loader rejects	YAML loads
a block marked <!-- glyf-docs: skip -->	correctly skipped, rest still checked

Notes

tests/ already runs under make test, so this is in make ci with no wiring. Suite is 189 passed, up from 126 — the new tests are parametrised per block, so a failure names the page and line.

docs-site/README.md documents the checks and the opt-out marker. Nothing uses the marker; the intent is that a broken block gets fixed rather than annotated.

One inconsistency this surfaced but does not fail on, left for a follow-up decision: guides/dashboard-macros.md:197 teaches activation_health(ctx, chart=…, field=…), while examples/product_analytics/dashboards/macros.py:9 ships activation_health(ctx, *, chart=…, field=…, threshold=80.0). Nothing is broken for users — the example page's YAML passes threshold=80 and the shipped macro accepts it — but the teaching example has drifted from the code it teaches.