@kirrosh/zond 0.22.0 → 0.26.0

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

@@ -1,184 +1,861 @@
 ---
 name: zond
 description: |
-  End-to-end API testing with zond — generate tests from an OpenAPI spec, run them,
-  diagnose failures, and hunt for typical backend bugs via probe suites. Use when
-  asked to: test an API, cover endpoints, raise coverage, find bugs, diagnose
-  failed runs, fix failing tests, debug 4xx/5xx, run probes, sync tests after a
-  spec change, set up API test infrastructure. Activates on: openapi.json,
-  openapi.yaml, swagger.json, .api-catalog.yaml, "test this API", "cover this
-  spec", "tests are failing", "diagnose run", "find bugs", "probe", "5xx",
-  "negative input".
-allowed-tools: [Read, Write, Bash(zond *), Bash(bunx zond *)]
+  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 — API Coverage, Diagnosis & Bug Hunting
+# 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).
+  `--body '{…}'` always sends `application/json`. For form-encoded APIs
+  (Stripe v1, classic webforms) pass `--form` — zond URL-encodes the
+  JSON body. Auto-detect from spec: if `requestBody.content` in
+  `.api-catalog.yaml` declares only `application/x-www-form-urlencoded`,
+  use `--form`; mixed content-types → pick by `Content-Type` header you
+  want to test.
+- **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. To WRITE / rotate a secret
+  use `zond secrets set <key> <value> --api <name>` (writes a `.bak`, never
+  echoes the value, auto-strips a pasted `Bearer ` prefix — pass `--literal`
+  to keep it verbatim).
+- **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.
+  `.api-schema.local.yaml` is the response-schema overlay (ARV-176) —
+  written by `refresh-api --merge-schema`, also survives refresh; edit by
+  re-merging a `patch.schema.json`, not by hand. `.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> --json`
+  (401/403 dominate `by_recommended_action`); 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.
+- **`prepare-fixtures` is single-pass, never POST-creates, and never
+  harvests values** (ARV-362) — it verifies existing fixtures and reports
+  unfilled vars as gaps. Which record/field fills a slot is your call:
+  fill fixtures by hand (`fixtures add` / editing `.env.yaml`).
+
+## Workspace artifact model
+
+After `zond add api <name> --spec <path|url>`, `apis/<name>/` contains:
 
-CLI-only skill. zond is invoked directly via shell. Run `zond --version` first;
-if missing, install via `curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh`.
+```
+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 (you fill every value)
+
+ARV-362: `prepare-fixtures` **reports** FK gaps — it never harvests a
+value. Every fixture is filled by hand: read the gap (empty list → create
+a record first; non-empty → pick a value; 404/403 → auth/drift), then
+supply it. Vendor-dashboard ids (Stripe `cus_*`, GitHub PR numbers,
+Sentry issue ids) have no list endpoint at all — same 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.
+
+### 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.
 
-For multi-step user journeys / fixture creation through the API, hand off to
-`zond-scenarios` instead — that is a different concern.
+`--json` ≠ `--report json`. `--json` wraps the **command result**;
+`--report json` wraps the **test-run artefact**. `zond run` doesn't
+accept `--json` — use `--report json`.
 
-## Critical rules (always-on)
+## Entry points — pick by intent
 
-- **NEVER** open OpenAPI/Swagger files with Read/cat/grep — use `zond describe`,
-  `zond catalog`, or the generated `.api-catalog.yaml`.
-- **NEVER** use curl/wget — use `zond request <method> <url>`.
-- **NEVER** write test YAML from scratch — start with `zond generate`, then edit failures.
-- **NEVER** hardcode tokens — `apis/<name>/.env.yaml` (auto-gitignored), reference as `{{auth_token}}`.
-- **`--safe` enforces GET-only** — required for first-pass smoke against unknown envs.
-- **`recommended_action: report_backend_bug` (5xx) → STOP**. Do NOT modify
-  `expect: status` to make the test pass. Surface the bug to the user with the
-  request/response excerpt.
-- **5xx in any run is a bug candidate** — never edit assertions to mask it.
-- For multi-suite tag filters always include the setup tag: `--tag crud,setup`.
-- Captures are file-scoped — pass auth across suites via a `setup: true` suite.
-- Re-run after each fix with `--safe --json`; do not batch many edits without verifying.
+| User asked… | Start at |
+|---|---|
+| "smoke this API", "quick first pass", "demo / CI gate" | `zond audit --api <name>` (safe-mode breadth pass — no live mutations) |
+| "audit this API", "test the whole API", "raise coverage", "deep pass" | walk Phase 0–9 — audit covers smoke; depth (stateful, security, learn-apply) needs phase-level decisions |
+| "full live audit against sandbox", "include mass-assignment/security probes" | `zond audit --api <name> --live --with-mass-assignment --with-security` (REQUIRES throwaway/sandbox account) |
+| "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`) |
 
