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

* fix(spec): give the client-SDK surface a page-scoped docs root

`check:skill-examples` resolves modules per SURFACE, and a root was always a
whole subtree — so "which packages may this page import?" was a property of the
tree a page lives in. `content/docs/**` resolves against `@objectstack/spec`
alone, and spec does not depend on `@objectstack/client`, so a marker on any
docs fence importing the SDK red with TS2307 on correct code. Two pages
recorded that in prose and left their SDK blocks deliberately unmarked.

`SourceRoot.pages` makes a root a page SET rather than a tree, so the two SDK
pages join the client-SDK surface that already resolves those packages for its
19 TSDoc blocks — no new resolution environment and no new extraction code.
The scoped root's `pages` and the broad root's `excludePages` read one shared
constant, and two guards prove the partition every run: no file may be scanned
by two surfaces, and every scoped page must exist.

Opts in the four fences that are self-contained (Quick Start, the
`createFilter()` chain and the React Hooks block on the SDK page; the
`services.data` example on the data-service page). The remaining nine are
continuation fragments that read Quick Start's `client` and stay unmarked; both
pages' notes now record the measurement rather than the old constraint.

* fix(spec): the scoped-page guard must skip a root whose dir is absent

`assertScopedPagesExist()` asserted SDK_DOCS_PAGES unconditionally, but this
script is run against repo-SHAPED sandbox trees as well as the repo: the #7181
dist-freshness pins build one that seeds skills/, packages/spec/src and the two
client packages and has no content/docs at all. There the guard reported both
SDK pages missing and — being an assert that runs before everything else —
spoke ahead of the three verdicts those tests pin, hijacking a positive
control, a staleness refusal and an orphan-marker finding alike.

`sourceFiles()` already skips a root whose `dir` does not exist. The defect was
two predicates disagreeing about whether a root is present in this checkout at
all, the same shape as the two fence closers (#11690) and the two
fence-ownership notions (#11355) this file has already collapsed. The guard now
restates that one rule.

The rename protection is untouched: content/docs always exists in a real
checkout, so a page renamed inside it is still judged and still reds. Pinned in
both directions, with a control — an absent dir is silent in BOTH predicates,
while the identical page list under a dir that DOES exist is still flagged, so
the exemption is the dir and not a predicate gone quiet.

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-litant

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.