@kirrosh/zond 0.22.0 → 0.26.0

package/src/db/schema.ts

@@ -1,15 +1,24 @@
 import { Database } from "bun:sqlite";
-import { resolve } from "path";
-import { existsSync } from "fs";
+import { dirname, resolve } from "path";
+import { existsSync, mkdirSync } from "fs";
 import { findWorkspaceRoot } from "../core/workspace/root.ts";
+import { applyMigrations } from "./migrate.ts";
 
 let _db: Database | null = null;
 let _dbPath: string | null = null;
 
+/**
+ * Default DB path lives under `<workspace>/.zond/zond.db` to keep runtime
+ * artifacts out of the project root. (The flat `<workspace>/zond.db` layout
+ * was dropped in m-25 — pass an explicit `--db` to target a legacy file.)
+ */
+function defaultDbPath(): string {
+  const root = findWorkspaceRoot().root;
+  return resolve(root, ".zond", "zond.db");
+}
+
 export function getDb(dbPath?: string): Database {
-  const path = dbPath
-    ? resolve(dbPath)
-    : (_dbPath ?? resolve(findWorkspaceRoot().root, "zond.db"));
+  const path = dbPath ? resolve(dbPath) : (_dbPath ?? defaultDbPath());
 
   // If cached connection exists, verify the file still exists
   if (_db && _dbPath === path && existsSync(path)) return _db;
@@ -20,19 +29,68 @@ export function getDb(dbPath?: string): Database {
     _db = null;
     _dbPath = null;
   }
+  // SQLite won't auto-create parent dirs; ensure `.zond/` (or any custom
+  // path's parent) exists before opening the file.
+  const parent = dirname(path);
+  if (!existsSync(parent)) mkdirSync(parent, { recursive: true });
+
   const db = new Database(path, { create: true });
 
   // Performance and integrity settings
   db.exec("PRAGMA journal_mode = WAL");
   db.exec("PRAGMA foreign_keys = ON");
+  // ARV-163: concurrent zond processes (e.g. `probe security` in one terminal
+  // + `checks run` in another) collide on the write-lock and surface as
+  // "database is locked". Letting SQLite spin at the C-level for up to 5s
+  // resolves the overwhelming majority without any per-call retry logic.
+  // `synchronous=NORMAL` is safe under WAL and cuts fsync overhead in the
+  // bulk-insert path (saveResults). withDbRetry() in this file remains the
+  // belt-and-suspenders for the rare long-running transactions.
+  db.exec("PRAGMA busy_timeout = 5000");
+  db.exec("PRAGMA synchronous = NORMAL");
 
   runMigrations(db);
 
+  // ARV-127: file-based migrations sit on top of the legacy PRAGMA
+  // path. On an existing DB the runner pre-seeds `schema_migrations`
+  // so the v9→v10 inline migration (now mirrored in
+  // src/db/migrations/0001_run_kind.sql) is treated as applied.
+  applyMigrations(db);
+
   _db = db;
   _dbPath = path;
   return db;
 }
 
