docs(skills): make the analytics dataset a module-completeness line item

[claude]

Fixes #13696

What this changes

The published catalog's module-completeness list — skills/objectstack-ui/SKILL.md § CRM UI Blueprint (Metadata-First), framed verbatim as "the default for 'build a complete metadata app UI' tasks" — priced src/views/**, src/apps/**, dashboards and reports, but never the dataset the last two bind. git grep 'src/datasets' over the whole published catalog returned zero hits before this PR.

That omission is the card's finding, exactly. An agent grew a complete leave-management module from one sentence — object with 15 fields, an approval flow, five profiles of permissions, four views, a nav entry wired into an existing app — and every one of those works in the app. The module was simply not in the report builder's dataset list, because the analytics face needs a second declaration nothing told the agent to write.

Three edits:

1. skills/objectstack-ui/SKILL.md — the blueprint table gains an Analytics dataset row (src/datasets/*.dataset.ts), placed above Dashboards and Reports so it reads in dependency order. The Reports row, which used to carry "Bind a dataset …" as a sub-clause, now selects rows/values from that dataset — the binding obligation moved up to a peer line item rather than being restated. Net +1 line.
2. content/docs/getting-started/build-with-claude-code.mdx — the docs half of the grow-a-module path. The objectstack-ui prompt row now asks for the dataset before the dashboard (the previous prompt, "Add a dashboard with a metric for open tickets", is the exact request that silently produces nothing when no dataset exists), and the section's habits list gains "A module is not finished until its analytics face exists."
3. scripts/check-skills-token-ratchet.mjs — the CEILINGS row for that SKILL.md, see below.

Why the dataset stays a separate declaration

Per the ruling on the card (#13696 comment 5475439419, maintainer 2026-08-31, director seat batch #15, verbatim and untranslated: 「同意」), option C: dataset-only report sources are design intent, not a defect — the dataset layer carries the governed joins, row-level security and measure semantics an object does not express. The ruling's own words for the remedy: 「发布技能与文档的「长模块」路径必须把 dataset 声明列为模块完整性的一部分」.

Deliberately not done here, per that same ruling:

• ⛔ Option A (objects automatically reportable) — not taken up; it is capability expansion straight past a deliberate governance face, and reopening it needs named user pull.
• ⛔ Option B (auto-generating datasets on the authoring side) — revisited after C lands, not ridden along on this PR.
• ⛔ The widget property panel's inline object query path is not taught as a workaround. The filing agent recorded it honestly as unverified (verifying it would have meant changing configuration, outside that read-only pass), and it stays unverified — so it is omitted rather than half-taught.

The token ratchet, and the arithmetic

check-skills-token-ratchet is shrink-only per file and skills/objectstack-ui/SKILL.md had 12 tokens of headroom (25113 / 25125) — roughly 48 bytes, against a table row of ~200. The gate names two ways forward: pay by genuine deletion in the same file, or raise the ceiling "in a PR whose body quotes a maintainer ruling authorizing it". This PR does both, taking the deletion first so the raise is as small as it can honestly be.

In bytes, which is what the ceil(utf8 bytes / 4) convention divides:

	bytes
new Analytics dataset blueprint row	+204
Reports row, shrunk by the obligation moving out of it	−7
sentence deleted in § Dataset-Bound Widgets (see below)	−77
net	+120

25113 → 25143 tokens. The existing 12 tokens of headroom absorb part of that, so the ceiling moves 18 (25125 → 25143) and lands at zero headroom — the next token in this file is paid for by deleting one, exactly as before.

The deleted sentence is Reports bind the same way (dataset + rows + values + runtimeFilter). It sat one line below a sentence that already names reports among the surfaces that bind a dataset and select named dimensions and values, so it restated report binding a second time inside its own paragraph; the only fact unique to it, runtimeFilter, is authored and explained in § Report Configuration below it. It is genuine deletion, not a re-wrap — a re-wrap moves no tokens and pays nothing.

The authorizing ruling is the one quoted above, and the raise follows the two precedents already in that table (objectstack-automation 12643 and objectstack-pm-dispatch 14391), which likewise carry the maintainer's words in the row comment and the arithmetic in the raising PR's body. check-ratchet-remedy-authority stays green: the ⛔ MAINTAINER-ONLY compliance token is untouched.

Verification

Union derived mechanically on the final head 0e8a4e97 (node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack; the derivation is byte-identical before and after the commit) — 39 families across 29 workflow files, all green:

• 36 passed on the first sweep, including check:pm-governed-merges, check:skill-frame-sync, check:skill-identifier-liveness, check:skill-compatibility, check:corpus-claim-drift, check:doc-authoring, check:docs-single-h1, check:role-word.
• 4 came back PREREQUISITE NOT MET (unbuilt workspace packages — not findings, and each says so in its own text). After turbo run build over @objectstack/spec, @objectstack/lint, @objectstack/formula, @objectstack/client-react, @objectstack/client all four are green:
  • check:doc-formula-expressions — 22 record-scoped formula example(s) across 427 files / 1451 TS blocks judged clean
  • check:doc-security-posture — 26 ObjectSchema.create example(s) … carry an os validate-clean security posture
  • check:docs — 230 generated files in sync with packages/spec
  • check:skill-examples — 260 prose examples type-check across 3 surface(s)
• 1 is structurally NOT MEASURED locally: check-test-completeness grades a saved turbo run test log and exits 3 when handed none. Its own text says this branch is unreachable in CI and "it is not a red, and there is nothing here to fix."

Ratchet family re-run on the committed head 0e8a4e97, after the last commit rather than before it:

✓ check-skills-token-ratchet self-test: 64 cases pass.
✓ check-skills-token-ratchet: skills/objectstack-ui/SKILL.md is 25143 tokens (ceiling 25143; headroom 0).
✓ check-skills-token-ratchet: 38 authored bundle file(s) within their ceilings; 11 generator-owned file(s) measured, not ratcheted.
OK  check-ratchet-remedy-authority: 180 scripts swept; 12 mark the expanding remedy ⛔ MAINTAINER-ONLY, 6 turn it down outright
check-nul-bytes: OK (scanned 7660 text file(s); no raw ASCII control bytes).

Bundle total moves 186520 → 186550 tokens.

Every exit code above was captured before any pipe, and each verdict is quoted from the line the gate printed itself.

Changeset

None, and skip-changeset applied — this diff publishes nothing from any package. That follows the merged sweep-flight precedent exactly: #13833, #13861, #13867 and #13891 each touched skills/** only, each carried documentation + skip-changeset, and none carried a changeset file.

Scope

Draft, and governed on both counts (skills/** is a governed surface; the ratchet row is a maintainer-authority surface) — human merge or the pinned-approval queue path, never a self-flip to ready.

Session: https://claude.ai/code/session_01Msg17tAHJ3jVTYFgHydCm2

---

Generated by Claude Code