@kirrosh/zond 0.21.0 → 0.23.0

package/src/cli/commands/init/templates/skills/zond.md

@@ -0,0 +1,651 @@
+---
+name: zond
+description: |
+  Primary skill for any zond work. Loads on workspace touch
+  (`apis/<name>/`, `.env.yaml`, `.api-fixtures.yaml`) AND on intent —
+  full API audit, "find bugs", "raise coverage", "test the whole API",
+  contract-drift check, schema-drift detection, post-deploy regression,
+  case study, single-flow scenario authoring, fixture pack. Hand off to
+  `zond-checks` for depth-check reference / SARIF / stateful invariants,
+  to `zond-triage` for "what broke in the last run".
+allowed-tools: [Read, Write, Edit, Bash(zond *), Bash(bunx zond *), Bash(sqlite3 *)]
+---
+
+# zond — Primary skill
+
+CLI-only. Run `zond --version` first; if missing:
+`curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh`.
+
+For depth-check reference (the catalog of conformance / security /
+stateful checks, SARIF output, m-20 invariants) — see `zond-checks`.
+For triage of a failing run — see `zond-triage`.
+
+## Iron rules (read once, apply always)
+
+- **NEVER read raw OpenAPI** with Read/cat/grep. The workspace has
+  pre-built artifacts (catalog/resources/fixtures) — use those. Drop
+  into `apis/<name>/spec.json` only when probe-class authoring needs
+  full schemas.
+- **NEVER `curl` or `wget`** — use `zond request <method> <url> --api <name>`
+  for ad-hoc HTTP so it lands in the run DB and respects auth. Never
+  shell-substitute the token by hand (`$(yq …)` is blocked by the sandbox).
+- **NEVER hardcode tokens** — put them in `apis/<name>/.secrets.yaml`
+  (auto-gitignored), reference from `.env.yaml` as `@secret:auth_token`.
+  Plain `${SHELL_VAR}` references also work. Tests read the resolved
+  value as `{{auth_token}}`.
+- **NEVER read `.secrets.yaml` directly.** Use `zond doctor --api <name> --json`
+  — reports `set | unset` and value length only.
+- **NEVER edit `.api-*.yaml`** (catalog / resources / fixtures) by hand —
+  regenerated by `zond refresh-api`. `.api-resources.local.yaml` IS the
+  hand-editable / annotate-target overlay; safe to edit. `.env.yaml`
+  values are editable (see ARV-114).
+- **NEVER invent endpoints.** Only use entries from `.api-catalog.yaml`.
+- **NEVER run destructive ops on a shared / production org without
+  `--dry-run` first.** Probes, `prepare-fixtures --apply`, `cleanup` hit
+  live APIs and can delete user data. `--dry-run` once → inspect → drop
+  the flag.
+- **NEVER share triage artefacts** outbound without `--redact-identity`.
+  Secret-redaction is on by default; identity values (org/member slugs,
+  real ids) need the extra flag.
+- **NEVER report cleanup failure as an API bug.** POST 200 → DELETE 5xx
+  is *probably* a fixture-isolation issue (orphan accumulation, race).
+  Re-run with `--no-cleanup` or isolated namespace before filing.
+- **`recommended_action: report_backend_bug` / 5xx → STOP** in interactive
+  mode (surface the request/response, get a decision; never `expect:`-mask).
+  In autonomous / loop / audit-sweep mode (no user-in-the-loop), log to
+  `api-bugs-<NN>.md`, continue the sweep — bailing on bug #1 forfeits #2..N.
+- **CRUD-run ≥80% 401/403 / `permission_denied` → `env_issue`, not bug.**
+  Token scope issue. Confirm via `zond db diagnose <run-id> --env-only`;
+  do not generate case-studies, do not `expect:`-mask.
+- **MUST run `zond doctor --api <name> --missing-only` before generating
+  fixtures or touching `.env.yaml`** — identifies unfilled keys early.
+- **Cascade cap is 8 passes** (`zond prepare-fixtures --cascade [--seed]`)
+  — never override without a written reason.
+
+## Workspace artifact model
+
+After `zond add api <name> --spec <path|url>`, `apis/<name>/` contains:
+
+```
+spec.json                    ← dereferenced OpenAPI (machine source)
+.api-catalog.yaml            ← endpoint index (method, path, params)
+.api-resources.yaml          ← CRUD chains + FK deps (auto)
+.api-resources.local.yaml    ← overlay: extensions + annotate output (hand-edit OK; appears after first `zond api annotate apply` — or create by hand to use as overlay)
+.api-fixtures.yaml           ← MANIFEST: required vars + descriptions (read-only)
+.env.yaml                    ← VALUES: variable values (user / prepare-fixtures writes)
+.secrets.yaml                ← raw secret values (auto-gitignored)
+.identity.yaml               ← non-secret identifying values (gitignored)
+tests/                       ← generated/handwritten suites
+scenarios/                   ← handwritten flow suites
+probes/                      ← probe-emitted suites
+```
+
+### Manifest vs values (the #1 source of confusion)
+
+**`.api-fixtures.yaml` = the list of vars this API needs (manifest).
+`.env.yaml` = their values.**
+
+| Op | Touches manifest? | Touches env? |
+|---|---|---|
+| `zond add api` / `refresh-api` | rebuilds | seeds skeleton |
+| `zond generate` | extends (adds new `{{vars}}` discovered) | does **not** modify |
+| `zond prepare-fixtures` | reads | writes values |
+| `zond fixtures add` / `import` | reads | writes values (manual) |
+| user editing | never | always |
+
+- `{{var}}` in a generated test but NOT in `.api-fixtures.yaml` is a
+  bug in the manifest builder / generator. Don't "fix" it by adding to
+  `.env.yaml`.
+- A key in `.env.yaml` but NOT in `.api-fixtures.yaml` is shadow —
+  `prepare-fixtures` warns `not in manifest, ignored`.
+- "Generate should sync `.env.yaml`" is a rejected design (decision-7,
+  m-17).
+
+### Manual fixture-bootstrap (when `prepare-fixtures --seed` can't help)
+
+`prepare-fixtures --seed` requires a discoverable list endpoint or a
+postable create. Path-id ids that live only in a vendor dashboard
+(Stripe `cus_*`, GitHub PR numbers, Sentry issue ids) need a manual
+hand-off:
+
+| Input you have | Command |
+|---|---|
+| Concrete id values | `zond fixtures add <var>=<id> [--validate] --apply` |
+| Curl from devtools / dashboard | `pbpaste \| zond fixtures import --from-curl --apply` (URL is matched against spec paths to extract `{var}` bindings) |
+
+`--validate` GETs the spec's read-by-id endpoint and classifies the
+fixture as `live` / `stale` / `unknown` so dead ids don't silently
+break later runs (ARV-32). Both commands write to `apis/<name>/.env.yaml`
+with a `.env.yaml.bak` backup, mirroring `prepare-fixtures --apply`.
+
+### When to read which file
+
+| To know… | Read |
+|---|---|
+| What endpoints exist | `.api-catalog.yaml` |
+| How resources chain (CRUD, FK, ETag) | `.api-resources.yaml` |
+| What vars are needed and why | `.api-fixtures.yaml` |
+| What var values are set | `.env.yaml` |
+| Annotation overlay (seed_body, lifecycle, pagination, readback_diff) | `.api-resources.local.yaml` |
+| Full request/response schema (only when needed) | `spec.json` |
+
+## --json envelope (uniform across commands)
+
+```jsonc
+{
+  "ok": true|false,
+  "command": "<name>",
+  "data": { /* command-specific */ },
+  "warnings": ["..."],
+  "errors": [{ "code": "ZondErrorCode", "message": "...", "details": {} }],
+  "exit_code": 0|1|2
+}
+```
+
+Route on `errors[].code`, not message. Stdout discipline: `--json`
+emits only the envelope on stdout; progress/hints to stderr.
+
+`--json` ≠ `--report json`. `--json` wraps the **command result**;
+`--report json` wraps the **test-run artefact**. `zond run` doesn't
+accept `--json` — use `--report json`.
+
+## Entry points — pick by intent
+
+| User asked… | Start at |
+|---|---|
+| "audit this API", "test the whole API", "raise coverage" | Phase 0 → `zond audit --api <name>` (one-shot) OR walk Phase 0–8 |
+| "find bugs", "test for 5xx", "probe sweep" | Phase 0 → Phase 7 (Probes) |
+| "security only / SSRF / CRLF" | Phase 7.2 directly with `--dry-run` first |
+| "deep depth-checks", "SARIF", "stateful invariants" | Hand off → `zond-checks` |
+| "what broke in last run", "diagnose run X" | Hand off → `zond-triage` |
+| "write a test for X flow", "smoke this checkout" | Phase S (Scenarios) |
+| "what vars does this API need" | `zond doctor --api <name> --json` |
+| "share results", "case study" | Phase 9 (Share) |
+| "workspace looks messy" | `zond clean --api <name>` (dry-run → `--force`) |
+
+## Phase 0 — Orient
+
+```bash
+zond doctor --api <name> --json                 # gaps + freshness
+```
+
+Then read the three artifacts (NOT the raw spec):
+
+```bash
+cat apis/<name>/.api-catalog.yaml | head -80
+cat apis/<name>/.api-resources.yaml
+cat apis/<name>/.api-fixtures.yaml
+```
+
+If doctor reports stale → `zond refresh-api <name>`.
+
+## Phase 1 — Fixture pack
+
+`zond prepare-fixtures` walks `.api-resources.yaml`, hits each owner
+list endpoint, fills `.env.yaml`. Always `--apply`; add `--cascade --seed`
+for empty workspaces.
+
+```bash
+zond prepare-fixtures --api <name>                          # dry-run preview
+zond prepare-fixtures --api <name> --apply                  # single-pass
+zond prepare-fixtures --api <name> --apply --cascade --seed # cascade + POST-create when list is empty
+zond prepare-fixtures --api <name> --refresh                # = --verify --apply: drop stale ids, re-resolve
+```
+
+`--seed` POSTs to create endpoints when a list returns `[]`, using a
+schema-derived body. Bracket-notation nested params (Stripe's
+`card[number]`, `items[0][price]`) are a known weak spot (ARV-196) —
+some APIs will 400 here; **don't ask the user to fill missing ids
+manually first**, jump to Phase 2 (annotate seed_body) instead.
+
+If `--seed` converges but vars stay UNSET, the reason is outside the
+API path (email verify / paid plan / SCIM / TOS limits). Document the
+gap; don't loop further.
+
+Editing `.env.yaml` by hand is the sanctioned fallback when the CLI
+cannot harvest a value (write-only ingest endpoints, SDK-only ids,
+slugs that live in user's project config). Touch values only — never
+add keys not in `.api-fixtures.yaml`.
+
+## Phase 2 — Annotate (NEW, m-20 / ARV-187)
+
+**Critical**: zond itself does NOT call any LLM. The flow is
+**dump → agent fills YAML → apply**. The agent (you) generates the
+overlay; zond validates and writes it into `.api-resources.local.yaml`.
+
+`zond api annotate` has 6 dump-subcommands (one per aspect). Pick what
+your downstream check needs:
+
+| Aspect | Dump produces | Feeds into |
+|---|---|---|
+| `--seed-bodies` | request-body schema per resource | `prepare-fixtures --seed`, all stateful checks |
+| `--readback` | create+read pair (write-shape vs read-shape) | `cross_call_references` ignore_fields, write_to_read_map |
+| `--idempotency` | header candidates | `idempotency_replay` (header, scope, body_hash_fields) |
+| `--pagination` | list-endpoint cursor/page detection | `pagination_invariants` (type, cursor_param) |
+| `--lifecycle` | action-endpoint candidates per resource | `lifecycle_transitions` (states, transitions) |
+| `--resources` | orphan endpoints not in resource graph | `.api-resources.local.yaml` extensions |
+
+**Workflow** (for ANY aspect):
+
+```bash
+# 1. Dump — emits JSON slices on stdout. Restrict scope with --only.
+zond api annotate dump --api <name> --seed-bodies --only r1,r2 > /tmp/dump.json
+
+# 2. Agent reads the dump and writes a YAML response file (see format below).
+
+# 3. Apply — dry-run first (diff), then --yes to write.
+zond api annotate apply --api <name> --seed-bodies --input /tmp/out.yaml          # dry-run + diff
+zond api annotate apply --api <name> --seed-bodies --input /tmp/out.yaml --yes    # write
+```
+
+YAML response format — a top-level list of entries, each one resource:
+
+```yaml
+- resource: <name>
+  seed_body:                              # (--seed-bodies)
+    content_type: application/x-www-form-urlencoded
+    body:
+      amount: 1000
+      currency: usd
+  rationale: 'why this shape'             # optional, helps future review
+  confidence: high                        # high|medium|low — optional
+```
+
+Same shape for `readback_diff`, `idempotency`, `pagination`,
+`lifecycle` blocks (see `zond-checks` for the per-aspect schemas).
+
+**When to annotate**: run dump+apply BEFORE Phase 6 (stateful checks)
+for any production API. Without annotation, stateful checks fall back
+to defaults and miss API-specific quirks (custom pagination params,
+non-standard lifecycle field names, write-only fields in create body).
+
+**For Stripe-style form-encoded APIs**: `--seed-bodies` is the single
+biggest win — it fixes `--seed` 400s for the bulk of resources.
+
+## Phase 3 — Generate tests
+
+```bash
+zond generate apis/<name>/spec.json --output apis/<name>/tests [--tag <spec-tag>] [--uncovered-only]
+zond check tests apis/<name>/tests
+```
+
+`generate` fills bodies with `{{$randomString}}`. Format-strict APIs
+reject many — that's a **test-fix**, not a backend bug. Pair with
+Phase 1 fixtures + Phase 2 annotation.
+
+If a CRUD chain you expected is missing, run
+`zond generate <spec> --explain` — diagnostic table shows every POST
+endpoint with verdict (no GET-by-id, non-`{id}` item param,
+trailing-slash mismatch, …).
+
+## Phase 4 — Spec-lint (hygiene, separate workflow)
+
+```bash
+zond lint --api <name>                           # 0 network requests
+zond lint --api <name> --json | jq '.data.stats'
+# Equivalent: `zond check spec --api <name>`
+```
+
+ARV-255 (m-21 pivot): **spec-lint is hygiene, not security or
+contract.** It runs separately from `zond audit` / `zond probe` /
+`zond checks run` — those produce the security/reliability/contract
+report, lint stays out of that pile.
+
+Severity capped at **LOW / INFO** by design:
+- LOW: real spec violations (format mismatch in example, missing
+  path-param format, response without schema).
+- INFO: style and documentation gaps (additionalProperties missing,
+  naming, missing examples).
+
+No HIGH/MEDIUM ever — static analysis has no runtime evidence, so the
+severity matrix forbids escalation. `--strict` opts back into a
+non-zero exit when any LOW lands.
+
+## Phase 5 — Run (sanity → smoke → CRUD)
+
+Wrap multi-run sweeps in a session so `/runs` shows one row:
+
+```bash
+zond session start --label "smoke + probes"
+zond run apis/<name>/tests --tag sanity --report json                              # 5.1 sanity
+zond run apis/<name>/tests --safe --report json                                    # 5.2 smoke (GET-only)
+zond run apis/<name>/tests --tag crud,setup --validate-schema --report json        # 5.3 full CRUD
+zond run apis/<name>/tests --tag positive --include 'path:^/emails'                # 5.4 narrow
+zond session end
+```
+
+**Always pass `--validate-schema` for CRUD** — contract drift is
+invisible without it. `schema_violation` failures are real backend bugs;
+treat them like 5xx.
+
+Rate limit: `zond run` defaults to an adaptive limiter (no-op until
+`RateLimit-*` headers appear). Pass `--rate-limit <N>` for a hard cap;
+`--sequential` for old binaries.
+
+**Long runs**: `zond run` shows a periodic progress line on stderr when
+stdout/stderr is a TTY (`zond: [42s] 234/10927 steps (2%), 230 req, ~30
+req/s, ETA ~5m`) — overwrites itself in place. Suppressed by `--quiet`
+and on non-interactive output. For huge probe-suites (e.g. GitHub spec
+→ ~10k probes under `--rate-limit 30` = 6+ min), this signals "alive,
+not hung". `zond probe static` itself prints a scale-warning block with
+ETA-at-rate-limit estimates and a `--max-per-endpoint K` sampling hint
+when `totalProbes ≥ 2000`.
+
+**Hard cap on requests**: pass `--max-requests N` to cap outgoing HTTP
+calls across the whole run. Remaining steps short-circuit to `skip` with
+`error: "max-requests-cap-reached"`. Each `retry_until` attempt counts as
+one request. Useful for sampling huge probe runs (`--max-requests 500`)
+and for CI time-boxing.
+
+`--all`: fold every `apis/<name>/tests/` dir into one `runs.id` per
+invocation (CI shape). CI context (commit_sha, branch, trigger=ci)
+auto-stamped from env vars.
+
+### Spec-drift learning tail (`--learn`)
+
+After the initial CRUD run, **always** close with `--learn` /
+`--learn-apply`. R09 measured a 28% → 58% pass-coverage jump from this
+phase alone.
+
+```bash
+zond run apis/<name>/tests --learn                            # detect (read-only)
+zond run apis/<name>/tests --learn-apply --learn-target test  # rewrite expect.status
+zond run apis/<name>/tests --learn-apply --learn-target drifts # allowlist in tolerated-drifts.yaml
+```
+
+**Caveat — `--learn-apply test` weakens assertions, not the code.**
+Diff `apis/<name>/tests/*.yaml` + `tolerated-drifts.yaml` after every
+apply; treat unexpected widenings as a review-blocker.
+
+## Phase 6 — Stateful checks (m-20)
+
+After Phase 2 annotation is applied, run the cross-call invariants.
+See `zond-checks` for per-check semantics.
+
+```bash
+zond checks run --api <name> --check stateful --report ndjson
+```
+
+5 m-20 stateful checks:
+- `cross_call_references` — POST→GET drift (uses readback_diff overlay)
+- `idempotency_replay` — bit-identical replay on `Idempotency-Key`
+- `pagination_invariants` — `?limit=N` + `?after=last_id` non-overlap
+- `lifecycle_transitions` — declared state-machine validity
+- `webhooks` (recipe-based, see `docs/recipes/webhook-receiver.md`)
+
+**Iron rule**: don't run `--check stateful` without prior `api annotate`
+review. Defaults catch the obvious; quirks need declared config.
+
+## Phase 7 — Proactive bug hunting (probes)
+
+```bash
+zond probe static --api <name>                # validation + methods (defaults)
+zond probe mass-assignment --api <name> --emit-tests apis/<name>/probes/mass-assignment
+zond probe security ssrf,crlf,open-redirect,prompt-injection --api <name> \
+  --emit-tests apis/<name>/probes/security
+zond run apis/<name>/probes --report json
+```
+
+Flag: 5xx on null/empty/wrong-type body → missing validation. 2xx on
+undeclared method → contract drift. `is_admin: true` echoed in response
+→ HIGH from mass-assignment.
+
+**Body-FK auto-discovery** — `mass-assignment` resolves required
+`*_id`/`*_slug`/`*_uuid`/`*_key` fields by hitting sibling list endpoints.
+If digest still says "unresolved body FKs:" — add to `.env.yaml` manually.
+
+**Auto-path-FK** — same logic for path params (`{domain_id}`/`{webhook_id}`).
+Cached per run. Pass `--no-discover` to opt out.
+
+### 7.1 — Manual mass-assignment catch-up
+
+`mass-assignment` digest splits findings: HIGH / MED / LOW /
+INCONCLUSIVE (no valid body — fixture problem) / INCONCLUSIVE-5XX
+(baseline crashed — already in validation-probe). Sweep INCONCLUSIVE
+with `--emit-template`:
+
+```bash
+zond probe mass-assignment --api <name> --emit-template "POST:/<resource>" \
+  --output apis/<name>/probes/mass-assignment/<resource>.yaml
+```
+
+Emits `create → verify → cleanup` chain pre-filled with classic vectors
+(`is_admin`, `role`, `owner_id`). If a privileged field survives the
+round-trip GET → **HIGH**, file via `report bundle --include case-study`.
+
+### 7.2 — Security probes
+
+```bash
+zond probe security ssrf,crlf --api <name> --dry-run         # first run: which (endpoint, field)
+zond probe security ssrf,crlf,open-redirect,prompt-injection --api <name>
+```
+
+Field autodetection: SSRF (`*_url`/`webhook`/`callback`/`format: uri`),
+CRLF (`subject`/`*_prefix`/`name`), open-redirect (`redirect`/`next`).
+
+Baseline-OK request first; if baseline ≠ 2xx → `INCONCLUSIVE-BASELINE`,
+attacks skipped (kills 5×404 noise on scope-locked endpoints).
+
+Verdict: HIGH (5xx OR payload echoed in 2xx — stored injection),
+LOW (2xx, no echo — verify side-effects manually), OK (4xx).
+
+**Cleanup is state-aware**: PUT/PATCH does `GET` → snapshot → attack →
+restore. POST falls back to `DELETE` with eventual-consistency retry.
+Restore failures → `## ⚠️ Cleanup failures` at top of digest.
+
+CI exit: non-zero on HIGH > 0 OR `cleanup.error > 0`.
+
+### 7.3 — Post-probe hygiene
+
+```bash
+zond prepare-fixtures --api <name> --refresh    # drop stale FK ids
+zond cleanup --orphans                           # retry DELETE for ~/.zond/orphans/
+```
+
+Skip only with `probe security --isolated` (isolated mode never attacks
+seeded-fixture endpoints).
+
+## Phase 8 — Coverage + spec drift
+
+```bash
+zond coverage --api <name> --union session                  # default for an audit window
+zond coverage --api <name> --union since:1h                 # last hour
+zond coverage --api <name> --union tag:smoke                # tag-filtered
+zond coverage --api <name> --fail-on-coverage 50            # CI gate (use hit-coverage)
+```
+
+**Two metrics**: `pass-coverage` (covered2xx — strict, CI gate) vs
+`hit-coverage` (any stored result, breadth proxy). Three-bucket JSON:
+`covered2xx`, `coveredButNon2xx` (hit but failed — usually fixture gap,
+not API bug), `unhit`.
+
+**Quality signals to gate CI on** (not raw pass-coverage):
+
+| Signal | Command |
+|---|---|
+| Contract drift | `checks run --phase coverage` HIGH count == 0 |
+| Stateful invariants | `checks run --check stateful` HIGH count == 0 |
+| Auth / Authz / injection | `probe security` HIGH count == 0 |
+| Mass-assignment | `probe mass-assignment` HIGH count == 0 |
+| Response conformance | `run --validate-schema` `schema_violation` == 0 |
+| Drift allowlist review | `git diff apis/<name>/tolerated-drifts.yaml` |
+
+## Phase 9 — Share findings
+
+```bash
+zond report export <run-id>                                # default: triage/<api>/run-<id>/
+zond report bundle 135..142 -o triage/sweep/               # all artefacts (default): case-study + html + diagnose + index.md
+zond report bundle <run-id> --include case-study,diagnose  # subset only (drop html)
+zond report bundle --session <id> -o triage/session/       # group by session
+```
+
+Bodies > 8 KB truncated by default; `--no-body-cap` to keep full.
+Existing files at `--output` auto-rotate to `<stem>-vN.<ext>`;
+`--overwrite` to silence. **Always pass `--redact-identity` for
+outbound sharing** (secret-redaction is on by default; identity slugs
+need the extra flag).
+
+Offer this proactively after a run surfaces `definitely_bug`
+(5xx / schema violation / mass-assignment 2xx). Skip for `env_issue` /
+`quirk`.
+
+## One-shot full audit
+
+`zond audit --api <name>` runs the whole pipeline in one shot:
+prepare-fixtures → generate → probe static → session-wrapped run on
+tests+probes → coverage → `audit-report.html`. Each stage prints
+`==> Stage N/M: <name>`; stage failure doesn't stop the rest; final
+exit 1 if any stage failed.
+
+```bash
+zond audit --api <name> --dry-run                       # plan
+zond audit --api <name>                                  # minimal pipeline
+zond audit --api <name> --seed                           # add prepare-fixtures --cascade --seed
+zond audit --api <name> --with-mass-assignment --with-security
+zond audit --api <name> --out reports/audit-<name>.html
+```
+
+`generate` skipped via mtime when `tests/` is fresher than `spec.json`
+(pass `--force` to override).
+
+**Gotchas**:
+- Wraps its own session — closes any prior `session start` silently.
+- Can exit 0 on failed stages (parse stdout `Warning: N failed`).
+- `audit-report.html` path not echoed by default — pass `--out`.
+
+When NOT to use audit: narrow asks ("fix run X", "why this endpoint
+500s") — walk phases.
+
+## Phase S — Single-flow scenarios
+
+When the user wants to verify one specific flow (not breadth):
+
+```bash
+zond doctor --api <name>                                 # confirm fixtures
+# write apis/<name>/scenarios/<flow-slug>.yaml directly (no scaffold cmd)
+zond session start --label "<short reason>"
+zond run apis/<name>/scenarios/<flow>.yaml --report json
+zond session end
+```
+
+YAML grammar (zond runner format — NOT Postman / OpenAPI shape):
+
+```yaml
+name: cancel-pending-order
+tags: [scenario, orders]
+base_url: "{{base_url}}"
+headers: { Authorization: "Bearer {{auth_token}}" }
+tests:
+  - name: create order
+    POST: /workspaces/{{ws_id}}/orders
+    json: { amount: 100, currency: USD }
+    expect:
+      status: 201
+      body:
+        id: { capture: order_id }
+        status: { equals: pending }
+  - name: cancel
+    POST: /orders/{{order_id}}/cancel
+    expect: { status: 200 }
+  - name: verify cancelled
+    GET: /orders/{{order_id}}
+    expect:
+      status: 200
+      body: { status: { equals: cancelled } }
+  - name: cleanup
+    DELETE: /orders/{{order_id}}
+    always: true                                          # runs even on prior failure
+    expect: { status: [200, 204, 404] }
+```
+
+Grammar:
+- HTTP verb is a top-level key on the step (`GET:`, `POST:`, …).
+- Body: `json: {...}` / `form: {...}` / `multipart:` / `text:`.
+- Captures: `expect.body.<field>: { capture: <var> }`.
+- Assertions: `equals`, `type`, `exists`, `matches`, `gt`/`lt`,
+  `length*`, `each`, `contains_item`, `set_equals`, `oneOf`.
+- `expect.status`: number or array. `oneOf` / `anyOf` string forms NOT
+  supported — pass an array directly.
+- `always: true` — runs on prior failure (cleanup).
+- `skip_if: "{{var}} =="` — skip when fixture var unset.
+- Generators: `{{$randomEmail}}`, `{{$uuid}}`, `{{$randomString}}`,
+  `{{$randomInt}}`, `{{$randomIsoDate}}`. Full list:
+  `zond reference random-helpers`.
+
+Hand-crafted scenarios are for **bug repro / post-deploy smoke /
+verifying a fix** — small focused work. For breadth, use Phase 3
+(generate) and the full audit chain.
+
+## Diagnose failures
+
+```bash
+zond db runs --limit 5 --json
+zond db diagnose <run-id> --json              # grouped by root_cause
+zond db run <id> --status 500 --json
+zond db compare <idA> <idB> --json            # regression diff
+```
+
+`recommended_action` enum (closed):
+- `report_backend_bug` — STOP, surface to user
+- `fix_test_logic` — edit the YAML
+- `fix_auth_config` / `fix_network_config` / `fix_env` — config issues
+- `fix_spec` — edit OpenAPI (from `check spec`)
+- `fix_fixture` — fill `.env.yaml` (from `prepare-fixtures` miss-* or
+  inconclusive mass-assignment baseline)
+- `update_spec` — status-drift from `--learn`
+
+`cascade` failures collapse under root cause — fix upstream, not
+individually.
+
+### Fixing 4xx from stub generators (`fix_test_logic`)
+
+When body rejected on format (400/422 + "expected ..."):
+
+1. Read failure: `zond db run <id> --status 422 --json`.
+2. **Fixture pack first** — if it's a FK id / verified resource /
+   constrained enum, add to `.env.yaml` (Phase 1).
+3. **Typed generator** — swap `{{$randomString}}` for matching format
+   helper.
+4. **Hardcoded literal** — when typed generators fail (regex too strict).
+5. **Runtime captures** — for resources the test creates (capture from
+   prior `create_*` step or `setup: true` suite). For pre-existing FKs,
+   prefer step 2.
+
+For deep triage of a specific failing run → hand off to `zond-triage`.
+
+## Auth / environments
+
+- `apis/<name>/.env.yaml` is both auth and fixture pack — any key
+  interpolatable as `{{key}}`. Auto-gitignored.
+- Login-flow tokens: `setup: true` suite captures vars that propagate
+  to later suites in the same run.
+- `zond run --env <name>` loads `.env.<name>.yaml`. Discovery walks up
+  to workspace root; deeper files override shallower.
+
+## File lifecycle
+
+Everything zond writes is tracked in `.zond/manifest.json` with
+sha256-at-write. Files whose hash no longer matches are **skipped**
+on clean (user edits stay safe). Re-running a generator overwrites
+the entry — manual edits to generator-owned files are lost on
+regenerate; promote them to a separate suite first.
+
+```bash
+zond clean --api <name>                     # dry-run: lists what would be removed
+zond clean --api <name> --force             # delete (preserves probes/)
+zond clean --api <name> --probes --force    # also probe suites
+zond clean --all --force                    # nuclear
+```
+
+Triage outputs default to
+`triage/<api>/<run-id>/<command>-<ts>.<ext>`. Don't pass `--output`
+unless the user has a specific destination.
+
+## When to hand off
+
+- "deep depth-checks", "SARIF", "boundary coverage", "stateful
+  invariants details", "annotate aspect XYZ" → `zond-checks`
+- "what failed in last run", "why is it red", "case study from run X"
+  → `zond-triage`
+
+If the user is mid-workflow in one of those, don't restart from here.

package/src/cli/commands/init/templates/zond-config.yml

@@ -0,0 +1,14 @@
+# zond workspace config
+#
+# The presence of this file marks the workspace root for `zond` walk-up
+# resolution (zond.db, apis/<name>/, .zond/current-api are anchored here).
+
+version: 1
+
+# Workspace-level defaults. Per-command flags always win; per-API
+# override lives in apis/<name>/.env.yaml as `rateLimit:` / `timeoutMs:`.
+# Resolution: CLI flag > .env.yaml meta > defaults below > built-in fallback.
+#
+# defaults:
+#   timeout_ms: 30000   # cleanup / prepare-fixtures / probe / request
+#   rate_limit: 5       # `zond run` (number rps, or "auto" for adaptive)