-## Entry points (skip phases when the request is narrow)
+## 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
+```
 
-| User asked... | Start at phase | Skip |
+If doctor reports stale → `zond refresh-api <name>`.
+
+## Phase 1 — Fixture pack
+
+`zond prepare-fixtures` is **single-pass and deterministic**: it walks
+`.api-resources.yaml`, hits each owner list/read endpoint, and **reports**
+which FK vars are unfilled (empty list → create one first; non-empty →
+pick a value; 404/403 → auth/drift). It does **not** POST-create resources
+and (ARV-362) **never harvests a value** — which record/field fills a slot
+is your judgment. Fill every gap by hand (`fixtures add` / `.env.yaml`).
+
+```bash
+zond prepare-fixtures --api <name>            # report gaps (never writes values)
+zond prepare-fixtures --api <name> --apply    # only unsets stale ids under --refresh; never harvests
+zond prepare-fixtures --api <name> --refresh  # = --verify --apply: drop (unset) stale 404 ids → you refill
+```
+
+It also scans the generated suites and reports two named gap buckets
+(warnings in text, `summary.fixtureGaps` in `--json`) — report only, no
+values invented, no auto-seed (ARV-349/350):
+- **`unseededRoots`** — required manifest vars that are empty, referenced by
+  a suite, and seeded by no step (e.g. `{{account}}` created in `crud-accounts`
+  but referenced uncaptured in `persons-crud`). These are chain-heads: one id
+  un-skips a whole dependent CRUD suite. Fix these first.
+- **`undefinedVars`** — suite `{{vars}}` no manifest entry, capture, or param
+  produces (`{{bank_code}}`, `{{tax_id}}`). Supply by hand.
+
+To fill `unseededRoots` autonomously — author create-bodies, POST them, and
+capture the returned ids — hand off to **`zond-seed`** (agent reasons, zond
+executes via `request … --capture`). It seeds only what the API self-serves
+and reports external-input gaps honestly.
+
+When a var stays UNSET after `--apply`, read the per-target reason in the
+output, then fill the gap directly:
+
+| 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` |
+| Nothing yet (empty list) | Create the resource in the product UI / via API, then harvest its id with `fixtures add` |
+
+Common reasons a var stays UNSET (all fixed outside prepare-fixtures):
+- empty list on the target account — no record exists to harvest;
+- the id lives only in a vendor dashboard (Stripe `cus_*`, GitHub PR
+  numbers, Sentry issue ids) with no discoverable list endpoint;
+- the value is gated outside the API path (email verify / paid plan /
+  SCIM / TOS limits). Document the gap; don't loop.
+
+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`.
+
+### Dynamic value functions in `.env.yaml` (ARV-190, m-21)
+
+Stale hardcoded UUIDs / dates / idempotency keys pin existing rows or
+expire mid-run. Use `#(funcName)` / `#(funcName(args))` references —
+evaluated at load time, stable within one run:
+
+| Token | Resolves to | Use for |
+|---|---|---|
+| `#(uuid)` | fresh UUID v4 (same value across all references in this run) | Idempotency-Key, request id |
+| `#(uuidStable(<seed>))` | deterministic UUID from seed (sha-256 shaped as v4) | reproducible tests |
+| `#(today)` | `YYYY-MM-DD` (UTC) | expiry-from dates |
+| `#(todayPlus(N))` | today + N days (N may be negative) | expires_at, valid_until |
+| `#(now)` | ISO 8601 timestamp | created_at hints |
+| `#(unix)` | seconds since epoch | epoch timestamps |
+| `#(alphanumeric(N))` | N random `[a-z0-9]` chars (default 8) | one-shot tokens |
+| `#(env:VAR)` | `process.env.VAR` (alias for `${VAR}`) | secrets passed through |
+
+```yaml
+# apis/foo/.env.yaml
+idempotency_key: "#(uuid)"          # same uuid across every step in this run
+trial_expires:   "#(todayPlus(30))"  # 30 days from now
+request_id:      "req-#(uuid)"       # embedded; shares uuid with above
+```
+
+Resolution order: `${ENV}` → `#(...)` → `@secret:` → `@identity:`. Dynamic
+functions run BEFORE secret/identity refs so a secret value that happens to
+contain `#(...)` stays opaque (no double-expansion). Per-run cache means
+`#(uuid)` referenced twice in the same `.env.yaml` returns the same value
+— critical for idempotency-replay flows.
+
+## 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 |
 |---|---|---|
