docs(ui): `report` and `theme` have generated references and no guide, and `doc-pages.mdx` never mentions `book`

[os-elon]

Part of #10206
Blocked-by: #10210

Why blocked

Not a dependency of substance — a hot-file serial. #10210 holds the first position on content/docs/ui/meta.json; this card takes the second. Two agents editing one nav file is the collision the serial discipline exists to prevent. This card returns to pm:queue when #10210 closes; nothing else about it is waiting on anything.

The gap — three subjects, one shape

Each is an authorable surface with a generated schema reference and no page teaching it. Same defect shape, same fix method, same directory, one meta.json — folded into one card under the family-dispatch gates.

report — references/ui/report.mdx (148 lines). defineStack({ reports }), describe string 'Analytics Reports'. The only prose anywhere is the "Binding a report" section of data-modeling/analytics.mdx, which is written from the dataset side and assumes you already know what a report is. capabilities/analytics.mdx has a ## Reports heading but that page is business-language evaluation material, not authoring.

theme — references/ui/theme.mdx (137 lines). defineStack({ themes }), describe string 'UI Themes'. Total hand-written coverage is one sentence in ui/index.mdx: "Themes define palettes, typography, and spacing as metadata — the showcase example ships light and dark theme variants."

book — references/system/book.mdx (172 lines). defineStack({ books }), ADR-0046 §6, describe string 'Documentation navigation spines — ordered groups with derived membership'. content/docs/ui/doc-pages.mdx is the page that covers the doc kind, and the string "book" appears in it zero times. The navigation spine that turns flat src/docs/*.md into an ordered structure is invisible.

File surface

• content/docs/ui/reports.mdx — new
• content/docs/ui/theming.mdx — new
• content/docs/ui/doc-pages.mdx — edit (a book section + how doc and book compose)
• content/docs/ui/meta.json — two added entries

⛔ Do not touch content/docs/ui/pages.mdx or content/docs/ui/react-pages.mdx — #10210 owns them. Nothing outside content/docs/ui/.

Nav placement

Into the existing top group, not the ---Recipes--- group: reports after dashboards, theming after reports. Resulting order — index, apps, pages, react-pages, views, actions, dashboards, reports, theming, translations, forms, doc-pages, setup-app, ---Recipes---, …. react-pages will already be there from #10210; take main as you find it and do not re-order anything you did not add.

What to write

reports.mdx

From ReportSchema (packages/spec/src/ui/report.zod.ts):

• what a report is and how it differs from a list view and from a dashboard widget — lead with the distinction, it is why the reader is here;
• report types, groupings, aggregates, filters, formatting — whatever the schema actually declares;
• the two data paths: object-bound and dataset-bound. data-modeling/analytics.mdx §"Binding a report" already covers the dataset side — cross-link it, do not duplicate it, and make sure the two pages agree;
• permissions/sharing on a report if the schema carries any.

theming.mdx

From ThemeSchema (packages/spec/src/ui/theme.zod.ts):

• what a theme declares — palette, typography, spacing, and the real token names;
• how light/dark variants are authored (the showcase example ships both — read it rather than inventing an idiom);
• how a theme is selected and scoped at runtime;
• ⚠️ the relationship to the hsl(var(--token)) convention that ui/react-pages.mdx (docs(ui): kind:'react' / kind:'html' page authoring has no guide, and the Page Properties table omits kind and source entirely #10210) tells react-page authors to use. These are two ends of one system and the pages must not contradict each other. If docs(ui): kind:'react' / kind:'html' page authoring has no guide, and the Page Properties table omits kind and source entirely #10210 has landed by the time you write, read it and align; if it has not, write the token half from the schema and note the cross-link for review.

doc-pages.mdx — the book half

From BookSchema (packages/spec/src/system/book.zod.ts) and ADR-0046 §6:

• what a book is: an ordered group with derived membership — say what derives it, precisely;
• how doc items and a book compose into a rendered documentation surface;
• a worked example alongside the existing doc example;
• keep the existing doc content intact — this is an addition, not a rewrite.

⛔ Non-goals

• Do not touch packages/spec/**. Dead or contradictory schema properties are domain:spec findings — report them.
• Do not duplicate generated property tables; link references/**.
• Three subjects, one PR — but three independently checkable pieces. A PR that lands two of them well and one as a stub is a rework, not a partial success.

Gates (derived at dispatch time via node scripts/pm/dispatch-gates.mjs, not recalled)

check:doc-anchors, check:docs-audit-scope, check:docs-redirects, check:published-readme-links, check:role-word, check:cross-package-test-inputs, and the spec liveness set (check:empty-state, check:liveness, check:strictness-ledger, check:variant-docs). Re-derive against your actual diff; ADR anchor checks apply once you cite ADR-0046 decision letters.

Acceptance

• Reports, theming and the book spine are each reachable from the Views & Apps sidebar and authorable from the page alone.
• reports.mdx and data-modeling/analytics.mdx agree; theming.mdx and react-pages.mdx agree.
• Named gates green.

[os-elon]

Claim: epic #10206 PM loop, round 4 (unlock)
Session: session_01GawRwpD44VwBDVy3hs77AX
Branch: claude/issue-10237-ui-reports-theming-book
Worktree: objectstack-issue-10237
Domain: domain:devx
File surface: content/docs/ui/reports.mdx, content/docs/ui/theming.mdx, content/docs/ui/doc-pages.mdx, content/docs/ui/meta.json, plus the mechanical .claude/workflows/docs-accuracy-audit.js regeneration (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus — no path-derived mandate (dispatch-gates.mjs --tier), no contract surface, PM judgment call
Clause-②: no
Serial constraints cleared: #10281 MERGED at 17:27:49Z, which was this card's only Blocked-by:. The hot-file serial on content/docs/ui/meta.json is released — no other open PR touches it. No other in-flight card in this epic shares a file with this one.

Unlock re-verified on the merged ref, not on the upstream card's say-so. git fetch origin main (9a1ed7a09..f094214b3), then:

• content/docs/ui/react-pages.mdx — present on origin/main;
• content/docs/ui/meta.json — react-pages is entry 4, immediately after pages, matching what this card predicted;
• content/docs/ui/reports.mdx and content/docs/ui/theming.mdx — absent, so this card's work is still needed and its "take main as you find it, do not re-order anything you did not add" instruction is accurate as written.

Blocked-by: #10210 in the body is now exhausted and satisfied; left in place as the record of why this card waited, and inert — the card is pm:dispatched and will not be re-selected by the unlock scan.

---

Generated by Claude Code