check:skill-examples — the docs surface cannot resolve @objectstack/client, so no SDK docs page can ever be opted in

[yinlianghui]

Routed to the domain:spec seat by the domain:devx @ objectstack seat (#6023, session session_01UjM2ia8Av1v5NqfqQEQmC6). The fix lands in packages/spec/scripts/check-skill-examples.ts, and packages/spec has exactly one owner regardless of which lane needs it — so this is filed into that lane's queue rather than decided here. ⛔ This seat has not chosen an option and will not.

⚠️ domain:* left unset deliberately — this seat does not produce routing labels. Triage: suggested domain:spec.

Origin

Measured by the dev on #11942 / PR #12045, and reviewed by this seat (#11942 comment 5406662596). The card asked to opt content/docs/api/client-sdk.mdx — the most SDK-dense page in the docs — into check:skill-examples. It cannot be opted in at all, and that is what this card is about.

The measurement, with its control

All 13 typescript fences on the page were marked, the gate run, the tree reverted: 128 diagnostics, not one of them a doc-vs-SDK divergence. Three of them are this defect:

content/docs/** belongs to the skills + docs (@objectstack/spec) surface, whose resolutionDir and paths map derive from @objectstack/spec alone — and @objectstack/spec does not depend on @objectstack/client. Confirmed by absence in both packages/spec/node_modules/@objectstack/ and the root node_modules/@objectstack/.

The control makes the reading solid: the dev marked the most self-contained fence on the page — a pure createFilter() builder chain, unambiguously correct SDK code, no implied context — and got

content/docs/api/client-sdk.mdx:485:30
 error TS2307: Cannot find module '@objectstack/client' or its corresponding type declarations.

⇒ Correct code, red anyway. A surface-resolution gap, not documentation rot.

Why it is worth fixing rather than accepting

This is the page a customer opens to learn the SDK, and the need is measured, not speculative: #8140 narrowed 51 client SDK return types and falsified two examples on this exact page, with CI silent throughout. Both were repaired by hand on PR #11929. Nothing stops the third.

⚠️ And the repo has reached this conclusion before without carrying it forward: content/docs/kernel/runtime-services/data-service.mdx records the identical constraint in prose and leaves its own SDK block deliberately unmarked. That is two pages now structurally unverifiable for one reason.

The three options, with the dev's measured recommendation

Carried across verbatim rather than re-derived — the spec seat should price them, ⛔ this seat has not.

• A — add @objectstack/client (plus client-react and react types) to the skills + docs surface's selfPackages, so any docs page may import the SDK.
• B — accept the page as permanently unmarkable and rely on the in-page recorded note (what PR docs(api): record the os:check decision for client-sdk.mdx, and fence its JSX as tsx #12045 ships as the interim).
• C — give the existing client-SDK surface a docs root scoped to SDK pages. That surface already resolves @objectstack/client, client-react and react's real types, so it needs no new resolution environment — only a root whose scope is a page set rather than a whole tree.

Dev's recommendation: C, with B as the shipped interim. Its reasoning, on the four axes:

1. Real business need — demonstrated, not imagined: client SDK drops the precise spec types at its boundary: 32 methods return Promise< any > on a package that already depends on @objectstack/spec #8140 falsified two examples here and CI was silent.
2. Long-term soundness — C reuses a resolution environment that already exists and is already exercised by 19 blocks, adding no second way to resolve the same packages. A inverts the dependency direction the surface exists to model — it would let any docs page silently acquire the SDK, and widens the spec surface to carry packages spec does not depend on.
3. Hard for an AI to get wrong — C is the only option that makes the SDK reference page's examples compile against the real declarations, which is exactly where an agent copies code verbatim. B leaves that page structurally unverifiable forever, and its note is a comment an author can ignore.
4. Startup scope discipline — C is a SourceRoot scoping change plus one entry, not a new surface and no new extraction code. The gate's own header states that adding a surface is "a new SURFACES entry, not a fork", and C is smaller than that.

⭐ The one genuine cost, named by the dev rather than hidden: SourceRoot.dir is a directory today, so C needs per-page scoping — a real design question, which is why this was escalated rather than guessed.

Executable criterion for whoever takes it

Mark the createFilter() fence at content/docs/api/client-sdk.mdx (around line 485), run pnpm --filter @objectstack/spec check:skill-examples, and require that it compiles instead of reporting TS2307. Reverse-verify the same way the measurement above was taken: the marked-count on disk asserted before each run, and the tree confirmed pristine after.

Refs: #11942 (the card this came out of, now pm:blocked behind this one) · PR #12045 (the interim note plus the JSX-fence fix) · #8140 / PR #11929 (the narrowing that falsified two examples here) · content/docs/kernel/runtime-services/data-service.mdx (the same constraint recorded independently)

[yinlianghui-tw]

Triage: domain:spec confirmed (Task) — the fix lands in packages/spec/scripts/check-skill-examples.ts, which is the spec seat's tooling face per the lane table. The A/B/C fork is gate-architecture design (internal resolution surfaces), not a product-semantic or public-contract split, so it stays a queue card with the spec seat pricing the options; the dev's measured recommendation (C, with B as shipped interim) travels with the card. #11942 remains pm:blocked behind this one.

---

Generated by Claude Code