-| "cover this API", "raise coverage", "test this spec" | 1 (Discover) | — |
-| "find bugs", "probe this API", "test for 5xx" | 1 then 5 (Probes) | — |
-| "tests are failing", "diagnose run X", "fix failures" | 4 (Diagnose) | 1–3 |
-| "the run after my fix" | 3.x (Run) → 4 (Diagnose) | 1–2 |
+| `--seed-bodies` | request-body schema per resource | all stateful checks (create-body overlay) |
+| `--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 — the create-body overlay it produces lets stateful checks
+POST valid resources instead of 400-ing on schema-derived random bodies.
+
+### Agent-in-the-loop annotate (dump → write → apply, ARV-187 / 277 / 278-282)
+
+zond does NOT infer annotations. YOU (the agent) read the spec slice and
+write the overlay; zond only dumps raw material and validates/merges what
+you produce.
+
+```bash
+# 1. Dump the raw material for a resource — spec slice + expected YAML
+#    shape + (for seed-bodies) the last N seed-POST attempts so you see
+#    the error progression, not just the current 400 (ARV-277/278).
+zond api annotate dump --api <name> --seed-bodies --only <res> \
+  --with-last-attempt --history 5
+
+# 2. YOU write the overlay: read the dumped slice + attempt history,
+#    reason about the required create body / pagination / lifecycle /
+#    idempotency, and produce one YAML doc per resource. Edit
+#    .api-resources.local.yaml directly OR emit a file for apply.
+
+# 3. Apply — zond validates your YAML (zod), renders a diff, and (with
+#    --yes) merges. With --gap-fill-only (ARV-281) your response can ONLY
+#    add missing fields — already-set blocks are protected from overwrite.
+zond api annotate apply --api <name> --seed-bodies --input agent-out.yaml --gap-fill-only --yes
+
+# 4. Refresh fixtures — drop (unset) stale (404) ids so they resurface as
+#    gaps; refill them by hand / `fixtures add` (discover never harvests).
+zond prepare-fixtures --api <name> --refresh
+```
+
+## 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 typed generators (`{{$randomString}}` etc.).
+Format-strict APIs reject many — that's a **test-fix**, not a backend bug.
+Pair with Phase 1 fixtures + Phase 2 annotation.
+
+Required FK / reference body fields (`*_id`, unresolved `*Code` like
+`sequenceTypeCode`) are wired to `{{fixture}}` refs (ARV-45) — canonicalised
+(`sequence_type_code`) and listed in `.api-fixtures.yaml` as `source: body-fk`.
+Fill their real values once in `.env.yaml`; no more hand-editing generated
+tests. Blank fixture → the var is unbound and dependent tests skip.
+
+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 1 — Discover
+## Phase 5 — Run (sanity → smoke → CRUD)
+
+Wrap multi-run sweeps in a session so `/runs` shows one row:
 
 ```bash
