@kirrosh/zond 0.23.0 → 0.26.0

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

@@ -29,16 +29,28 @@ For triage of a failing run — see `zond-triage`.
 - **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.
+  — 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. `.env.yaml`
-  values are editable (see ARV-114).
+  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
@@ -55,12 +67,15 @@ For triage of a failing run — see `zond-triage`.
   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.
+  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.
-- **Cascade cap is 8 passes** (`zond prepare-fixtures --cascade [--seed]`)
-  — never override without a written reason.
+- **`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
 
@@ -101,12 +116,13 @@ probes/                      ← probe-emitted suites
 - "Generate should sync `.env.yaml`" is a rejected design (decision-7,
   m-17).
 
-### Manual fixture-bootstrap (when `prepare-fixtures --seed` can't help)
+### Manual fixture-bootstrap (you fill every value)
 
-`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:
+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 |
 |---|---|
@@ -116,7 +132,7 @@ hand-off:
 `--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`.
+with a `.env.yaml.bak` backup.
 
 ### When to read which file
 
@@ -153,7 +169,9 @@ accept `--json` — use `--report json`.
 
 | 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 |
+| "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` |
@@ -181,32 +199,85 @@ 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.
+`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>                          # 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
+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
 ```
 
-`--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.
+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.
 
-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.
+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
@@ -218,7 +289,7 @@ your downstream check needs:
 
 | Aspect | Dump produces | Feeds into |
 |---|---|---|
-| `--seed-bodies` | request-body schema per resource | `prepare-fixtures --seed`, all stateful checks |
+| `--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) |
@@ -260,7 +331,36 @@ 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.
+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
 
@@ -269,9 +369,15 @@ zond generate apis/<name>/spec.json --output apis/<name>/tests [--tag <spec-tag>
 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.
+`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
@@ -318,6 +424,13 @@ zond session end
 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.
@@ -363,29 +476,47 @@ 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
+zond checks run --api <name> --check stateful --report ndjson --live   # CRUD create-chains need --live
 ```
 
-5 m-20 stateful checks:
+**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`.
+
 **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> \
+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.
@@ -416,13 +547,27 @@ 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>
+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).
 
@@ -448,16 +593,34 @@ 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 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> --fail-on-coverage 50            # CI gate (use hit-coverage)
+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)
+```
+
+**Dual-metric output (ARV-265).** `zond coverage` prints two blocks side-by-side by default:
+
+- **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.
+
+Source breakdown (`--scope audit` text or `data.audit_coverage.by_source` JSON):
+
+```
+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
 ```
 
-**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`.
+Producers opt out via `ZOND_CHECKS_PERSIST=0`.
 
 **Quality signals to gate CI on** (not raw pass-coverage):
 
@@ -474,8 +637,8 @@ not API bug), `unhit`.
 
 ```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 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
 ```
 
@@ -489,29 +652,69 @@ Offer this proactively after a run surfaces `definitely_bug`
 (5xx / schema violation / mass-assignment 2xx). Skip for `env_issue` /
 `quirk`.
 
-## One-shot full audit
+## One-shot smoke audit — `zond 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.
+**`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                       # 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> --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
 ```
 
+**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).
 
