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.

Updated 

Process flow

  Start
      |
      v
  Core steps (see walkthrough below)
      |
      v
  Outcome
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.