-# Workspace + register API (idempotent)
-zond init --with-spec <spec> --name <name> [--base-url <url>]
-zond use <name>
+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
+```
 
-# Endpoint discovery (do NOT read the raw spec)
-zond catalog <spec> --output apis/<name>/tests   # writes .api-catalog.yaml
-zond describe <spec> --compact                   # quick overview
-zond guide <spec> --tests-dir apis/<name>/tests  # uncovered + suggestions
+**Always pass `--validate-schema` for CRUD** — contract drift is
+invisible without it. `schema_violation` failures are real backend bugs;
+treat them like 5xx.
+
+**After any `zond run` with failures → delegate to `zond-triage`.** Do
+NOT parse `runs/run-NN.json` with `jq` by hand. The triage skill reads
+`zond db diagnose --json` (which already buckets by `recommended_action`
+in `data.by_recommended_action`, ARV-228) and routes by closed enum —
+re-implementing that logic with prose heuristics drifts. Only fall back
+to manual CLI queries when the failure is outside the example slice.
+
+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
 ```
 
-## Phase 2 — Generate
+**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 generate <spec> --output apis/<name>/tests              # all
-zond generate <spec> --output apis/<name>/tests --tag <tag>  # by spec tag
-zond generate <spec> --output apis/<name>/tests --uncovered-only
-zond validate apis/<name>/tests                              # YAML lint
+zond checks run --api <name> --check stateful --report ndjson --live   # CRUD create-chains need --live
 ```
 
-`generate` fills bodies with `{{$randomString}}`. Format-strict APIs will reject
-many of these — that is a **test-fix**, not a backend bug. See phase 4 for the fix flow.
+**Safe by default (ARV-299)**: without `--live`, `checks run` skips the
+stateful CRUD create-chains (`ensure_resource_availability`,
+`use_after_free`) — they'd POST real resources. Read-only stateful checks
+(pagination, observation-mode lifecycle, cross-call GET diff) still run.
+Add `--live` **only against a throwaway/sandbox account** to exercise the
+create-chains.
+
+`--check stateful` expands to the state-machine set (ARV-325):
+- `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
+- `use_after_free`, `ensure_resource_availability` — CRUD lifecycle
+- `cursor_boundary_fuzzing` — list-cursor edge values
+- `webhooks` (recipe-based, see `docs/recipes/webhook-receiver.md`)
+
+`ignored_auth` / `open_cors_on_sensitive` are **not** part of the alias —
+they're auth/security checks that roughly triple run time on wide APIs.
+Run them by explicit id: `--check ignored_auth,open_cors_on_sensitive`.
 
-## Phase 3 — Run (sanity → smoke → full)
+**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
-# 3.1 Sanity gate — must pass before broad runs
-zond run apis/<name>/tests --tag sanity --json
+zond probe static --api <name>                # validation + methods (defaults; generator, always safe)
+zond probe mass-assignment --api <name> --live --emit-tests apis/<name>/probes/mass-assignment
+zond probe security ssrf,crlf,open-redirect --api <name> --live \
+  --emit-tests apis/<name>/probes/security
+zond run apis/<name>/probes --report json
+```
+
+**Safe by default (ARV-299)**: `probe mass-assignment` / `probe security`
+without `--live` plan only (no live attack payloads) — same as `--dry-run`.
+Add `--live` **only against a throwaway/sandbox account** to send probes.
+`probe static` just generates suites, so it's always safe.
+
+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) — same as default --safe
+zond probe security ssrf,crlf,open-redirect --api <name> --live   # send, sandbox only
+```
+
+**Targeting** (two filters; an endpoint must pass BOTH to be planned):
+
+1. **Has a JSON request body** — GET-only routes are skipped with
+   `no-body`. The probes work by mutating a body field, so read-only
+   endpoints have nothing to attack.
+2. **Has ≥1 field name matching the requested class detectors** — if
+   no field matches, the endpoint is skipped with `no-matched-field`.
+
+Field autodetection: SSRF (`*_url`/`webhook`/`callback`/`format: uri`),
+CRLF (`subject`/`*_prefix`/`name`), open-redirect (`redirect`/`next`).
+
+If `--dry-run` reports `0 planned / 0 skipped / 0 total` with a narrow
+`--include`, the scope likely captured only GET routes — broaden the
+filter or drop `--include` to see the per-endpoint skip reasons. With
+no `--include`, the dry-run shows `no-body` / `no-matched-field` next
+to each skipped endpoint so the gap is obvious.
+
+Baseline-OK request first; if baseline ≠ 2xx → `INCONCLUSIVE-BASELINE`,
+attacks skipped (kills 5×404 noise on scope-locked endpoints).
 
