docs(skills): teach the binding data-table actually reads, in all three sites

[os-support-ai]

Fixes#5126
Fixes#5337

The defect

Three published skill guides taught { "type": "data-table", "bind": "customers" }, and two of them added a mechanism sentence: "the table component calls useDataScope("customers") and gets the array."

DataTableRenderer takes its rows from data: rawData = EMPTY_ROWS off the node, and packages/components/src/renderers/complex/data-table.tsx matches neither bind nor useDataScope (grep, zero hits, re-measured on this branch). Copying the example threw nothing and logged nothing — a header over the "No results found" empty state, which is the hardest shape for an AI author to self-check.

Measured here through the real SchemaRenderer, with a provider that really does hold the array:

retired bind form : 1 tbody row -> ["No results foundTry adjusting your filters or search query."]
taught data form : 2 tbody rows -> ["Ada Lovelace","ada@example.com","Grace Hopper","grace@example.com"]

Direction — inherited, not re-opened

#5125 was adjudicated as enforce-or-remove deletion of the only bind-reading table renderer (landed in PR #5338), so data-table does not gain bind here: the teaching is what changes. Making it read bind would widen the authorable key surface that sibling ruling declined to widen; that would be a new Feature card through the decision inbox, and is out of scope here.

Site census — measured on origin/mainbdf8cf76e, and repo-wide

file	data-table blocks	which carried bind	verdict
skills/objectui/guides/schema-expressions.md	:377	:377	corrected
skills/objectui/guides/data-integration.md	:185	:185	corrected
skills/objectui/rules/protocol.md	:100, :109, :130	:130 only	:130 corrected; :100 / :109 left alone

protocol.md:100 and :109 are the "No Schema Property Invention" pair — a violation example spelling fields, and its columns counterpart. Neither carries bind; both are about the property-invention rule and are correct as they stand.

The zeros are counter-probed, not assumed. Grepping each whole file on origin/main for the known-present terms: schema-expressions.md has 13 bind lines and 3 useDataScope lines; protocol.md has 5 and 2; data-integration.md has 5 and 3. So the extractor does see these files, and "only one block in protocol.md binds" is a reading rather than a silent miss.

Widened past the three cards named: across all 307 markdown/MDX files tracked under content/docs, skills, packages, apps and examples, exactly 3 fenced json blocks paired data-table with a bind key — the three above — and 0 remain on this branch. Counter-probe on the same scan: 8 json blocks carry a bind key on both refs, so the zero is the finding and not a broken matcher. (The first version of that scan made the language tag optional in the fence pattern, mis-paired opening and closing fences, and reported zero on origin/main too. The counter-probe is what caught it.)

What changed

• All three sites now demonstrate bind with list, which does call useDataScope, bound to a string array. Binding list to ordinary records renders the right number of empty entries — the sibling trap list 从不渲染 children,且全仓不存在 item / index 迭代作用域 —— schema-expressions.md 的「Iteration scopes」整节是空头支票 #4797 recorded — so the example data is node-shaped on purpose.
• Each site now names the real readers and says plainly that data-table is not one of them.
• The useDataScope mechanism sentence, which described a different component, is gone.
• schema-expressions.md and data-integration.md keep a data-table example, now in its real inline-data form.
• data-integration.md:143 carried the same over-broad claim in miniature ("Components with bind: "customers" will then access ...", unqualified). One clause, same defect class, same file, named here because a fix nobody names is scope creep.

The reader list is list and tree-view in @object-ui/components, plus object-grid, object-kanban, object-chart, object-data-table, object-gallery, object-timeline and object-pivot from the plugin packages. That list is itself pinned (below) — the first draft said object-pivot-table, which is the component file (ObjectPivotTable.tsx); the key it registers is object-pivot, and a copied type nothing is registered under is the same class of silent failure.

The columns pin is intact

The columns entries in schema-expressions.md and data-integration.md are byte-identical to origin/main — they do not appear in the diff at all, git matched them as context. Their { name, label } spelling is the separate open question on #5120, parked at needs-user-decision with the maintainer to be taken with #5350; nothing here decides it, and both examples stay true whichever way it lands. That question is not addressed by this PR and #5120 remains open.