-**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`.
+**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.
@@ -582,9 +785,16 @@ verifying a fix** — small focused work. For breadth, use Phase 3
 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
+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

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

@@ -1,7 +1,7 @@
 # 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).
+# resolution (.zond/zond.db, apis/<name>/, .zond/current-api are anchored here).
 
 version: 1
 

package/src/cli/commands/prepare-fixtures.ts

@@ -1,19 +1,18 @@
 /**
- * `zond prepare-fixtures` — unified fixture-pack command.
+ * `zond prepare-fixtures` — single-pass fixture-pack command.
  *
- * Consolidates the former `discover` and `bootstrap` (TASK-299, m-13 D):
+ * Deterministically fills `apis/<name>/.env.yaml` with FK ids that can be
+ * resolved from list/read endpoints in a single discover pass, and reports
+ * which fixtures are still missing so an agent (or the user) can fill the
+ * gaps by hand (`fixtures add` / editing `.env.yaml`).
  *
  *   - default                 → single-pass discover (auto-fill FK ids
  *                                from list endpoints).
- *   - --cascade               → multi-pass cascade (former bootstrap).
- *   - --seed                  → cascade + POST-create when discover misses
- *                                (implies --cascade).
- *   - --verify / --refresh    → revalidate fixtures via read-by-id
- *                                (former `discover --verify/--refresh`).
+ *   - --verify / --refresh    → revalidate fixtures via read-by-id.
  *
- * The imperative cores (`discoverCommand`, `bootstrapCommand`) live in
- * the original modules and are still consumed directly by tests. This
- * module only owns the CLI surface.
+ * The imperative core (`discoverCommand`) lives in the original module and
+ * is still consumed directly by tests. This module only owns the CLI
+ * surface.
  */
 
 import type { Command } from "commander";
@@ -23,7 +22,6 @@ import { getDb } from "../../db/schema.ts";
 import { findCollectionByNameOrId } from "../../db/queries.ts";
 import { printError } from "../output.ts";
 import { discoverCommand } from "./discover.ts";
-import { bootstrapCommand } from "./bootstrap.ts";
 import { loadEnvMeta } from "../../core/parser/variables.ts";
 import { resolveTimeoutMs } from "../../core/workspace/config.ts";
 import { getApi, MISSING_API_MESSAGE } from "../util/api-context.ts";
@@ -32,9 +30,9 @@ export function registerPrepareFixtures(program: Command): void {
   program
     .command("prepare-fixtures")
     .description(
-      "Auto-fill apis/<name>/.env.yaml — single-pass discover by default, " +
-      "or `--cascade` for the multi-pass discover+seed flow (replaces the legacy " +
-      "`discover` and `bootstrap` commands; TASK-299).",
+      "Auto-fill apis/<name>/.env.yaml in a single discover pass: resolve FK " +
+      "ids from list/read endpoints and report which fixtures are still " +
+      "missing (fill those by hand via `fixtures add` / editing .env.yaml).",
     )
     // Not `requiredOption` — the value can also come from the program-level
     // --api flag (parsed by program.ts and mirrored into ZOND_API_GLOBAL),
@@ -46,13 +44,9 @@ export function registerPrepareFixtures(program: Command): void {
     .option("--api-dir <path>", "Override apis/<name>/ root (defaults to the collection's base_dir)")
     .option("--env <path>", "Override .env.yaml path (defaults to <api-dir>/.env.yaml)")
     .option("--apply", "Write discovered values to .env.yaml (with .env.yaml.bak backup). Default: dry-run.")
-    .option("--cascade", "Multi-pass cascade discover (former `bootstrap`). Required for --seed / --force / --max-passes.")
-    .option("--seed", "POST-create resources when discover can't find an existing record (implies --cascade)")
-    .option("--force", "Re-discover/re-seed even if a fixture is already filled (cascade only)")
-    .option("--verify", "GET each fixture's read-by-id endpoint and classify live/stale/unknown (single-pass only). Combine with --apply (or use --refresh) to drop stale fixtures and re-resolve them. (TASK-281)")
-    .option("--refresh", "Shortcut for --verify --apply (single-pass only). (TASK-281)")
+    .option("--verify", "GET each fixture's read-by-id endpoint and classify live/stale/unknown. Combine with --apply (or use --refresh) to drop stale fixtures and re-resolve them. (TASK-281)")
+    .option("--refresh", "Shortcut for --verify --apply. (TASK-281)")
     .option("--timeout <ms>", "Per-request timeout in ms (overrides apis/<name>/.env.yaml `timeoutMs` and zond.config.yml `defaults.timeout_ms`; default 30000)", parsePositiveInt("--timeout"))
-    .option("--max-passes <n>", "Cap on cascade passes (default 8; cascade only)", parsePositiveInt("--max-passes"))
     .action(async (opts, cmd: Command) => {
       // ARV-53: --api resolution lives in cli/util/api-context.ts —
       // local opt > ancestor opt > ZOND_API_GLOBAL/ZOND_API/.zond/current-api.
@@ -64,22 +58,9 @@ export function registerPrepareFixtures(program: Command): void {
       }
       opts.api = apiName;
 
-      const cascade = opts.cascade === true || opts.seed === true;
       const refresh = opts.refresh === true;
       const verify = opts.verify === true || refresh;
 
-      // Flag combos that don't make sense — fail fast with a clear hint.
-      if (cascade && verify) {
-        printError("--verify / --refresh are single-pass options; drop --cascade/--seed or drop --verify.");
-        process.exitCode = 2;
-        return;
-      }
-      if (!cascade && (opts.force === true || typeof opts.maxPasses === "number")) {
-        printError("--force / --max-passes only apply with --cascade (or --seed).");
-        process.exitCode = 2;
-        return;
-      }
-
       const resolved = resolveSpecArg(undefined, opts.api, opts.db);
       if ("error" in resolved) { printError(resolved.error); process.exitCode = 2; return; }
 
@@ -100,25 +81,6 @@ export function registerPrepareFixtures(program: Command): void {
       } catch { /* meta is best-effort */ }
       const timeoutMs = resolveTimeoutMs(opts.timeout, envTimeout);
 
-      if (cascade) {
-        process.exitCode = await bootstrapCommand({
-          specPath: resolved.spec,
-          apiDir,
-          envPath: opts.env,
-          apply: opts.apply === true,
-          seed: opts.seed === true,
-          force: opts.force === true,
-          timeoutMs,
-          maxPasses: opts.maxPasses,
-          json: globalJson(cmd),
-          // ARV-205 (R10/F6, R13/F19): surface the user-facing command name
-          // in the JSON envelope. Without this the user sees command="bootstrap"
-          // even though they typed `zond prepare-fixtures …`.
-          commandName: "prepare-fixtures",
-        });
-        return;
-      }
-
       process.exitCode = await discoverCommand({
         specPath: resolved.spec,
         apiDir,