-# 3.2 Smoke (GET-only)
-zond run apis/<name>/tests --safe --json
+Verdict: HIGH (5xx OR payload echoed in 2xx — stored injection),
+LOW (2xx, no echo — verify side-effects manually), OK (4xx).
 
-# 3.3 Full CRUD — only after setup-token capture works
-zond run apis/<name>/tests --tag crud,setup --json
+**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/
 ```
 
-## Phase 4 — Diagnose failures
+Skip only with `probe security --isolated` (isolated mode never attacks
+seeded-fixture endpoints).
+
+## Phase 8 — Coverage + spec drift
 
 ```bash
-zond db runs --limit 5 --json                # find failed runId
-zond db diagnose <run-id> --json             # full DiagnoseResult (grouped by root_cause)
-zond db run <id> --status 500 --json         # filter results within a run
-zond db run <id> --method POST --json
-zond db compare <idA> <idB> --json           # regression diff between runs
+zond coverage --api <name> --union session                  # default: dual-metric (test + audit)
+zond coverage --api <name> --union since:1h                 # last hour
+zond coverage --api <name> --union tag:smoke                # tag-filtered
+zond coverage --api <name> --scope audit --union session    # only "did zond touch the API"
+zond coverage --api <name> --scope test  --union session    # legacy single block
+zond coverage --api <name> --fail-on-coverage 50            # CI gate (gates pass-coverage)
 ```
 
-DiagnoseResult guide:
-- `agent_directive` — literal next step. Do exactly that.
-- `recommended_action`:
-  - `fix_test_logic` → edit the YAML (assertion, generator, capture).
-  - `report_backend_bug` → STOP, report to user.
-  - `update_expectation` → only if the user confirms the new contract is correct.
-- `root_cause` groups identical failures so one fix covers many cases.
+**Dual-metric output (ARV-265).** `zond coverage` prints two blocks side-by-side by default:
 
-### 4a. Fixing 4xx caused by stub generators
+- **test-coverage** — runs produced by `zond run` only (`run_kind` ∈ {regular, probe}). Has two sub-metrics:
+  - `pass-coverage`: endpoint had a passing 2xx (strict; CI gate via `--fail-on-coverage`)
+  - `hit-coverage`: endpoint received any response (loose; breadth proxy)
+  Three-bucket JSON: `covered2xx`, `coveredButNon2xx`, `unhit`.
+- **audit-coverage** — any HTTP touch from any producer (`zond run` + `checks run` + `probe` + `request` + `prepare-fixtures`). Use this to answer "did the scan reach the API at all?" — typical safe-mode runs without `zond run` still report >50% on a 1k-endpoint spec from `checks run` alone.
 
-When `recommended_action: fix_test_logic` and the body is rejected on format
-(400/422 with a field name and an "expected ..." message):
+Source breakdown (`--scope audit` text or `data.audit_coverage.by_source` JSON):
 
-1. Read the failure body: `zond db run <id> --status 422 --json`.
-2. **First pass** — swap `{{$randomString}}` for the matching typed generator:
+```
+audit-coverage: 619/1184 endpoints (52%, 1500 HTTP touches)
+  by source:
+    check     619 endpoints, 1500 events
+    regular     0 endpoints,    0 events
+    probe       0 endpoints,    0 events
+    request     3 endpoints,    3 events
+```
 
-   | API expects   | Use                  |
-   |---------------|----------------------|
-   | email         | `{{$randomEmail}}`   |
-   | hostname/FQDN | `{{$randomFqdn}}`    |
-   | URL           | `{{$randomUrl}}`     |
-   | IPv4          | `{{$randomIpv4}}`    |
-   | UUID          | `{{$uuid}}`          |
-   | integer       | `{{$randomInt}}`     |
-   | ISO date      | `{{$randomIsoDate}}` |
-   | date          | `{{$randomDate}}`    |
-   | person name   | `{{$randomName}}`    |
+Producers opt out via `ZOND_CHECKS_PERSIST=0`.
 
-3. **Second pass** — if a typed generator still fails (regex too strict, enum,
-   business constraint), drop to a hardcoded literal that satisfies the contract
-   (e.g. `"https://example.com"`, `"info@example.com"`, `"2026-01-01T00:00:00Z"`).
-4. **Dependent IDs** (`audience_id`, `topic_id`, anything that must reference an
-   existing resource) — generators cannot help. Either capture the ID from a
-   prior `create_*` step in the same suite, or move that creation into a
-   `setup: true` suite and reference the captured variable.
+**Quality signals to gate CI on** (not raw pass-coverage):
 
-## Phase 5 — Proactive bug hunting (probes)
+| 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` |
 