One columns line did go: protocol.md:130's "columns": [...] placeholder, which left with the data-table node it belonged to. It carried no column-key spelling at all, and protocol.md is not one of the two files the #5120 census fork names, so it pre-empts nothing — flagged here rather than buried.

Verification — against the renderer, not against a reading of it

New pin: packages/components/src/__tests__/skill-guide-data-table-binding.test.tsx. It lifts the JSON blocks out of the real guide files at run time and feeds them to the real SchemaRenderer, so it pins the shipped bytes rather than a copy. Three halves: counter-probe (each guide must still carry a bind key in some block, so the "no data-table binds" assertion is a reading), doc-sameness, and behaviour.

Build artifacts between the edit and the thing under test: none, on every leg. The root vitest.config.mts aliases every workspace package to its src/, so @object-ui/react and the renderers resolve to source; the guides are read from disk at run time. No dist/ sits in the path, so no rebuild is needed for a leg to be honest.

All runs from the repo root (pnpm exec vitest run PATH), per the invocation guard — never pnpm --filter PKG test.

Green on 99d8721a3:

vitest run packages/components/src/__tests__/skill-guide-data-table-binding.test.tsx
Test Files 1 passed (1) Tests 15 passed (15) exit 0
vitest run scripts/__tests__/doc-version-claims.test.ts \
scripts/__tests__/check-skills-paths.test.ts \
packages/plugin-dashboard/src/__tests__/ObjectDataTable.columnIdentity.test.tsx
Test Files 3 passed (3) Tests 61 passed (61) exit 0
pnpm --filter @object-ui/components run type-check exit 0
eslint packages/components/src/__tests__/skill-guide-...test.tsx exit 0 (0 errors, 0 warnings)
node scripts/check-skills-paths.mjs exit 0 (94/95 paths resolve, 1 baselined)
node scripts/check-control-bytes.mjs exit 0 (4758 files)
node scripts/check-package-self-import.mjs exit 0
node scripts/check-changeset-presence.mjs exit 0 (empty-frontmatter exemption)
node scripts/check-changeset-fixed.mjs / -no-major.mjs exit 0

Reverse verification, both legs run and both stated. With the three guides reverted to origin/main and the test unchanged, the pin goes red: 9 failed / 4 passed, exit 1 — the three no data-table example is bound cases, the useDataScope sentence case, both inline-data render cases, and the three list cases. Restoring the guides returns 15/15, exit 0. The four that pass under the mutation are the three counter-probes (main teaches bind too, correctly, so they must pass) and the empty-state measurement, which is true on both refs — that is the point of it.

Second ablation, on the reader-list guard specifically: putting object-pivot-table back into schema-expressions.md fails it with `object-pivot-table` must be registered by exactly one plugin package: expected [] to have a length of 1. Restored, 15/15.

Governed surface — do not merge

