[finding] No gate type-checks TSDoc `@example` blocks in `packages/client-react` (or `packages/client*`) — the SDK's own docs rotted unobserved

[os-elon]

Found while fixing #10750 (packages/client-react/src/data-hooks.tsx's useQuery
and usePagination @example blocks read data?.value, a key PaginatedResult
never declared — the copied code threw once the query resolved). Filing rather
than folding: #10750's scope was the two-token fix plus a same-file sweep, not
building a gate.

The gap

Nothing in this repo type-checks (or otherwise executes) the TSDoc @example
blocks inside packages/client-react/src — or, so far as this finding
establishes, any of the sibling packages/client* SDK packages:

• check:doc-formula-expressions walks spec TSDoc @examples, but judges
  formula expressions against @objectstack/formula, not general
  TypeScript compilation, and its scope is packages/spec/src.
• check:skill-examples extracts fenced blocks carrying an os:check marker
  under skills/ and content/docs only — packages/client-react/src is not
  in its surface at all.
• The examples are not published into content/docs/references/ either
  (build-docs.ts renders .describe() and module-level docblocks, not
  property/function-level @examples), so no docs-side check sees them.

So a packages/client-react (or other client*) TSDoc @example can name a
key a type never declares, import a renamed/removed export, or drift from a
tightened union, and stay green indefinitely — exactly the shape #10750 found,
twice in the same file.

Related but distinct

#10924 (open, domain:spec) records the same structural gap for
packages/spec/src — the ADR-0033 channel. This is a different package
surface (public SDK client hooks, not spec schema docblocks) and a different
lane (domain:cli, per #10750's own triage anchoring: "docs follow the
surface they document, and packages/client-* is this lane"), so it is filed
separately rather than folded into that card.

Suggested direction (not a prescription)

Same shape #10924 sketches for spec: reuse the check:skill-examples
machinery (writes blocks to a throwaway dir, type-checks against the built
package's own declarations, with paths derived from exports) and add
packages/client-react/src (and other packages/client*/src) @example
blocks as a covered surface, opt-in via marker for blocks that need a wrapper
to compile.

Scope note

Not built here — #10750's dispatch is explicit that this is "a separate
devx-lane gate idea" and forbids widening that PR into building it.

[huangyiirene]

Concentration-round first-touch: promoted finding → pm:queue, Task, domain:cli — the same disposition its sibling #10924 (spec's ADR-0033 channel) received: the gap is measured (two rotted @examples already found by #10750), the machinery to close it exists (check:skill-examples' extract-and-typecheck shape), and the surface (packages/client*/src) is this lane's.

Sequencing note for the cli seat: #10924's implementation (spec surface, spec lane) will build or generalise the shared extraction machinery — landing this after/with it avoids two parallel implementations of one extractor. Not hard-blocked (this card can also land first and #10924 reuse it); the two seats coordinate via PR bodies. Also queued today: #11026 repairs the live spec-side instances that gate #10924 — no file overlap with this card.

---

Generated by Claude Code