fix(spec): give the client-SDK surface a page-scoped docs root so SDK pages can opt into check:skill-examples

content/docs/api/client-sdk.mdx

@@ -24,42 +24,48 @@ pnpm add @objectstack/client
 ```
 
 {/*
- CONTRIBUTOR NOTE — none of this page's TypeScript fences carries an
- `os:check` marker, and that is a recorded decision rather than an omission.
-
- `check:skill-examples` compiles marked blocks per SURFACE. `content/docs/**`
- belongs to the "skills + docs" surface, whose resolution dir and `paths` map
- are derived from `@objectstack/spec` alone — and `@objectstack/spec` does not
- depend on `@objectstack/client`. So a marker on any fence that imports the SDK
- reds with TS2307 "Cannot find module '@objectstack/client'" — a
- surface-resolution gap, not doc-vs-SDK drift.
-
- Every other fence is a deliberate continuation fragment: Quick Start
- establishes `client` once and each later block continues that implied context,
- so a marker there reds with TS2304 "Cannot find name 'client'". Making either
- class compile would mean hand-declaring the SDK's own types, or injecting
- casts into prose whose subject IS the real API — pinning each example to
- itself and teaching worse code than the page teaches now.
-
- Measured on this page (all 13 fences marked, then reverted): 128 diagnostics,
- every one TS2307 / TS2304 / TS18004 / TS18046 / TS2591 / TS7006 / TS7026 /
- TS2875. Not one was a doc-vs-SDK divergence.
-
- The React Hooks block near the end is fenced tsx, not typescript, because it
- IS JSX: the gate writes every block out with its fence's own extension, and
- JSX in a .ts file is a syntax error. That reaches past this page — tsc stops
- at syntax errors and never runs the semantic pass, so one such block would
- suppress type-checking for every marked block across skills/ and
- content/docs/ (measured here: 128 semantic diagnostics collapse to 0). Please
- do not retag it back.
-
- The marker becomes worth adding here the day the docs surface can resolve
- `@objectstack/client` — the same condition recorded in
- content/docs/kernel/runtime-services/data-service.mdx.
+ CONTRIBUTOR NOTE — three of this page's fences carry an `os:check` marker and
+ are compiled by `check:skill-examples` against the real SDK declarations; the
+ rest deliberately do not. Both halves are measured, not assumed.
+
+ This page belongs to the client-SDK SURFACE, not to the broad
+ `content/docs/**` one. That surface resolves `@objectstack/client`,
+ `@objectstack/client-react` and react's real types, so a marked block here
+ imports the SDK exactly as a reader's own code does. It was not always so:
+ `content/docs/**` resolves against `@objectstack/spec` alone, spec does not
+ depend on the client, and every SDK import here used to red with TS2307
+ "Cannot find module '@objectstack/client'". The page is carved out by name
+ (`SDK_DOCS_PAGES` in packages/spec/scripts/check-skill-examples.ts) — moving
+ or renaming it without updating that list fails the gate loudly rather than
+ silently returning the page to the surface that cannot resolve it.
+
+ What IS marked: Quick Start, the `createFilter()` builder chain, and the
+ React Hooks block — the three that stand alone. What is not: every block that
+ continues Quick Start's implied context. Quick Start establishes `client`
+ once and each later block reads it, so a marker there reds with TS2304
+ "Cannot find name 'client'"; the error-handling blocks additionally read a
+ `catch` binding that is `unknown` (TS18046). Making those compile would mean
+ hand-declaring the SDK's own types or injecting casts into prose whose
+ subject IS the real API — pinning each example to itself and teaching worse
+ code than the page teaches now.
+
+ Measured with all 13 fences marked, then reverted: 114 diagnostics, TS2304 /
+ TS18046 / TS18004 / TS2591, spread over the nine continuation blocks — and
+ ZERO TS2307. Before the carve-out the same sweep produced 128 diagnostics
+ including TS2307 on every SDK import. Not one diagnostic in either sweep was
+ a doc-vs-SDK divergence; that is what the three marked blocks now hold.
+
+ The React Hooks block is fenced tsx, not typescript, because it IS JSX: the
+ gate writes every block out with its fence's own extension, and JSX in a .ts
+ file is a syntax error. That reaches past this page — tsc stops at syntax
+ errors and never runs the semantic pass, so one such block would suppress
+ type-checking for every marked block on its whole surface. Please do not
+ retag it back.
 */}
 
 ## Quick Start
 
+{/* os:check */}
 ```typescript
 import { ObjectStackClient } from '@objectstack/client';
 
@@ -513,6 +519,7 @@ const results = await client.data.query('account', query);
 
 The `FilterBuilder` provides a rich set of filter methods:
 
+{/* os:check */}
 ```typescript
 import { createFilter } from '@objectstack/client';
 
@@ -669,6 +676,7 @@ For React applications, use `@objectstack/client-react`:
 pnpm add @objectstack/client-react
 ```
 
+{/* os:check */}
 ```tsx
 import { ObjectStackProvider, useClient, useQuery } from '@objectstack/client-react';
 import { ObjectStackClient } from '@objectstack/client';

content/docs/kernel/runtime-services/data-service.mdx

@@ -146,6 +146,7 @@ Call these methods from code that **holds** the binding — a managed runtime ha
 a hook body: a hook has no `services` key to reach through (see above), and reads other
 objects via `ctx.api`.
 
+{/* os:check */}
 ```ts
 import type { ObjectStackClient } from '@objectstack/client';
 
@@ -179,11 +180,17 @@ export async function recentOrdersForContact(data: DataService, contactId: strin
 }
 ```
 
-The block carries no `{/* os:check */}` marker, and that is a measurement rather than an
-omission: `check:skill-examples` compiles marked blocks against the built
-`@objectstack/spec` declarations only — its `paths` map is derived from that package's own
-`exports`, and `@objectstack/spec` does not depend on `@objectstack/client`. A marked
-block here would therefore have to hand-declare `DataService` instead of importing it,
-which pins the example to itself and nothing else. The marker becomes worth adding the day
-this surface has a spec-side contract to import (see the
-[Canonical source](#canonical-source) note).
+The block carries an `{/* os:check */}` marker, so `check:skill-examples` compiles it
+against the real `@objectstack/client` declarations on every CI run: if `data.get` /
+`data.find` / `data.query` change shape, this example reds rather than rotting. It used to
+carry no marker, and that was a measurement rather than an omission — marked blocks under
+`content/docs/**` were compiled against `@objectstack/spec` alone, which does not depend
+on `@objectstack/client`, so importing `ObjectStackClient` here red with TS2307 and
+hand-declaring `DataService` instead would have pinned the example to itself and nothing
+else. This page is now carved out by name to the client-SDK surface (`SDK_DOCS_PAGES` in
+`packages/spec/scripts/check-skill-examples.ts`), which resolves the SDK; renaming or
+moving the page without updating that list fails the gate rather than silently dropping
+the check.
+
+The signature listing under [Methods](#methods) stays unmarked: it is a listing of method
+shapes, not a compilable statement, and it cannot parse at all.