skills/** is maintainer-merge-only. This is a draft on purpose: please do not enable auto-merge and do not merge it from a passing seat. It waits for a maintainer.

Changeset

.changeset/5126-data-table-bind-teaching.md, empty frontmatter. Nothing published changes: three files under skills/, one new test, and no package source. The empty frontmatter is the gate's explicit exemption, and the only reason a declaration is owed at all is that the new test lives under packages/components/src/.

---

Generated by Claude Code

[github-actions]

✅ Console Performance Budget

Metric	Value	Budget
Main entry (gzip)	25.3 KB	350 KB
Entry file	index-C18Xhb4h.js	—
Status	PASS	—

---

📦 Bundle Size Report

Package	Size	Gzipped
app-shell (index.js)	9.83KB	3.70KB
app-shell (runtime-config.js)	7.42KB	2.32KB
app-shell (types.js)	0.01KB	0.04KB
app-shell (urlParams.js)	10.06KB	3.86KB
auth (AuthContext.js)	0.31KB	0.24KB
auth (AuthGuard.js)	1.17KB	0.53KB
auth (AuthProvider.js)	29.33KB	7.05KB
auth (AuthShell.js)	3.49KB	1.40KB
auth (ForgotPasswordForm.js)	12.21KB	3.45KB
auth (LoginForm.js)	18.13KB	5.39KB
auth (PreviewBanner.js)	0.90KB	0.50KB
auth (RegisterForm.js)	6.64KB	2.21KB
auth (SocialSignInButtons.js)	9.60KB	3.89KB
auth (UserMenu.js)	3.40KB	1.22KB
auth (auth-gate-events.js)	1.29KB	0.66KB
auth (authStyles.js)	5.04KB	1.72KB
auth (createAuthClient.js)	40.21KB	10.79KB
auth (createAuthenticatedFetch.js)	6.34KB	2.43KB
auth (index.js)	2.71KB	1.22KB
auth (invitation-status.js)	1.22KB	0.70KB
auth (org-roles.js)	6.66KB	2.78KB
auth (phone-identifier.js)	1.11KB	0.66KB
auth (types.js)	0.59KB	0.35KB
auth (useAuth.js)	5.02KB	0.88KB
auth (useIsWorkspaceAdmin.js)	1.61KB	0.85KB
collaboration (CommentThread.js)	26.07KB	7.56KB
collaboration (LiveCursors.js)	3.17KB	1.27KB
collaboration (PresenceAvatars.js)	6.49KB	2.64KB
collaboration (PresenceProvider.js)	2.79KB	1.13KB
collaboration (index.js)	1.65KB	0.73KB
collaboration (useCollaborationTranslation.js)	6.05KB	2.52KB
collaboration (useCommentSearch.js)	1.98KB	0.88KB
collaboration (useConflictResolution.js)	7.75KB	1.86KB
collaboration (useMentionNotifications.js)	1.81KB	0.68KB
collaboration (usePresence.js)	6.33KB	1.84KB
collaboration (useRealtimeSubscription.js)	7.91KB	2.01KB
components (index.js)	505.53KB	113.13KB
core (index.js)	4.11KB	1.62KB
create-plugin (index.js)	10.08KB	3.26KB
data-objectstack (index.js)	159.80KB	44.34KB
fields (index.js)	237.07KB	59.46KB
i18n (LocalizationContext.js)	1.76KB	0.96KB
i18n (currency.js)	1.22KB	0.64KB
i18n (i18n.js)	4.28KB	1.75KB
i18n (index.js)	3.42KB	1.39KB
i18n (pickLocalized.js)	3.69KB	1.73KB
i18n (provider.js)	23.13KB	7.63KB
i18n (useDisplayLocale.js)	2.85KB	1.45KB
i18n (useObjectLabel.js)	30.51KB	7.57KB
i18n (useSafeTranslation.js)	7.77KB	3.13KB
layout (index.js)	38.97KB	10.98KB
mobile (MobileProvider.js)	0.92KB	0.49KB
mobile (ResponsiveContainer.js)	0.94KB	0.38KB
mobile (breakpoints.js)	1.51KB	0.70KB
mobile (createOfflineDataSource.js)	5.61KB	1.74KB
mobile (index.js)	1.50KB	0.62KB
mobile (offlineQueue.js)	3.91KB	1.35KB
mobile (pwa.js)	0.97KB	0.49KB
mobile (serviceWorker.js)	1.48KB	0.62KB
mobile (serviceWorkerSource.js)	3.41KB	1.48KB
mobile (useBreakpoint.js)	1.54KB	0.65KB
mobile (useGesture.js)	6.96KB	1.98KB
mobile (useOfflineSync.js)	1.99KB	0.72KB
mobile (usePullToRefresh.js)	2.53KB	0.85KB
mobile (useResponsive.js)	0.71KB	0.42KB
mobile (useResponsiveConfig.js)	1.36KB	0.63KB
mobile (useSpecGesture.js)	4.32KB	1.64KB
mobile (useTouchTarget.js)	1.01KB	0.54KB
permissions (MePermissionsProvider.js)	9.35KB	3.31KB
permissions (PermissionContext.js)	0.31KB	0.25KB
permissions (PermissionGuard.js)	0.89KB	0.45KB
permissions (PermissionProvider.js)	4.42KB	1.42KB
permissions (evaluator.js)	5.12KB	1.74KB
permissions (index.js)	0.91KB	0.41KB
permissions (store.js)	0.91KB	0.42KB
permissions (useFieldPermissions.js)	1.28KB	0.52KB
permissions (usePermissions.js)	1.81KB	0.83KB
plugin-ai (index.js)	15.75KB	3.80KB
plugin-calendar (index.js)	46.62KB	12.83KB
plugin-charts (index.js)	64.75KB	18.37KB
plugin-chatbot (index.js)	181.21KB	43.14KB
plugin-dashboard (index.js)	128.07KB	32.77KB
plugin-designer (index.js)	212.39KB	42.83KB
plugin-detail (index.js)	241.46KB	60.56KB
plugin-editor (index.js)	2.46KB	1.10KB
plugin-form (index.js)	124.19KB	30.20KB
plugin-gantt (index.js)	164.10KB	39.87KB
plugin-grid (index.js)	197.30KB	53.06KB
plugin-kanban (index.js)	52.93KB	14.60KB
plugin-list (index.js)	111.66KB	27.13KB
plugin-map (index.js)	20.08KB	6.62KB
plugin-markdown (index.js)	13.72KB	4.69KB
plugin-report (index.js)	43.49KB	11.93KB
plugin-timeline (index.js)	26.68KB	7.66KB
plugin-tree (index.js)	8.50KB	2.88KB
plugin-view (index.js)	84.52KB	20.67KB
providers (DataSourceProvider.js)	0.75KB	0.39KB
providers (MetadataProvider.js)	1.37KB	0.59KB
providers (ThemeProvider.js)	1.90KB	0.85KB
providers (UploadProvider.js)	11.66KB	3.50KB
providers (index.js)	0.44KB	0.22KB
providers (types.js)	0.01KB	0.04KB
react-runtime (index.js)	5.62KB	2.34KB
react (LazyPluginLoader.js)	3.77KB	1.33KB
react (SchemaRenderer.js)	36.10KB	12.26KB
react (data-invalidation.js)	5.05KB	2.08KB
react (index.js)	1.33KB	0.69KB
react (schema-input.js)	1.45KB	0.83KB
react (spec-input.js)	0.20KB	0.18KB
sdui-parser (codegen.js)	5.41KB	2.34KB
sdui-parser (index.js)	4.77KB	2.16KB
sdui-parser (input-type.js)	2.84KB	1.40KB
sdui-parser (parse.js)	10.76KB	3.17KB
sdui-parser (provenance.js)	3.66KB	1.82KB
sdui-parser (types.js)	0.29KB	0.24KB
sdui-parser (validate.js)	6.92KB	2.40KB
types (ai.js)	0.20KB	0.17KB
types (api-types.js)	0.20KB	0.18KB
types (app.js)	2.87KB	0.99KB
types (base.js)	0.20KB	0.18KB
types (blocks.js)	0.20KB	0.18KB
types (complex.js)	0.20KB	0.18KB
types (crud.js)	0.20KB	0.18KB
types (dashboard-filter-alias.js)	6.23KB	2.74KB
types (data-display.js)	0.20KB	0.18KB
types (data-protocol.js)	0.20KB	0.19KB
types (data.js)	0.20KB	0.18KB
types (designer.js)	1.87KB	0.85KB
types (disclosure.js)	0.20KB	0.18KB
types (error-code.js)	1.54KB	0.88KB
types (feedback.js)	0.20KB	0.18KB
types (field-types.js)	0.20KB	0.18KB
types (form.js)	0.20KB	0.18KB
types (http-retry.js)	4.32KB	2.02KB
types (index.js)	3.08KB	1.53KB
types (layout.js)	0.20KB	0.18KB
types (managed-by.js)	0.19KB	0.18KB
types (mobile.js)	2.59KB	1.31KB
types (navigation.js)	0.20KB	0.18KB
types (objectql.js)	0.20KB	0.18KB
types (overlay.js)	0.20KB	0.18KB
types (permissions.js)	0.20KB	0.18KB
types (plugin-scope.js)	0.20KB	0.18KB
types (record-components.js)	0.20KB	0.19KB
types (record-semantics.js)	1.28KB	0.67KB
types (registry.js)	0.20KB	0.18KB
types (reports.js)	0.20KB	0.18KB
types (spec-report.js)	5.05KB	1.93KB
types (system-fields.js)	3.33KB	1.54KB
types (theme.js)	0.20KB	0.18KB
types (ui-action.js)	3.40KB	1.71KB
types (views.js)	0.20KB	0.18KB
types (widget.js)	0.20KB	0.18KB

Size Limits

• ✅ Core packages should be < 50KB gzipped
• ✅ Component packages should be < 100KB gzipped
• ⚠️ Plugin packages should be < 150KB gzipped

[os-support-ai]

⛔ Maintainer merge required — this PR is deliberately parked green

PM review, round 18 (session session_01RV6yuVCxymHYE16PL9vQkE). All 19 gate jobs are completed: success; the two non-green entries are dependabot and Test (coverage), both skipped by design, not gates. Nothing is red, nothing is pending, nothing is cancelled.

It is held as a draft with auto-merge not enabled because skills/** is a governed surface (alongside docs/adr/**, .claude/**, AGENTS.md, CLAUDE.md, content/docs/releases/) and lands by maintainer merge only. ⛔ No execution seat should enqueue this.

Surface verified independently

git diff --name-only origin/main...refs/pull/5371/head → 5 files: the three skill guides, one new test in packages/components/src/__tests__/, one changeset. Within the declared file surface, no breach.

The pin I ordered held — checked, not taken on trust

The two files this PR edits are the same lines #5120's census fork is parked on with you (whether columns spelled { name, label } is authored surface, to be taken with #5350). I ordered the columns entries kept byte-identical so this PR could not pre-empt that decision.

Measured on the diff: the only columns line touched anywhere under skills/ is a removal of protocol.md's "columns": [...] placeholder, which left with the data-table node it belonged to — it carries no column-key spelling at all, and protocol.md is not one of the two files #5120's census names. The four other matches my scan caught are { "name": "Ada Lovelace", … }record values inside the new inline data array, not columns[] entries. In schema-expressions.md and data-integration.md the columns blocks do not appear in the diff at all — git matched them as unchanged context. #5120 is untouched and remains yours to decide.

Why it is worth your time

The defect is the shape that is hardest for an AI author to self-check: copying the documented example threw nothing and logged nothing, it rendered a header over "No results found". The dev measured both states through the real SchemaRenderer — retired form 1 empty row, taught form 2 rows with all 4 cells — and pinned it with a test that lifts the JSON out of the real guide files at run time, so it pins the shipped bytes rather than a copy. Reverse-verified both legs: guides reverted → 9 failed / 4 passed; restored → 15/15. The 4 survivors are the counter-probes and the empty-state control, green on both refs by construction.

It also caught two of its own errors with guards it then pinned: the reader list first said object-pivot-table, which is the component file — the registered key is object-pivot; and its first repo-wide census script made the fence language tag optional, mis-paired fences, and reported zero on origin/main too. The counter-probe is what caught that.

One thing to weigh before merging — filed, not fixed

#5372, measured through the real renderer with identical columns in all three legs: the only working route from a provider dataSource into a data-table is the properties envelope that protocol.md tells authors not to use. Node-level data: "${data.customers}" renders the empty state (top-level keys are never expression-evaluated); props: is evaluated but not hoisted. It is the inverse polarity of the seam #4799 corrected.

That does not block this PR — correcting a false teaching is right regardless. But it is the strongest evidence yet that the #5125/#5126 pair left a real gap, and it is the decision input if the closed direction 2 ("make data-table read bind") is ever reweighed. ⛔ I have not reopened it and am not proposing to.

---

Generated by Claude Code