-Run on a passing API to surface latent bugs.
+## Phase 9 — Share findings
 
 ```bash
-# Negative-input — 5xx on malformed bodies/query/path
-zond probe-validation <spec> --output apis/<name>/probes/validation
-zond run apis/<name>/probes/validation --json
+zond report export <run-id>                                # default: triage/<api>/run-<id>/
+zond report bundle 135..142 -o triage/sweep/               # all artefacts (default): case-study + export + diagnose + index.md
+zond report bundle <run-id> --include case-study,diagnose  # subset only (drop export)
+zond report bundle --session <id> -o triage/session/       # group by session
+```
 
-# Undeclared HTTP methods — 5xx or unexpected 2xx on methods not in spec
-zond probe-methods <spec> --output apis/<name>/probes/methods
-zond run apis/<name>/probes/methods --json
+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).
 
-# Triage
-zond db diagnose <run-id> --json
+Offer this proactively after a run surfaces `definitely_bug`
+(5xx / schema violation / mass-assignment 2xx). Skip for `env_issue` /
+`quirk`.
+
+## One-shot smoke audit — `zond audit`
+
+**`zond audit` is the breadth pass, not "full audit".** It covers the
+*smoke + coverage* slice — prepare-fixtures → generate → probe static
+→ session-wrapped run on tests+probes → coverage → `audit-report.html`.
+Depth (stateful checks, security probes against R18 evidence-gates,
+m-20 annotate, `--learn-apply` iteration) is the **skill's job, not
+audit's**: those stages need decisions audit can't make
+(annotate-before-stateful, scoping after auth-cluster, evidence
+preconditions). Use audit for: CI smoke, demo, "first 5 minutes on a
+new API". For a real depth campaign, walk Phase 0–9 from this skill.
+
+```bash
+zond audit --api <name> --dry-run                       # print stage plan
+zond audit --api <name>                                  # safe mode (default) — no live probes
+zond audit --api <name> --live --with-mass-assignment --with-security   # full live pipeline (throwaway/sandbox only)
+zond audit --api <name> --out reports/audit-<name>.html
 ```
 
