`content/docs/ui/index.mdx` credits themes with `spacing` (retired at #3494) and its Cards grid is missing five of the module's pages

[os-elon]

Found while writing content/docs/ui/theming.mdx for #10237 (docs PR #10483). Out of that card's declared file surface (ruling: the four files in the claim comment), so filed rather than fixed.

1. A retired key is advertised as a theme capability

content/docs/ui/index.mdx, "The building blocks":

Themes define palettes, typography, and spacing as metadata — the showcase example ships light and dark theme variants.

spacing was removed from ThemeSchema at #3494 and is a guidance tombstone today, with this prescription:

spacing was removed in #3494 — the theme engine (objectui generateThemeVars) never emitted a spacing variable, so authoring it was a silent no-op. Emit your own scale through customVars (e.g. { "space-4": "1rem" }).

So the index page names, as one of three headline theme capabilities, a key the schema now rejects by name. "typography" is also weaker than it reads: after #5021 the only live typography input is fontFamily.base, which emits --font-sans; the size / weight / line-height / letter-spacing scales are tombstones too.

Suggested replacement, accurate against the current schema:

Themes define palettes, a base font family, radii and shadows as metadata — the showcase example ships light and dark theme variants.

The frontmatter description on the same file carries "themes" only, so it needs no change.

2. The Cards grid has drifted from meta.json

The "What's in this module" grid lists 7 pages; the sidebar carries 13 in the top group. Missing: actions, react-pages, translations, and — once PR #10483 lands — reports and theming. Nothing gates the grid against meta.json, which is why it drifts quietly: check:docs-audit-scope reconciles the audit workflow's list against the filesystem, and check:doc-anchors resolves fragments, but neither has an opinion about whether an index page links its siblings.

This half is an observation rather than a defect — a hand-curated index legitimately need not list everything. Worth a decision on which it is, because the answer determines whether a gate should exist.

Scope note

Both are one-file edits to content/docs/ui/index.mdx. Item 1 is mechanical and pinned by the schema's own tombstone text; item 2 needs the curation decision first.

[os-zhuang]

Triage: lands in content/docs/ui/index.mdx (one file) → domain:devx, pm:queue, type Task.

Scope queued:

1. Item 1 in full — replace the theme-capability sentence with the schema-accurate one (the card's suggested wording is pinned by the spacing tombstone and the 主题引擎发出的 9 组 CSS 变量零消费方(--font-size-* / --z-* / --duration-* …):ADR-0049 该判去留 #5021 typography retirement; use it or tighter).
2. Item 2, editorial half only — add the missing sibling pages to the Cards grid (actions, react-pages, translations, and reports/theming once PR docs(ui): add the report and theming guides, and the book spine half of doc-pages #10483 lands — check that PR's merge state at dispatch time and include accordingly). This is cheap curation restoring the index to "lists its module".

Explicitly not queued: a gate reconciling the grid against meta.json — a hand-curated index legitimately need not enumerate everything, and there is no pull for tooling here. If drift recurs enough to annoy, that's a future finding.

Size/model suggestion: S, mode:subagent, sonnet.

---

Generated by Claude Code

[claude]

Claim: /pm-dispatch domain:devx execution seat.
Session: session_01DdCnBGcHeufjrq7drTD3wt
Branch: claude/issue-10487-ui-index-retired-claims
Worktree: objectstack-issue-10487
Domain: domain:devx
File surface: content/docs/ui/index.mdx and content/docs/capabilities/analytics.mdx

Batched with #10488 — both are stale factual claims in hand-written docs, found by the same #10237 docs seat and filed out of its declared surface.

⭐ PM ruling on #10488's stated hesitation, so the dev is not left to guess: that card notes capabilities/** is business-language evaluation material where "the bar for editing is a product-voice decision, not a schema fact." Correct. But the defect being fixed is a schema fact — under ADR-0021 every joined report block is dataset-bound, so "joined (multi-object)" is false. ⇒ Fix the factual claim minimally and ⛔ leave the marketing voice, structure and tone alone. Rewriting the framing would be the product-voice change this lane does not own.

⛔ Governed surface out of scope (docs/adr/**, .claude/**, skills/**, AGENTS.md, CLAUDE.md, content/docs/releases/**) and the #9465 epic fence (.changeset/ tooling, cut-rc.yml, release.yml, root package.json).
⭐ Changeset: AGENTS.md:943 — "Pure bug fixes do not require a changeset"; a diff that publishes nothing takes the skip-changeset label via the additive POST /labels (⛔ never a whole-set PUT — see #5533). Precedent: PR #10502.
⚠️ This repo has no formatter of record (verified: no format/prettier script, prettier not in devDeps, no .prettierrc/.editorconfig) — ⛔ do not run prettier --write; its defaults reject files already on main (#10622).

---

Generated by Claude Code

[claude]

{
 "issue": 10487,
 "folded_issue": 10488,
 "status": "done",
 "branch": "claude/issue-10487-ui-index-retired-claims",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/10639",
 "premise_still_valid": true,
 "summary": "Both cards' schema claims were re-verified against origin/main (47aff09388) before editing and all held, with ONE sub-claim falsified: #10487 says five pages are missing from the ui Cards grid; on today's tree it is four. The card projected `theming` as landing with `reports` in PR #10483, but #10483 landed as d0c0865f06 with a follow-up commit 'docs(ui): withhold theming.mdx per maintainer split ruling' — content/docs/ui/theming.mdx has no git history and is absent from both the directory and meta.json, so no card was added for it. Fixed: (a) ui/index.mdx theme sentence now names the four keys ThemeSchema's docblock certifies live, replacing both the retired `spacing` and the overstating `typography`; (b) the Cards grid gained actions/react-pages/reports/translations as four pure insertions with no existing card line moved; (c) analytics.mdx 'joined (multi-object)' became 'joined (several dataset panels)' — two words, nothing else on the page touched, per the PM ruling that the fact is in scope and the product voice is not. #10488's leg-2 'scheduled email digests' sentence was verified and left UNCHANGED: the composed delivery path exists (schedule-type flow + notify + sys_email_template).",
 "verified_claims": [
 {
 "claim": "#10487: `spacing` is a tombstone in ThemeSchema today, with the prescription text the card quotes",
 "holds": true,
 "evidence": "packages/spec/src/ui/theme.zod.ts:339 in THEME_RETIRED_KEY_GUIDANCE — \"`spacing` was removed in #3494 — the theme engine (objectui `generateThemeVars`) never emitted a spacing variable, so authoring it was a silent no-op. Emit your own scale through `customVars` (e.g. `{ \\\"space-4\\\": \\\"1rem\\\" }`).\" Byte-for-byte the card's text. It is a `guidance` entry consulted for unrecognized_keys on a strict shell, so the key is rejected BY NAME."
 },
 {
 "claim": "#10487: after #5021 the only live typography input is `fontFamily.base`, emitting `--font-sans`; the size/weight/line-height/letter-spacing scales are tombstones",
 "holds": true,
 "evidence": "theme.zod.ts TypographySchema docblock: \"Base font family. The size / weight / line-height / letter-spacing scales were retired at #5021 and are `retiredKey()` tombstones below.\" On fontFamily.heading: \"`base` is the ONE font-family key with a live consumer (it emits `--font-sans`) and is unchanged.\" fontSize/fontWeight/lineHeight/letterSpacing are each retiredKey(); fontFamily.heading and .mono likewise. ThemeSchema docblock closes it: \"`colors`, `borderRadius`, `shadows` and `fontFamily.base` have live consumers and stay.\" — which is exactly what the new sentence names."
 },
 {
 "claim": "#10487: the showcase ships light and dark theme variants (unchanged sentence tail)",
 "holds": true,
 "evidence": "examples/app-showcase/src/ui/themes/index.ts exports ShowcaseLightTheme (mode: 'light') and ShowcaseDarkTheme (mode: 'dark'), collected as allThemes."
 },
 {
 "claim": "#10487: the Cards grid is missing FIVE of the module's pages",
 "holds": false,
 "evidence": "FALSIFIED — it is four. meta.json's top group is index + 11 pages (apps, pages, react-pages, views, actions, dashboards, reports, translations, forms, doc-pages, setup-app); the grid listed 7. `theming` is not among them: PR #10483 landed as d0c0865f06 whose second commit is titled 'docs(ui): withhold theming.mdx per maintainer split ruling', and `git log -- content/docs/ui/theming.mdx` is empty. The doc was NOT fixed to match the card — only the four pages that actually exist were added."
 },
 {
 "claim": "#10488: JoinedReportBlockSchema declares dataset/rows/columns/values/runtimeFilter/order, and objectName/object/dataSet/source are alias entries pointing at `dataset`",
 "holds": true,
 "evidence": "packages/spec/src/ui/report.zod.ts:166. Aliases block, under the comment \"ADR-0021 single-form: the legacy inline query was removed in the cutover. These are the spellings that cutover retired, aimed at their successors.\": objectName: 'dataset', object: 'dataset', dataSet: 'dataset', source: 'dataset'. The `dataset` key's docblock: \"ADR-0021 — the dataset this block binds to (single-form). The block selects the dataset's measures by name; the legacy inline `objectName` + `columns` + `groupings` query was removed in the cutover.\" rows/columns/values/runtimeFilter all carry '(dataset-bound)' in their .describe(). NOTE: the card's six-key list is the QUERY surface, not the whole shape — the block also declares name, label, description, type and chart. Not a defect in the card, but its list is not exhaustive."
 },
 {
 "claim": "#10488: the schema docblock frames a joined report as slices of the same domain",
 "holds": true,
 "evidence": "JoinedReportBlockSchema docblock: \"Blocks are used for comparative dashboards where each panel is a different slice of the same domain — e.g. 'new customers / churned / silent' in a customer-churn report\". This supplied the replacement's word 'panel'. I did NOT adopt 'same domain' as the doc's wording: blocks may bind different datasets whose base objects differ, so it would trade a false claim for an over-narrow one."
 },
 {
 "claim": "#10488 leg 2 (triage): does a path exist making 'scheduled email digests deliver a report daily or weekly' true at capability level?",
 "holds": true,
 "evidence": "YES — sentence left unchanged, no words touched. Scheduling: FlowSchema.type enum includes 'schedule' (automation/flow.zod.ts:652); cron/interval is declared as `config.schedule` on the START node (flow.zod.ts:606-608). Delivery: schemaless-node-config.zod.ts:211 — \"`actionType: 'email' | 'slack'` were **logger-backed stubs**. They wrote a line to the log, reported success, and delivered nothing under any configuration ... `notify` (real delivery, via the messaging service) and `connector_action` were already the live mechanisms.\" notify's `template` names a sys_email_template bundle and \"the delivery path resolves `(name, recipient locale)` at delivery time and renders subject/body per recipient.\" Report side: sys_saved_report is described as \"Persisted ObjectQL report definition — re-runnable and schedulable\". The card's own observation that ReportSchema carries NO scheduling/delivery key is correct and is not a defect — the capability is composed, which is what makes the capability-level claim true."
 }
 ],
 "cards_grid_before_after": {
 "before_7": ["Apps", "Views", "Pages", "Dashboards", "Forms", "Doc Pages", "Setup App"],
 "after_11": ["Apps", "Views", "Actions", "Pages", "React Pages", "Dashboards", "Reports", "Translations", "Forms", "Doc Pages", "Setup App"],
 "added_4": ["actions", "react-pages", "reports", "translations"],
 "not_added": "theming — withheld from PR #10483 per maintainer split ruling; the file does not exist and is not in meta.json",
 "method": "four pure insertions, each next to its meta.json neighbour; no existing card line moved and the existing relative order is untouched (git diff: 5 insertions, 1 deletion across the whole file)"
 },
 "analytics_words_changed": {
 "before": "and **joined** (multi-object) —",
 "after": "and **joined** (several dataset panels) —",
 "removed": "'multi-object' — names the mechanism ADR-0021's single-form cutover deleted; objectName/object/dataSet/source are alias entries pointing at `dataset`, so a reader taking it literally hunts for a per-block object key that no longer exists",
 "added": "'several dataset panels' — names the surviving mechanism in the page's own existing vocabulary (the page already says 'shared datasets' twice) and keeps the parenthetical parallel with (detail rows) / (grouped totals) / (regions × quarters); 'panel' is the schema docblock's own word",
 "untouched": "the four-shape structure, the sentence's other three glosses, the scheduled-digest sentence, the HotCRM block, the frontmatter, tone, register and section structure. Two words, one parenthetical."
 },
 "tests": "Gate families derived with `node scripts/pm/dispatch-gates.mjs` and NO paths passed — it took the change set from the merge base itself: 'change set derived from git — 2 path(s) vs merge base 47aff0938 of origin/main and HEAD (committed 2, working tree 0, untracked 0; three-dot semantics)'. It named 11 families; all 11 plus check:nul-bytes were run AT THE FINAL COMMIT faed755bc6 (re-derived after committing; same 11 families) under scripts/pm/os-verify-lock.sh, exit codes captured by redirect-then-capture (never through a pipe). Lock verdict line: 'os-verify-lock: VERDICT command-exit 0 · held the lock 20s · waited 0s'. All 12 EXIT=0. Each gate's own verdict line: check:doc-anchors '✅ check-doc-anchors: 272 internal #fragment link(s) across 408 source file(s) all resolve to a real heading' (+ --self-test green); check:docs-audit-scope '✓ docs-accuracy-audit scope is in sync with content/docs/: 189 hand-written doc(s).' (+ two self-tests, 281 and 24 cases); check:docs-redirects 'check-docs-redirects: OK (apps/docs/redirects.mjs: 92 entries ...)' (+ --self-test, 48 assertions); check:role-word 'check-role-word: OK, no new occurrences of the reserved word.' (+ self-test OK); check:published-readme-links '✓ check:published-readme-links — 152 outbound link(s) across 60 published markdown file(s)'; check:cross-package-test-inputs 'OK: 13 package(s) read outside themselves, all declared, and turbo.json hashes every declared glob.' (+ 'All 79 self-test cases passed.'); scripts/check-cross-package-test-inputs.mjs same OK line; check:nul-bytes 'check-nul-bytes: OK (scanned 6211 text file(s) -- 6211 tracked, 0 untracked-not-ignored; skipped 5 binary; no raw ASCII control bytes).' (+ --self-test, 75 assertions); spec check:empty-state '✓ all classified (1 closed, 2 open, 4 output, 9 scope)'; spec check:liveness '✓ every governed-type property at the walk's one-level granularity is classified ...'; spec check:strictness-ledger '✓ strictness ledger: 61 file(s) across 5 triaged director(ies) — every row names a live sited file, no undeclared schema files.'; spec check:variant-docs '✓ variant/doc gate: 18 discriminated union(s) — 8 governed (every variant mentioned in a bound doc), 10 exempt.'. Every spec gate echoed its script name in its own output, so none is a zero-match --filter silent green. Both edited files were also hand-scanned for control bytes outside the gate (grep -naP over the ASCII control ranges): no matches. No ablation was involved — this is a docs-only diff with no build artifact in the loop. prettier --write NOT run (no formatter of record, #10622).",
 "changeset": "None. AGENTS.md:943 — 'Pure bug fixes do not require a changeset.' The diff is two hand-written pages under content/docs/ and publishes no package, so it took the `skip-changeset` label via additive POST /repos/.../issues/10639/labels (never a whole-set PUT, per #5533). Read back after the bots settled: PR labels are ['size/xs', 'skip-changeset'] — the additive POST preserved the bot's size label.",
 "open_questions": [],
 "out_of_scope_findings": [],
 "brief_corrections": [
 "The brief and #10487 both say FIVE grid pages are missing; on today's tree it is four — `theming` was explicitly withheld from PR #10483 ('docs(ui): withhold theming.mdx per maintainer split ruling') and content/docs/ui/theming.mdx has never existed. The doc was not bent to match the card.",
 "#10488's field list for JoinedReportBlockSchema (dataset/rows/columns/values/runtimeFilter/order) is the query surface only — the block also declares name, label, description, type and chart. The card's substantive claim is unaffected.",
 "My standing dev instructions cite `packages/plugin-email` as an ablation example; no such package exists in this repo. Irrelevant to this card, noted only because I searched for it while verifying the email-delivery path."
 ]
}

---

Generated by Claude Code