Handbook

JSON examples (builders)

These files live in docs/examples/ beside docs/schemas/. They are not runtime fixtures — they track the same shapes tests/test_docs_schemas.py validates.

Landing · Updated

Builder JSON sample flow

How hand-edited samples stay aligned with schemas and pytest validation in CI.

  1. StartA schema or envelope change signals that samples may be stale.
  2. Core steps (see walkthrough below)Edit the schema, update matching sample-*.json files, then run pytest.
  3. OutcomeCI keeps scrubbed, deterministic examples builders can cite safely.
Samples stay scrubbed; extend the matrix whenever route families stabilize
Example Schema Use
sample-wizard-session.json wizard-session.schema.json Session envelope persisted for Wizard
sample-cursor-launch-pack-manifest.json cursor-launch-pack-manifest.schema.json ZIP manifest fragment
sample-api-error.json api-error.schema.json Canonical { ok: false } error shape

Refresh workflow

  1. Edit schema under docs/schemas/ when the Python server changes envelopes.
  2. Update matching sample-*.json and run:

bash pytest tests/test_docs_schemas.py

  1. Mention behavioral changes in Schemas and API (builders) if HTTP tables move.

Classic vs Studio coverage

Area Primary doc
HTTP inventory HTTP API route catalog + Schemas and API (builders) (GitHub narrative)
Wizard contracts Builders schemas + Wizard chapters (schema sources on GitHub)

More narrative context for example authors: examples README (GitHub) — machine-oriented one-liner beside the tracked JSON corpus.

Scenario stubs (safe, no secrets)

Product area What to walk through
Classic Open / dashboard after install; confirm workspace scan ran (Install).
Studio Complete Studio 101 path on /studio/.
Wizard Throwaway session on hub + session URL (Wizard 101) — experimental.
Docs Health Run a scan from Docs Health; inspect severity labels only.
LLM / Fleet Local provider probe without pasting API keys (LLM setup).
API / schema Validate sample-api-error.json with pytest tests/test_docs_schemas.py.

Full worked narratives live in tutorials; this hub stays anchored to checked-in JSON so CI stays deterministic.