chore: examples/test-app is a fixture, not an example — rename or add real SDK examples #1463

Context (verified 2026-07-28; decision recorded 2026-07-28)

examples/test-app is the Expo dogfood fixture (its own README: "a minimal Expo Router fixture app for agent-device and skillgym experiments"), 496KB git-tracked across 46 files. It is the repo's only examples/ content, so anyone looking for SDK usage examples by convention finds a test fixture instead. The actual SDK snippets live only in website/docs/docs/client-api.md, while the real consumer (the agent-device-cloud bridge) imports all 11 export subpaths — there is no runnable Node.js SDK example anywhere.

Maintainer decision (thymikee): Option 2 — add real Node.js SDK examples under examples/sdk/. The examples/test-app → fixtures/ rename is explicitly deferred (blast radius: ~10 test-app:* package scripts, test-app-build-cache.yml, skillgym configs, docs). Do NOT rename or move examples/test-app in this issue.

Task

Create examples/sdk/ with small, runnable, typechecked Node.js scripts demonstrating the public SDK surface, sourced from the snippets in website/docs/docs/client-api.md and the import patterns visible in the repo's own integration tests (test/integration/installed-package-metro.test.ts).

Acceptance criteria

• At minimum these examples, each a standalone .ts runnable with node --experimental-strip-types (repo Node is >=22.12): root client session (createAgentDeviceClient → open → snapshot/tap → close, with error handling via the exported error types), metro (normalizeBaseUrl/resolveRuntimeTransport), contracts (typed result consumption, e.g. centerOfRect on a snapshot node), and one of batch (runBatch) / finders (findBestMatchesByLocator).
• Imports use the package name (agent-device/...), not relative src/ paths — examples must exercise the published export map. Wire them to resolve against the local build (workspace/file link or tsconfig paths) so they typecheck in CI without publishing.
• CI typechecks the examples by extending an existing lane (e.g. a tsconfig included in check:tooling's typecheck or a small vitest include) — no new workflow.
• Each example has a top comment stating what it demonstrates and its prerequisites (daemon running, device/simulator available); examples that need live hardware must still typecheck without it.
• examples/README.md (new) indexes the examples and clarifies that test-app/ is a fixture, not an example — one line, no rename.
• Drift guard: the client-api.md snippets either import/include from these files or a test asserts the doc snippets compile — pick the cheaper mechanism that fits the existing docs build.
• pnpm check:tooling and pnpm test:unit green.