+/**
+ * ARV-163: retry wrapper for SQLite write paths that may collide with
+ * concurrent zond processes. `PRAGMA busy_timeout` already absorbs short
+ * contention at the C level — this wrapper only catches the residual cases
+ * where the lock holder runs longer than the timeout (e.g. a big
+ * `saveResults` bulk insert during a parallel `probe security` cleanup).
+ *
+ * Detects bun:sqlite's "database is locked" / "SQLITE_BUSY" message shapes;
+ * other errors propagate immediately. Backoff: 100, 200, 400, 800ms capped at
+ * 4 attempts (≈1.5s total) so we never silently stall a CLI command.
+ */
+export function withDbRetry<T>(label: string, fn: () => T): T {
+  const delaysMs = [100, 200, 400, 800];
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= delaysMs.length; attempt++) {
+    try {
+      return fn();
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (!/database is locked|SQLITE_BUSY/i.test(msg)) throw err;
+      lastError = err;
+      if (attempt === delaysMs.length) break;
+      Bun.sleepSync(delaysMs[attempt]!);
+    }
+  }
+  const msg = lastError instanceof Error ? lastError.message : String(lastError);
+  throw new Error(`SQLite still locked after ${delaysMs.length + 1} attempts (${label}): ${msg}`);
+}
+
 export function closeDb(): void {
   if (_db) {
     try { _db.close(); } catch {}
@@ -41,7 +99,7 @@ export function closeDb(): void {
   }
 }
 
-export function resetDb(): void {
+function resetDb(): void {
   if (_db) { try { _db.close(); } catch {} }
   _db = null;
   _dbPath = null;
@@ -51,7 +109,7 @@ export function resetDb(): void {
 // Schema
 // ──────────────────────────────────────────────
 
-const SCHEMA_VERSION = 2;
+const SCHEMA_VERSION = 10;
 
 const SCHEMA = `
   CREATE TABLE IF NOT EXISTS runs (
@@ -67,7 +125,16 @@ const SCHEMA = `
     branch        TEXT,
     environment   TEXT,
     duration_ms   INTEGER,
-    collection_id INTEGER REFERENCES collections(id)
+    collection_id INTEGER REFERENCES collections(id),
+    session_id    TEXT,
+    tags          TEXT,
+    -- ARV-55: classify a run once at INSERT time so coverage / diagnose
+    -- queries don't have to re-derive "is this a probe-only run?" from
+    -- the results' suite_file paths. ARV-265 extends the CHECK list with
+    -- 'request' (zond request in-session) and 'fixture' (prepare-fixtures
+    -- cascade list-calls) so audit-coverage can attribute HTTP touches
+    -- back to the producer.
+    run_kind      TEXT NOT NULL DEFAULT 'regular' CHECK (run_kind IN ('regular','probe','check','request','fixture'))
   );
 
   CREATE TABLE IF NOT EXISTS results (
@@ -86,7 +153,12 @@ const SCHEMA = `
     assertions       TEXT,
     captures         TEXT,
     response_headers TEXT,
-    suite_file       TEXT
+    suite_file       TEXT,
+    provenance       TEXT,
+    failure_class    TEXT,
+    failure_class_reason TEXT,
+    spec_pointer     TEXT,
+    spec_excerpt     TEXT
   );
 
   CREATE TABLE IF NOT EXISTS collections (
@@ -98,44 +170,6 @@ const SCHEMA = `
     base_dir     TEXT
   );
 
-  CREATE TABLE IF NOT EXISTS ai_generations (
-    id                INTEGER PRIMARY KEY AUTOINCREMENT,
-    collection_id     INTEGER REFERENCES collections(id),
-    prompt            TEXT NOT NULL,
-    model             TEXT NOT NULL,
-    provider          TEXT NOT NULL,
-    generated_yaml    TEXT,
-    output_path       TEXT,
-    status            TEXT NOT NULL DEFAULT 'pending',
-    error_message     TEXT,
-    prompt_tokens     INTEGER,
-    completion_tokens INTEGER,
-    duration_ms       INTEGER,
-    created_at        TEXT NOT NULL DEFAULT (datetime('now'))
-  );
-
-  CREATE TABLE IF NOT EXISTS chat_sessions (
-    id          INTEGER PRIMARY KEY AUTOINCREMENT,
-    title       TEXT,
-    provider    TEXT NOT NULL,
-    model       TEXT NOT NULL,
-    created_at  TEXT NOT NULL DEFAULT (datetime('now')),
-    last_active TEXT NOT NULL DEFAULT (datetime('now'))
-  );
-
-  CREATE TABLE IF NOT EXISTS chat_messages (
-    id            INTEGER PRIMARY KEY AUTOINCREMENT,
-    session_id    INTEGER NOT NULL REFERENCES chat_sessions(id),
-    role          TEXT NOT NULL,
-    content       TEXT NOT NULL,
-    tool_name     TEXT,
-    tool_args     TEXT,
-    tool_result   TEXT,
-    input_tokens  INTEGER,
-    output_tokens INTEGER,
-    created_at    TEXT NOT NULL DEFAULT (datetime('now'))
-  );
-
   CREATE TABLE IF NOT EXISTS settings (
     key   TEXT PRIMARY KEY,
     value TEXT NOT NULL
@@ -143,13 +177,27 @@ const SCHEMA = `
 
   CREATE INDEX IF NOT EXISTS idx_runs_started      ON runs(started_at DESC);
   CREATE INDEX IF NOT EXISTS idx_runs_collection    ON runs(collection_id);
+  CREATE INDEX IF NOT EXISTS idx_runs_session       ON runs(session_id, started_at DESC);
   CREATE INDEX IF NOT EXISTS idx_results_run        ON results(run_id);
   CREATE INDEX IF NOT EXISTS idx_results_status     ON results(status);
   CREATE INDEX IF NOT EXISTS idx_results_name       ON results(suite_name, test_name);
   CREATE INDEX IF NOT EXISTS idx_collections_name   ON collections(name);
-  CREATE INDEX IF NOT EXISTS idx_ai_gen_collection  ON ai_generations(collection_id);
-  CREATE INDEX IF NOT EXISTS idx_chat_messages_session ON chat_messages(session_id);
-  CREATE INDEX IF NOT EXISTS idx_chat_sessions_active  ON chat_sessions(last_active DESC);
+
+  CREATE TABLE IF NOT EXISTS lint_runs (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    spec_path       TEXT NOT NULL,
+    started_at      TEXT NOT NULL,
+    finished_at     TEXT,
+    total           INTEGER NOT NULL DEFAULT 0,
+    high_count      INTEGER NOT NULL DEFAULT 0,
+    medium_count    INTEGER NOT NULL DEFAULT 0,
+    low_count       INTEGER NOT NULL DEFAULT 0,
+    endpoint_count  INTEGER NOT NULL DEFAULT 0,
+    config_json     TEXT,
+    issues_json     TEXT
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_lint_runs_spec ON lint_runs(spec_path, started_at DESC);
 `;
 
 function runMigrations(db: Database): void {
@@ -165,6 +213,86 @@ function runMigrations(db: Database): void {
       // Migration v1→v2: add suite_file column to results
       db.exec("ALTER TABLE results ADD COLUMN suite_file TEXT");
     }
+    if (ver >= 2 && ver < 3) {
+      // Migration v2→v3: add provenance column (test source metadata)
+      db.exec("ALTER TABLE results ADD COLUMN provenance TEXT");
+    }
+    if (ver >= 3 && ver < 4) {
+      // Migration v3→v4: add failure classification columns
+      db.exec("ALTER TABLE results ADD COLUMN failure_class TEXT");
+      db.exec("ALTER TABLE results ADD COLUMN failure_class_reason TEXT");
+    }
+    if (ver >= 4 && ver < 5) {
+      // Migration v4→v5: add spec_pointer + spec_excerpt (frozen OpenAPI evidence)
+      db.exec("ALTER TABLE results ADD COLUMN spec_pointer TEXT");
+      db.exec("ALTER TABLE results ADD COLUMN spec_excerpt TEXT");
+    }
+    if (ver >= 5 && ver < 6) {
+      // Migration v5→v6: add lint_runs table for `zond lint-spec` history.
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS lint_runs (
+          id              INTEGER PRIMARY KEY AUTOINCREMENT,
+          spec_path       TEXT NOT NULL,
+          started_at      TEXT NOT NULL,
+          finished_at     TEXT,
+          total           INTEGER NOT NULL DEFAULT 0,
+          high_count      INTEGER NOT NULL DEFAULT 0,
+          medium_count    INTEGER NOT NULL DEFAULT 0,
+          low_count       INTEGER NOT NULL DEFAULT 0,
+          endpoint_count  INTEGER NOT NULL DEFAULT 0,
+          config_json     TEXT,
+          issues_json     TEXT
+        );
+        CREATE INDEX IF NOT EXISTS idx_lint_runs_spec ON lint_runs(spec_path, started_at DESC);
+      `);
+    }
+    if (ver >= 6 && ver < 7) {
+      // Migration v6→v7: add session_id column to runs for grouping CLI invocations
+      // (e.g. `zond hunt`, scripted post-init runs) into one campaign.
+      db.exec("ALTER TABLE runs ADD COLUMN session_id TEXT");
+      db.exec("CREATE INDEX IF NOT EXISTS idx_runs_session ON runs(session_id, started_at DESC)");
+    }
+    if (ver >= 7 && ver < 8) {
+      // Migration v7→v8: drop the unused AI/chat tables. They were a legacy
+      // experiment (in-app chat-driven YAML generation) that never shipped a
+      // user-facing surface and have no consumers in the codebase.
+      db.exec("DROP TABLE IF EXISTS chat_messages");
+      db.exec("DROP TABLE IF EXISTS chat_sessions");
+      db.exec("DROP TABLE IF EXISTS ai_generations");
+    }
+    if (ver >= 8 && ver < 9) {
+      // Migration v8→v9: tags column on runs (JSON array of strings — union
+      // of suite-level tags actually executed in the run, plus any explicit
+      // --tag filters). Powers `coverage --union tag:<name>` (TASK-274).
+      db.exec("ALTER TABLE runs ADD COLUMN tags TEXT");
+    }
+    if (ver >= 9 && ver < 10) {
+      // Migration v9→v10 (ARV-55): classify each historical run by suite
+      // kind so coverage's default query becomes a column compare. The
+      // CHECK constraint can't be added retroactively without a table
+      // rebuild — accept the looser column for legacy rows; new INSERTs
+      // go through `createRun()` which only emits known kinds.
+      db.exec("ALTER TABLE runs ADD COLUMN run_kind TEXT NOT NULL DEFAULT 'regular'");
+      // Backfill: derive kind per existing run from its stored results.
+      // `every` semantics mirror the runtime `detectRunKind` helper —
+      // pure-probe / pure-check vs anything else.
+      db.exec(`
+        UPDATE runs SET run_kind = 'probe'
+        WHERE id IN (
+          SELECT r.id FROM runs r
+          WHERE EXISTS (SELECT 1 FROM results WHERE run_id = r.id AND suite_file IS NOT NULL AND suite_file LIKE '%probes/%')
+            AND NOT EXISTS (SELECT 1 FROM results WHERE run_id = r.id AND suite_file IS NOT NULL AND suite_file NOT LIKE '%probes/%')
+        )
+      `);
+      db.exec(`
+        UPDATE runs SET run_kind = 'check'
+        WHERE id IN (
+          SELECT r.id FROM runs r
+          WHERE EXISTS (SELECT 1 FROM results WHERE run_id = r.id AND suite_file IS NOT NULL AND suite_file LIKE '%checks/%')
+            AND NOT EXISTS (SELECT 1 FROM results WHERE run_id = r.id AND suite_file IS NOT NULL AND suite_file NOT LIKE '%checks/%')
+        )
+      `);
+    }
     db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
   })();
 }

package/src/cli/commands/export.ts

@@ -1,144 +0,0 @@
-import { dirname, basename, join } from "path";
-import { parse } from "../../core/parser/yaml-parser.ts";
-import {
-  buildCollection,
-  buildEnvironment,
-  deriveCollectionName,
-} from "../../core/exporter/postman.ts";
-import { printError, printSuccess, printWarning } from "../output.ts";
-import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
-
-export interface ExportOptions {
-  testsPath: string;
-  output: string;
-  env?: string;
-  collectionName?: string;
-  json?: boolean;
-}
-
-export async function exportCommand(options: ExportOptions): Promise<number> {
-  // 1. Parse test suites
-  let suites;
-  try {
-    suites = await parse(options.testsPath);
-  } catch (err) {
-    const msg = `Failed to parse tests: ${(err as Error).message}`;
-    if (options.json) {
-      printJson(jsonError("export postman", [msg]));
-    } else {
-      printError(msg);
-    }
-    return 2;
-  }
-
-  if (suites.length === 0) {
-    const msg = "No test suites found";
-    if (options.json) {
-      printJson(jsonError("export postman", [msg]));
-    } else {
-      printError(msg);
-    }
-    return 1;
-  }
-
-  // 2. Derive collection name
-  const collectionName =
-    options.collectionName ?? deriveCollectionName(options.testsPath);
-
-  // 3. Build collection
-  const { collection, warnings } = buildCollection(suites, collectionName);
-
-  // Count total items across all folders
-  const totalItems = collection.item.reduce((sum, folder) => sum + folder.item.length, 0);
-
-  // 4. Write collection file
-  try {
-    await Bun.write(options.output, JSON.stringify(collection, null, 2));
-  } catch (err) {
-    const msg = `Failed to write collection file: ${(err as Error).message}`;
-    if (options.json) {
-      printJson(jsonError("export postman", [msg], warnings));
-    } else {
-      printError(msg);
-    }
-    return 2;
-  }
-
-  // 5. Optional env export
-  let envOutput: string | undefined;
-  if (options.env) {
-    let envVars: Record<string, string>;
-    try {
-      const text = await Bun.file(options.env).text();
-      const parsed = Bun.YAML.parse(text);
-      if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new Error("Environment file must be a YAML object");
-      }
-      // Convert all values to strings
-      envVars = {};
-      for (const [k, v] of Object.entries(parsed as Record<string, unknown>)) {
-        envVars[k] = String(v);
-      }
-    } catch (err) {
-      const msg = `Failed to read env file: ${(err as Error).message}`;
-      if (options.json) {
-        printJson(jsonError("export postman", [msg], warnings));
-      } else {
-        printError(msg);
-      }
-      return 2;
-    }
-
-    // Derive env name: e.g. ".env.staging.yaml" → "staging", ".env.yaml" → collectionName
-    const envBasename = basename(options.env);
-    const envNameMatch = envBasename.match(/^\.?env\.(.+?)\.ya?ml$/);
-    const envName = envNameMatch ? envNameMatch[1]! : collectionName;
-
-    const environment = buildEnvironment(envVars, envName);
-
-    // Output path: same directory as output, same base name with .postman_environment.json
-    const outBase = basename(options.output).replace(/\.postman\.json$/, "").replace(/\.json$/, "");
-    const outDir = dirname(options.output);
-    envOutput = join(outDir, `${outBase}.postman_environment.json`);
-
-    try {
-      await Bun.write(envOutput, JSON.stringify(environment, null, 2));
-    } catch (err) {
-      const msg = `Failed to write environment file: ${(err as Error).message}`;
-      if (options.json) {
-        printJson(jsonError("export postman", [msg], warnings));
-      } else {
-        printError(msg);
-      }
-      return 2;
-    }
-  }
-
-  // 6. Output result
-  if (options.json) {
-    printJson(
-      jsonOk(
-        "export postman",
-        {
-          output: options.output,
-          suites: suites.length,
-          items: totalItems,
-          ...(envOutput !== undefined ? { envOutput } : {}),
-        },
-        warnings
-      )
-    );
-  } else {
-    for (const w of warnings) {
-      printWarning(w);
-    }
-    printSuccess(
-      `Exported ${suites.length} suite(s) / ${totalItems} request(s) → ${options.output}`
-    );
-    if (envOutput) {
-      printSuccess(`Environment exported → ${envOutput}`);
-    }
-  }
-
-  return 0;
-}

package/src/cli/commands/guide.ts

@@ -1,127 +0,0 @@
-import {
-  readOpenApiSpec,
-  extractEndpoints,
-  extractSecuritySchemes,
-  scanCoveredEndpoints,
-  filterUncoveredEndpoints,
-} from "../../core/generator/index.ts";
-import { compressEndpointsWithSchemas, buildGenerationGuide } from "../../core/generator/guide-builder.ts";
-import { planChunks, filterByTag } from "../../core/generator/chunker.ts";
-import { findCollectionBySpec } from "../../db/queries.ts";
-import { printError } from "../output.ts";
-import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
-
-export interface GuideOptions {
-  specPath: string;
-  testsDir?: string;
-  tag?: string;
-  json?: boolean;
-}
-
-export async function guideCommand(options: GuideOptions): Promise<number> {
-  try {
-    const doc = await readOpenApiSpec(options.specPath);
-    let endpoints = extractEndpoints(doc);
-    const securitySchemes = extractSecuritySchemes(doc);
-    const baseUrl = ((doc as any).servers?.[0]?.url) as string | undefined;
-    const title = (doc as any).info?.title as string | undefined;
-
-    let outputDir = options.testsDir;
-    if (!outputDir) {
-      try {
-        const collection = findCollectionBySpec(options.specPath);
-        outputDir = collection?.test_path ?? "./tests/";
-      } catch {
-        outputDir = "./tests/";
-      }
-    }
-
-    let coverageInfo: { covered: number; total: number; percentage: number } | undefined;
-    if (options.testsDir) {
-      const totalBefore = endpoints.length;
-      const covered = await scanCoveredEndpoints(options.testsDir);
-      const uncovered = filterUncoveredEndpoints(endpoints, covered);
-      const coveredCount = totalBefore - uncovered.length;
-      const percentage = totalBefore > 0 ? Math.round((coveredCount / totalBefore) * 100) : 100;
-      coverageInfo = { covered: coveredCount, total: totalBefore, percentage };
-      endpoints = uncovered;
-    }
-
-    if (endpoints.length === 0) {
-      if (options.json) {
-        printJson(jsonOk("guide", { fullyCovered: true, ...coverageInfo }));
-      } else {
-        console.log("All endpoints are covered.");
-      }
-      return 0;
-    }
-
-    if (options.tag) {
-      endpoints = filterByTag(endpoints, options.tag);
-      if (endpoints.length === 0) {
-        const msg = `No endpoints found for tag "${options.tag}"`;
-        if (options.json) printJson(jsonError("guide", [msg]));
-        else printError(msg);
-        return 1;
-      }
-    }
-
-    const plan = planChunks(endpoints);
-
-    if (plan.needsChunking && !options.tag) {
-      if (options.json) {
-        printJson(jsonOk("guide", {
-          mode: "plan",
-          title: title ?? "API",
-          totalEndpoints: plan.totalEndpoints,
-          chunks: plan.chunks,
-          ...(coverageInfo ? { coverage: coverageInfo } : {}),
-        }));
-      } else {
-        console.log(`API has ${plan.totalEndpoints} endpoints across ${plan.chunks.length} tags.`);
-        console.log("Generate per-tag with --tag <name>:\n");
-        for (const chunk of plan.chunks) {
-          console.log(`  --tag ${chunk.tag} (${chunk.count} endpoints)`);
-        }
-      }
-      return 0;
-    }
-
-    const coverageHeader = coverageInfo
-      ? `## Coverage: ${coverageInfo.covered}/${coverageInfo.total} endpoints covered (${coverageInfo.percentage}%). Generating tests for ${endpoints.length} uncovered endpoints:`
-      : undefined;
-
-    const apiContext = compressEndpointsWithSchemas(endpoints, securitySchemes);
-    const guide = buildGenerationGuide({
-      title: options.tag ? `${title ?? "API"} — tag: ${options.tag}` : (title ?? "API"),
-      baseUrl,
-      apiContext,
-      outputDir,
-      securitySchemes,
-      endpointCount: endpoints.length,
-      coverageHeader,
-      includeFormat: true,
-    });
-
-    if (options.json) {
-      printJson(jsonOk("guide", {
-        title: title ?? "API",
-        endpointCount: endpoints.length,
-        outputDir,
-        guide,
-        ...(coverageInfo ? { coverage: coverageInfo } : {}),
-      }));
-    } else {
-      console.log(guide);
-    }
-    return 0;
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    if (options.json) {
-      printJson(jsonError("guide", [message]));
-    } else {
-      printError(message);
-    }
-    return 2;
-  }
-}

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

@@ -1,97 +0,0 @@
----
-name: zond-scenarios
-description: |
-  Author multi-step API scenario tests (user journeys) with zond. Use when asked to:
-  write a scenario, model a user flow, replay a UI flow via API, chain requests with
-  captures, set up test data via API, test a workflow end-to-end. Activates on:
-  "user scenario", "API workflow", "multi-step test", "login then ...", "create then ...".
-allowed-tools: [Read, Write, Bash(zond *), Bash(bunx zond *)]
----
-
-# zond — API Scenario Tests
-
-CLI-only skill. Scenarios are **hand-written** YAML chaining multiple requests
-with captures (no `zond generate` for scenarios — `generate` only emits per-endpoint suites).
-
-## Critical rules
-- **NEVER** run `zond generate` to produce scenarios — write them manually from `.api-catalog.yaml`.
-- **NEVER** read OpenAPI/Swagger specs directly — use `zond catalog` or `zond describe`.
-- **NEVER** invent endpoints — only use entries present in `.api-catalog.yaml`.
-- **Captures are file-scoped** — variables defined in one file do not leak into others
-  unless the producing suite is marked `setup: true`.
-- Tag every scenario `[scenario, <flow-name>]`. Run by `--tag scenario` or `--tag <flow>,setup`.
-- Keep one user journey per file; chain steps within that file.
-
-## Workflow
-```bash
-# 1. Make sure the catalog is current
-zond catalog <spec> --output apis/<name>/tests
-
-# 2. Read the catalog to pick endpoints (NOT the raw spec)
-cat apis/<name>/tests/.api-catalog.yaml
-
-# 3. Author the scenario YAML (see structure below)
-
-# 4. Validate + run
-zond validate apis/<name>/tests/scenarios/<flow>.yaml
-zond run apis/<name>/tests/scenarios/<flow>.yaml --json
-
-# 5. Diagnose failures
-zond db diagnose <run-id> --json
-```
-
-## Scenario YAML — minimal structure
-```yaml
-name: user_signup_to_first_purchase
-tags: [scenario, signup_purchase]
-steps:
-  - name: register
-    request:
-      method: POST
-      url: "{{base_url}}/auth/register"
-      body: { email: "{{generate.email}}", password: "{{generate.password}}" }
-    expect: { status: 201 }
-    capture:
-      user_id: "$.id"
-      auth_token: "$.token"
-
-  - name: create_cart
-    request:
-      method: POST
-      url: "{{base_url}}/carts"
-      headers: { Authorization: "Bearer {{auth_token}}" }
-    expect: { status: 201 }
-    capture: { cart_id: "$.id" }
-
-  - name: checkout
-    request:
-      method: POST
-      url: "{{base_url}}/carts/{{cart_id}}/checkout"
-      headers: { Authorization: "Bearer {{auth_token}}" }
-    expect: { status: 200 }
-
-  - name: cleanup
-    always: true                       # runs even if earlier steps failed
-    request:
-      method: DELETE
-      url: "{{base_url}}/users/{{user_id}}"
-      headers: { Authorization: "Bearer {{auth_token}}" }
-```
-
-Key building blocks (full reference in `ZOND.md`):
-- `capture: { var: "$.json.path" }` — JSONPath extraction into scenario-local vars.
-- `expect.status` / `expect.json` / `expect.headers` — assertions.
-- `{{generate.email}}`, `{{generate.uuid}}`, `{{generate.int(1,100)}}` — value generators.
-- `always: true` on a step — guaranteed cleanup (runs on prior failure).
-- `setup: true` at the suite level — captures propagate to other suites in the run.
-
-## Sharing auth across scenarios
-Put login in `apis/<name>/tests/setup.yaml` with `setup: true`; scenarios reference
-`{{auth_token}}` directly. Run with `--tag <flow>,setup`.
-
-## When to hand off
-- Need broad endpoint coverage, bug hunting, or run diagnosis → `zond`.
-- This skill is **only** for hand-written multi-step flows / fixture creation.
-
-For full YAML structure (assertions, flow control, generators, conditional steps),
-see the YAML format section of `ZOND.md` at the repo root.