-Typical findings:
-- **5xx on null / empty / oversized body** → missing input validation.
-- **5xx on wrong type** (string for int, etc.) → unguarded coercion.
-- **2xx on undeclared method** → contract drift (spec lies, or method is unprotected).
-- **5xx on missing required field** → uncaught NPE on the server.
+**ARV-264 safe vs live decision matrix.** Default is `--safe` (implicit;
+no flag needed). `--live` is the opt-in for traffic that mutates the
+target API.
+
+| Concern | `--safe` (default) | `--live` |
+|---|---|---|
+| `prepare-fixtures` mode | single-pass path-FK discovery (GET) | same — single-pass, never POST-creates |
+| `probe mass-assignment` | skipped even if `--with-mass-assignment` set, with a warning | runs when `--with-mass-assignment` set |
+| `probe security` (SSRF/CRLF/redirect) | skipped even if `--with-security` set, with a warning | runs when `--with-security` set |
+| `probe static` (validation+methods) | always runs — pure spec walk, no live traffic | same |
+| `run tests / probes` | runs against the live API but only generated GET-shape suites by default | same |
+
+**Pre-flight warnings (printed before any subprocess fires):** missing
+`auth_token` when the spec declares securitySchemes (probes will skip
+with 401 and the report will read misleadingly green); no
+securitySchemes declared in the spec (open API or incomplete spec —
+auth-related checks will skip).
+
+**Rule of thumb.** Unknown-scope PAT against a production API → `--safe`
+(default). Throwaway account / sandbox tenant → `--live` is fine. Never
+run `--live` against shared/production data on first contact.
+
+Each stage prints `==> Stage N/M: <name>` and a completion line
+`└─ OK · Ns` / `FAIL (exit K) · Ns` / `SKIPPED (reason)`. Exit 1 if
+any non-coverage stage failed.
+
+`generate` skipped via mtime when `tests/` is fresher than `spec.json`
+(pass `--force` to override).
+
+**Session reuse (ARV-65)**: if `.zond/current-session` is already set
+when audit starts (i.e. user ran `zond session start` first), audit
+reuses that session — `session-start` and `session-end` stages skip
+with reason `reusing active session <id>`. The user's session stays
+active after audit returns; runs inside audit are stamped with the
+outer `session_id` and roll up under the user's `coverage --union
+session` later.
+
+ARV-158: when any run inside the audit session has failures, the
+generated `audit-report.html` embeds a "Failures by run" section with
+collapsible `<details>` per run — `by_recommended_action` buckets +
+first example (method, path, status, reason) + concrete drill-down
+commands (`zond db diagnose --run-id N --json`, `zond report export
+N`). Triage starts from the rendered HTML; you only fall back to CLI
+queries when you need fields outside the example slice.
+
+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):
 
-Filter probe scope when an API is large:
 ```bash
-zond probe-validation <spec> --tag <spec-tag> --max-per-endpoint 20
-zond probe-methods <spec> --tag <spec-tag>
+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
 ```
 
-## Phase 6 — Coverage report & spec drift
+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 coverage --api <name> --fail-on-coverage 80
-zond coverage --api <name> --run-id <id>          # per-run breakdown
-zond sync <spec> --tests apis/<name>/tests        # detect new/removed endpoints
+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 + field-level body diff (.data.body_changes[], ARV-339)
+zond db run <id> --report yaml                # run snapshot as YAML (ARV-338) — keep/diff as text
 ```
 
+> **db --json envelope shape** (consistent across siblings): the array
+> always lives under `data.<plural>`, not directly under `data`.
+> `db runs` → `.data.runs[]`, `db collections` → `.data.collections[]`,
+> `db run <id> --status …` → `.data.results[]`. Top-level totals on runs
+> are at `runs[].total/passed/failed`, not under a `.summary` wrapper.
+
+`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
 
-- Tokens go in `apis/<name>/.env.yaml` (auto-gitignored), referenced as `{{auth_token}}`.
-- Login-flow tokens: a `setup: true` suite captures into vars that propagate to later
-  suites in the same run. See `apis/<name>/tests/setup.yaml` examples emitted by `zond generate`.
-- `zond run --env <name>` loads `.env.<name>.yaml` from the API directory.
+- `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 to `zond-scenarios`
+## When to hand off
 
-- The user asks for a multi-step user journey, business flow, or fixture creation
-  through the API (login → create cart → checkout → cleanup).
-- A failing run's root cause requires a hand-written multi-step suite that
-  `zond generate` cannot express.
+- "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`
 
-For YAML format (assertions, generators, captures, `always: true` cleanup,
-`setup: true` propagation), see `ZOND.md` at the repo root or `zond run --help`.
+If the user is mid-workflow in one of those, don't restart from here.