@kirrosh/zond 0.22.0 → 0.26.0

package/src/cli/commands/{init.ts → init/index.ts}

@@ -1,7 +1,8 @@
-import { setupApi, type SetupApiResult } from "../../core/setup-api.ts";
-import { printError, printSuccess } from "../output.ts";
-import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
-import { bootstrapWorkspace, type BootstrapResult } from "./init/bootstrap.ts";
+import { existsSync, readdirSync } from "node:fs";
+import { setupApi, type SetupApiResult } from "../../../core/setup-api.ts";
+import { printError, printSuccess } from "../../output.ts";
+import { jsonOk, jsonError, printJson } from "../../json-envelope.ts";
+import { bootstrapWorkspace, type BootstrapResult } from "./bootstrap.ts";
 
 export interface InitOptions {
   // register-an-API options (existing)
@@ -21,6 +22,8 @@ export interface InitOptions {
   noAgents?: boolean;
   /** Skip writing Claude Code skills under .claude/skills/. */
   noSkills?: boolean;
+  /** Remove legacy skill dirs (zond-base, zond-scenarios, …) — by default a warning is printed. */
+  pruneStaleSkills?: boolean;
   /** Override cwd for bootstrap (used by tests; CLI always uses process.cwd()). */
   cwd?: string;
   /** Override $HOME for MCP install (used by tests). */
@@ -55,7 +58,13 @@ export async function initCommand(options: InitOptions): Promise<number> {
       return 0;
     }
 
-    const bootstrap = bootstrapWorkspace({ writeAgents, writeSkills, cwd: options.cwd, home: options.home });
+    const bootstrap = bootstrapWorkspace({
+      writeAgents,
+      writeSkills,
+      pruneStaleSkills: options.pruneStaleSkills,
+      cwd: options.cwd,
+      home: options.home,
+    });
     let register: SetupApiResult | null = null;
 
     if (mode === "bootstrap+register") {
@@ -72,6 +81,8 @@ export async function initCommand(options: InitOptions): Promise<number> {
         agentsPath: bootstrap.agents?.path ?? null,
         agentsAction: bootstrap.agents?.action ?? null,
         skills: bootstrap.skills.map((s) => ({ name: s.name, path: s.path, action: s.action })),
+        staleSkills: bootstrap.staleSkills.map((s) => ({ name: s.name, path: s.path })),
+        prunedSkills: bootstrap.prunedSkills.map((s) => ({ name: s.name, path: s.path })),
       };
       if (register) {
         data.collectionId = register.collectionId;
@@ -134,6 +145,9 @@ function printBootstrapResult(b: BootstrapResult, writeAgents: boolean): void {
   for (const s of b.skills) {
     lines.push(`  ${verb(s.action)} .claude/skills/${s.name}/SKILL.md`);
   }
+  for (const s of b.prunedSkills) {
+    lines.push(`  Removed .claude/skills/${s.name}/ (stale)`);
+  }
   for (const w of b.warnings) {
     process.stderr.write(`Warning: ${w}\n`);
   }
@@ -143,8 +157,88 @@ function printBootstrapResult(b: BootstrapResult, writeAgents: boolean): void {
   } else {
     printSuccess("Workspace ready. See AGENTS.md for the CLI workflow.");
   }
+  const apiNames = listExistingApis(b.cwd);
+  if (apiNames.length === 0) {
+    process.stderr.write(
+      `\nNext steps:\n` +
+      `  1. zond add api <name> --spec <path|url>   # register API → builds .api-fixtures.yaml (manifest)\n` +
+      `  2. zond doctor --api <name>                 # gap report: which vars are UNSET in .env.yaml\n` +
+      `  3. zond prepare-fixtures --api <name> --apply   # fill .env.yaml values (single-pass); fill any gaps by hand\n` +
+      `\nNote: zond init only refreshes workspace files (skills, AGENTS.md, zond.config.yml).\n` +
+      `      It does NOT touch fixtures or .env.yaml — that's the doctor/prepare-fixtures loop above.\n`
+    );
+  } else {
+    const sample = apiNames[0]!;
+    process.stderr.write(
+      `\nFixtures untouched. zond init only refreshes skills/AGENTS.md/zond.config.yml.\n` +
+      `Verify env state with:\n` +
+      `  zond doctor --api ${sample} --missing-only   # show UNSET vars + blocked endpoints\n` +
+      `  zond prepare-fixtures --api ${sample} --apply   # discover values (single-pass); fill any gaps by hand\n`
+    );
+  }
+}
+
+function listExistingApis(cwd: string): string[] {
+  try {
+    const apisDir = `${cwd}/apis`;
+    if (!existsSync(apisDir)) return [];
+    return readdirSync(apisDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && existsSync(`${apisDir}/${d.name}/spec.json`))
+      .map((d) => d.name)
+      .sort();
+  } catch {
+    return [];
+  }
 }
 
 function verb(action: "created" | "updated" | "noop"): string {
   return action === "created" ? "Created" : action === "updated" ? "Updated" : "Up-to-date:";
 }
+
+import type { Command } from "commander";
+import { globalJson } from "../../resolve.ts";
+
+export function registerInit(program: Command): void {
+  program
+    .command("init [spec]")
+    .description("Bootstrap a workspace, or register an API when --spec is given")
+    .option("--name <name>", "API name (auto-detected from spec title if omitted)")
+    .option("--spec <path>", "Path to OpenAPI spec file (registers a single API)")
+    .option("--base-url <url>", "Override base URL")
+    .option("--dir <path>", "Target directory")
+    .option("--force", "Overwrite existing API collection")
+    .option("--insecure", "Skip TLS verification when fetching the spec")
+    .option("--db <path>", "Path to SQLite database file")
+    .option("--workspace", "Bootstrap a zond workspace (zond.config.yml, apis/, AGENTS.md)")
+    .option("--with-spec <path>", "Bootstrap workspace AND register first API from spec")
+    .option("--no-agents-md", "Skip writing AGENTS.md when bootstrapping")
+    .option("--no-skills", "Skip writing Claude Code skills under .claude/skills/")
+    .option(
+      "--prune-stale-skills",
+      "Remove .claude/skills/ dirs for retired template names (zond-base, zond-scenarios)",
+    )
+    .action(async (specPos: string | undefined, opts, cmd: Command) => {
+      const spec = opts.spec ?? specPos;
+      const json = globalJson(cmd);
+      if ((spec || opts.withSpec) && !json) {
+        process.stderr.write(
+          `Warning: 'zond init --spec' / '--with-spec' is deprecated. Use \`zond add api <name> --spec <path>\` (run \`zond init\` separately to bootstrap the workspace).\n`,
+        );
+      }
+      process.exitCode = await initCommand({
+        name: opts.name,
+        spec,
+        baseUrl: opts.baseUrl,
+        dir: opts.dir,
+        force: opts.force === true,
+        insecure: opts.insecure === true,
+        dbPath: opts.db,
+        workspace: opts.workspace === true,
+        withSpec: opts.withSpec,
+        noAgents: opts.agentsMd === false,
+        noSkills: opts.skills === false,
+        pruneStaleSkills: opts.pruneStaleSkills === true,
+        json,
+      });
+    });
+}

package/src/cli/commands/init/skills.ts

@@ -1,8 +1,11 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 import zondSkill from "./templates/skills/zond.md" with { type: "text" };
-import scenariosSkill from "./templates/skills/scenarios.md" with { type: "text" };
+import checksSkill from "./templates/skills/zond-checks.md" with { type: "text" };
+import triageSkill from "./templates/skills/zond-triage.md" with { type: "text" };
+import seedSkill from "./templates/skills/zond-seed.md" with { type: "text" };
+import warmUpSkill from "./templates/skills/warm-up-target.md" with { type: "text" };
 
 export interface SkillResult {
   name: string;
@@ -16,10 +19,103 @@ interface SkillTemplate {
 }
 
 const SKILLS: SkillTemplate[] = [
+  // Primary skill: artifact model + iron rules + full workflow
+  // (init → fixtures → annotate → generate → run → stateful checks →
+  // probes → coverage → share) + single-flow scenario authoring.
   { name: "zond", body: zondSkill },
-  { name: "zond-scenarios", body: scenariosSkill },
+  // Depth-check reference: conformance + security + m-20 stateful
+  // (cross_call_references, idempotency_replay, pagination_invariants,
+  // lifecycle_transitions) with per-aspect annotate flow.
+  { name: "zond-checks", body: checksSkill },
+  // Read-only triage of a finished run / probe artifact.
+  { name: "zond-triage", body: triageSkill },
+  // ARV-355: agent-orchestrated auto-seed loop (read gaps → order by
+  // fkDependencies → author body → request POST --capture → fix 4xx + retry).
+  { name: "zond-seed", body: seedSkill },
+  // ARV-366: warm up external-input fixtures (issue_id/file_id/integration_id)
+  // via the target's own SDK/CLI/replay — the honest-2xx ceiling zond-seed
+  // can't reach with a plain POST. Agent warms, zond stores + measures.
+  { name: "warm-up-target", body: warmUpSkill },
 ];
 
+/**
+ * Names previously emitted by `upsertSkills` but no longer in `SKILLS`.
+ * Detected as stale by `detectStaleSkills` and removed by
+ * `pruneStaleSkills` (only when the user opts in via `--prune-stale-skills`).
+ *
+ * Append a name here whenever a skill template is retired. User-authored
+ * skills (any name NOT in this list) are never touched.
+ */
+const LEGACY_SKILL_NAMES: readonly string[] = [
+  "zond-base",       // retired by skills-consolidation refactor (folded into zond)
+  "zond-scenarios",  // retired by skills-consolidation refactor (folded into zond)
+] as const;
+
+export interface StaleSkill {
+  name: string;
+  path: string;
+}
+
+/**
+ * Per-skill drift status vs the in-binary template. `missing` is
+ * non-actionable on its own (user may have intentionally passed
+ * `--no-skills`); `outdated` is the actionable one — workspace skill
+ * predates a binary upgrade and `zond init` will refresh it.
+ */
+export type SkillDriftStatus = "fresh" | "outdated" | "missing";
+
+export interface SkillDrift {
+  name: string;
+  path: string;
+  status: SkillDriftStatus;
+}
+
+/**
+ * Compare each in-binary skill template against the workspace copy at
+ * `<cwd>/.claude/skills/<name>/SKILL.md`. Returns one entry per skill —
+ * callers filter by status (`outdated` → warn the user to re-run
+ * `zond init`).
+ */
+export function detectSkillDrift(cwd: string): SkillDrift[] {
+  return SKILLS.map(({ name, body }) => {
+    const path = join(cwd, ".claude", "skills", name, "SKILL.md");
+    const desired = body.endsWith("\n") ? body : body + "\n";
+    if (!existsSync(path)) return { name, path, status: "missing" as const };
+    const current = readFileSync(path, "utf-8");
+    return {
+      name,
+      path,
+      status: (current === desired ? "fresh" : "outdated") as SkillDriftStatus,
+    };
+  });
+}
+
+/**
+ * Returns directories under `<cwd>/.claude/skills/` whose name is in
+ * `LEGACY_SKILL_NAMES`. User-authored skill directories (any other
+ * name) are intentionally ignored.
+ */
+export function detectStaleSkills(cwd: string): StaleSkill[] {
+  const out: StaleSkill[] = [];
+  for (const name of LEGACY_SKILL_NAMES) {
+    const path = join(cwd, ".claude", "skills", name);
+    if (existsSync(path)) out.push({ name, path });
+  }
+  return out;
+}
+
+/**
+ * Recursively removes the directories returned by `detectStaleSkills`.
+ * Returns the list of names that were actually removed.
+ */
+export function pruneStaleSkills(cwd: string, opts: { dryRun?: boolean } = {}): StaleSkill[] {
+  const stale = detectStaleSkills(cwd);
+  if (!opts.dryRun) {
+    for (const { path } of stale) rmSync(path, { recursive: true, force: true });
+  }
+  return stale;
+}
+
 /**
  * Idempotently writes Claude Code skills into `<cwd>/.claude/skills/<name>/SKILL.md`.
  * Body is identical to the in-binary template — overwrites on drift, noop on match.

package/src/cli/commands/init/templates/agents.md

@@ -1,73 +1,86 @@
 ## API testing with zond
 
-This workspace uses [zond](https://github.com/kirrosh/zond) for API testing. The MCP
-server is **not** configured for this workspace, so use the CLI directly.
+This workspace uses [zond](https://github.com/kirrosh/zond) for API testing — CLI
+only, no MCP server in this workspace.
+
+### Skills
+
+- **`.claude/skills/zond/SKILL.md` (primary)** — artifact model + iron
+  rules + full workflow: fixtures → annotate → generate → smoke → CRUD
+  → stateful checks → probes → coverage → report, plus single-flow
+  scenario authoring. Loads on workspace touch and on intent ("audit
+  this API", "find bugs", "write a test for X flow").
+- **`.claude/skills/zond-checks/SKILL.md`** — depth-check reference:
+  conformance + security + m-20 stateful invariants
+  (cross_call_references, idempotency_replay, pagination_invariants,
+  lifecycle_transitions) and the `zond api annotate dump+apply` flow.
+- **`.claude/skills/zond-triage/SKILL.md`** — read-only triage of a
+  finished run / probe artifact. Routes by `recommended_action` enum.
+- **`.claude/skills/zond-seed/SKILL.md`** — agent-orchestrated seed loop:
+  read fixture gaps → order by FK deps → author body → `request POST
+  --capture` → fix 4xx + retry. Fills what `prepare-fixtures` reports missing.
+- **`.claude/skills/warm-up-target/SKILL.md`** — warm external-input
+  fixtures (issue_id/file_id/integration_id) via the target's own
+  SDK/CLI/replay — the honest-2xx ceiling a plain POST can't reach.
+
+These skills work off the per-API artifacts written by `zond add api`:
 
-### Detailed playbooks (skills)
-
-Detailed task-specific playbooks live in `.claude/skills/` and are auto-discovered by
-Claude Code. Other agents (Codex, Cursor, Aider) can read them as plain markdown:
-
-- `.claude/skills/zond/SKILL.md` — end-to-end API testing: generate from OpenAPI,
-  run, diagnose failures, hunt bugs via probes, report coverage. Has explicit
-  entry points so narrow requests (only diagnose, only probe) skip earlier phases.
-- `.claude/skills/zond-scenarios/SKILL.md` — author multi-step user-journey tests
-  and fixture creation via the API (hand-written YAML with captures,
-  `setup: true`, `always: true`). NOT for spec coverage or bug hunting.
-
-### Mandatory rules (always-on)
+```
+apis/<name>/
+  spec.json              # dereferenced OpenAPI (machine source — only generators read it)
+  .api-catalog.yaml      # endpoint index (cheap to read, agent-friendly)
+  .api-resources.yaml    # CRUD chains, FK deps, ETag/soft-delete flags
+  .api-fixtures.yaml     # MANIFEST: required {{vars}} (read-only, auto-generated)
+  .env.yaml              # VALUES: variable values (user-edited; auto-gitignored)
+  tests/  scenarios/  probes/
+```
 
-- **NEVER** read OpenAPI/Swagger/JSON spec files with Read/cat — use `zond describe`,
-  `zond catalog`, or the generated `.api-catalog.yaml`.
-- **NEVER** use curl/wget for ad-hoc requests — use `zond request <method> <url>`.
-- **NEVER** write test YAML from scratch — start with `zond generate <spec> --output <dir>`,
-  then edit failing cases.
-- **NEVER** hardcode tokens — put them in `apis/<name>/.env.yaml` (already gitignored)
-  and reference as `{{auth_token}}` in test YAML.
-- `--safe` enforces GET-only; never run CRUD tests against production without explicit
-  user confirmation and a staging environment.
-- When `zond db diagnose` reports `recommended_action: report_backend_bug` — STOP, do
-  not change the test to make it pass.
+`.api-fixtures.yaml` is the **manifest** (single source of truth for the
+list of vars an API needs) and `.env.yaml` holds their **values**. Don't
+add a key to `.env.yaml` that's not in the manifest — it'll be warned and
+ignored. A missing entry in the manifest is a generator/manifest bug, not
+an env fix.
 
-### Workflow — covering an API end-to-end
+### Setup flow
 
 ```bash
-# 1. Register the API
-zond init --spec <path-or-url> --name <name> [--base-url <url>]
-zond use <name>                              # remember as current
-
-# 2. Inspect endpoints (avoid reading the raw spec)
-zond catalog <spec> --output apis/<name>     # writes .api-catalog.yaml
-zond describe <spec> --compact
-
-# 3. Generate test stubs and run smoke (GET-only)
-zond generate <spec> --output apis/<name>/tests --tag smoke
-zond run --safe --json
-
-# 4. Diagnose failures
-zond db runs --limit 5
-zond db diagnose <run-id> --json
-
-# 5. Coverage gate
-zond coverage --fail-on-coverage 50
-
-# 6. CRUD only with explicit user confirmation + staging env
-zond run --tag crud --dry-run                # show what would be sent
-zond run --tag crud --env staging
+zond init                                              # bootstrap workspace (no fixture changes)
+zond add api <name> --spec <path-or-url>               # register API + emit manifest + seed empty .env.yaml
+zond doctor --api <name> --missing-only                # gap report: which vars are UNSET
+zond prepare-fixtures --api <name>                     # gap report: verify + which FK vars need a value
+# → fill each gap yourself: `zond fixtures add` / edit .env.yaml (you pick the value)
+zond doctor --api <name>                               # re-check (exit 0 = ready)
 ```
 
-### Filtering by tag
-
-`--tag <name>` filters suites. If a `setup` suite primes auth tokens, always include
-its tag together with the target group: `--tag crud,setup`.
-
-### Auth patterns
-
-For in-memory or test backends that issue tokens via login, use a `setup.yaml` suite
-with `setup: true`. Captured variables (e.g. `auth_token`) propagate to subsequent
-suites in the same run. Do NOT hardcode bearer tokens for these flows.
-
-### Environments
-
-`zond run --env <name>` loads `.env.<name>.yaml` (or `.env.yaml` by default) from the
-API directory. Environment files are auto-gitignored by `zond init`.
+What each step does to `.env.yaml`:
+
+| Command | Touches `.env.yaml`? |
+|---|---|
+| `zond init` | no — only writes workspace/skills files |
+| `zond add api` | seeds skeleton with empty placeholders for every required var |
+| `zond doctor` | no — read-only diagnostic |
+| `zond prepare-fixtures` | no — reports gaps only; **never harvests a value** (which record/field fills a slot is your call) |
+| `zond prepare-fixtures --refresh` | unsets stale (404) ids so they resurface as gaps (`.bak` backup); does not re-resolve |
+| `zond fixtures add` / `import` | writes the value you supply (`.bak` backup) |
+| `zond refresh-api` | no — only re-snapshots `spec.json` and rebuilds the manifest |
+
+`zond refresh-api <name> [--spec <new-source>]` re-snapshots when the upstream
+spec changes.
+
+**Re-running `zond init`** is safe and expected after a CLI upgrade: it
+re-emits skills/AGENTS.md/zond.config.yml only. Fixtures stay exactly as
+they were — never relies on init to fill `.env.yaml`.
+
+### Mandatory rules (mirrored from the skills — non-negotiable)
+
+- **NEVER read raw OpenAPI/Swagger** with Read/cat/grep — use the artifacts
+  in `apis/<name>/.api-*.yaml`. Drop into `spec.json` only when a probe
+  generator needs full schemas.
+- **NEVER use curl/wget** — use `zond request <method> <url>` for ad-hoc HTTP.
+- **NEVER write test YAML from scratch for autogen flows** — start with
+  `zond generate`, then edit failures. (Hand-written YAML is fine for
+  scenarios.)
+- **NEVER hardcode tokens** — `apis/<name>/.env.yaml` (auto-gitignored),
+  reference as `{{auth_token}}`.
+- **`recommended_action: report_backend_bug` (5xx) → STOP**, do not edit
+  assertions to make the test pass.

package/src/cli/commands/init/templates/skills/warm-up-target.md

@@ -0,0 +1,122 @@
+---
+name: warm-up-target
+description: |
+  Warm up the TARGET API's environment so honest-2xx coverage stops being
+  capped by empty state. Picks up where `zond-seed` stops: the fixtures the
+  API cannot self-create via a plain POST — a real error `issue_id` (needs an
+  actual event), a `file_id` (needs a sourcemap/artifact upload), an
+  `integration_id` (needs an OAuth/app install), a `webhook_event_id` (needs a
+  replay). YOU decide HOW to warm each one using the target's OWN tooling (its
+  SDK, CLI, dashboard, replay/trigger endpoints); then harvest the resulting
+  LIVE id into `.env.yaml`. Use when honest-2xx is stuck low (~30%), when
+  `zond-seed` / `prepare-fixtures` report roots as un-seedable / external-input,
+  or the user asks to "warm up the target", "raise honest-2xx", "seed via the
+  SDK", "generate real test data". zond only STORES the id and MEASURES the
+  lift — the warm-up judgment is yours. Hand back to `zond` once warm.
+allowed-tools: [Read, Write, Edit, Bash]
+---
+
+# warm-up-target — get the API into a testable state
+
+`prepare-fixtures` reports fixture gaps; `zond-seed` fills the ones the API
+self-serves (plain `POST` + capture). Whatever is left — resources that exist
+only after a **real-world event** — is the honest-2xx ceiling. This skill
+breaks that ceiling by warming the target with **its own means**, then storing
+the live ids zond will reuse.
+
+This is **not** core zond and **not** a heuristic: zond never learns how to
+warm an API (that judgment has an infinite tail — every provider is different).
+YOU read the provider's docs/SDK and drive it; zond only records the id
+(`fixtures add`) and measures the coverage delta (`coverage`). Keep it that way
+— no warm-up logic goes into zond core (litmus test).
+
+## Iron rules
+
+- **You warm, zond stores + measures.** You run the SDK/CLI/dashboard action
+  that creates the real resource; you read the returned id; `zond fixtures add`
+  writes it. Never ask zond to "figure out" how to warm a resource.
+- **Live + throwaway/sandbox + cleanup.** Warm-ups create real state (events,
+  files, installs). Confirm `base_url` is a sandbox/test account first. Track
+  what you create; tear it down after (or use a disposable org). If you can't
+  guarantee cleanup, ask before creating.
+- **Hand off to `zond-seed` first.** Only warm what `zond-seed` marked
+  un-seedable. Don't reinvent plain-POST creation here — that's zond-seed's job.
+- **Ask early, don't reverse-engineer.** Give yourself a hard budget of ~1-2
+  attempts to derive a create-recipe from the spec/API. If a blind create 4xx/5xx
+  (missing an integer id the API doesn't expose, an opaque body shape), STOP —
+  ask the user for an example request (a working `curl`/HAR/body from their UI).
+  Extract the ids from it deterministically and replay. Do NOT spelunk 10 endpoints
+  guessing how creation works — that's the slow path the user hates.
+- **Delete only by self-captured id.** Tear-down must target the id YOUR create
+  returned, never a harvested read-fixture value. Deleting by `{{key}}` when that
+  key came from a live resource wipes pre-existing data (see ARV-368). Track
+  created ids explicitly; DELETE those and only those.
+- **Report honestly what you can't warm.** Some fixtures need a human (a paid
+  plan, a KYC step, a physical device, a manual dashboard toggle). Surface those
+  as a short "needs you" list with the exact action — never fake a value (it
+  just 422s and lies about coverage).
+- **Measure the lift.** Snapshot honest-2xx before and after so the warm-up's
+  value is visible (`zond coverage --api <name> --union session`).
+
+## Inputs — what needs warming
+
+| Signal | Command | What it tells you |
+|---|---|---|
+| Un-seedable roots | `zond-seed` handoff / `zond prepare-fixtures --api <name> --json` → `summary.fixtureGaps.unseededRoots[]` | fixtures no plain-POST can create |
+| Empty-list gaps | `prepare-fixtures` items with `status: miss-empty` | resource exists in spec, zero records in the target |
+| What each id is for | `apis/<name>/.api-resources.yaml` (the owning resource + its create/read endpoints) | which real-world action mints this id |
+| Current honest-2xx | `zond coverage --api <name> --union session --json` | the ceiling you're trying to raise |
+
+## Warm-up patterns (pick per resource)
+
+The resource's *nature* tells you the warm-up path. Common families:
+
+| Fixture shape | Warm-up path (via the target's own tooling) |
+|---|---|
+| Error / issue id (`issue_id`, `event_id`) | Trigger a real event: `sentry-cli send-event`, the app's error-report endpoint, or an SDK `captureException`. Poll the list endpoint until the id appears, capture it. |
+| Uploaded-artifact id (`file_id`, `release`, `sourcemap`) | Upload via the provider CLI/SDK (`sentry-cli releases files upload`, a `POST .../files` multipart). Capture the returned id. |
+| Integration / connection id (`integration_id`, `installation_id`) | Install the app/integration into a **sandbox** org (OAuth flow / provider dashboard "add to test workspace"). Capture the id from the callback or the list endpoint. |
+| Delivered-webhook id (`delivery_id`, `webhook_event_id`) | Register a webhook, trigger the source event, replay/list deliveries, capture the id. |
+| Provisioned-async id (needs a background job to finish) | Kick off the job, poll the status endpoint until ready, capture. |
+
+These are *examples*, not a lookup table — read the actual provider's docs for
+the target you're on.
+
+## The loop
+
+For each un-seedable root:
+
+1. **Identify the warm-up path.** From `.api-resources.yaml` + the provider
+   docs, decide which real-world action mints this id. If it needs a human,
+   add it to the "needs you" list and move on.
+
+2. **Warm it via the target's own tooling.** Run the SDK/CLI/curl that creates
+   the real resource in the sandbox. Read the id from the response (or poll the
+   list endpoint until it shows up — async resources aren't instant).
+
+3. **Store the live id.**
+   ```bash
+   zond fixtures add --api <name> issue_id=<real-id-you-got> --validate --apply
+   ```
+   `--validate` GETs the read-by-id endpoint and confirms the id is `live`
+   before writing (so a warm-up that half-failed doesn't poison later runs).
+
+4. **Verify the gap closed.** Re-run `zond prepare-fixtures --api <name> --json`
+   — the warmed root should drop out of `unseededRoots` / flip off `miss-empty`.
+
+5. **Measure + hand back.** When the worklist is drained (or only "needs you"
+   items remain), snapshot honest-2xx again and report the delta, then hand
+   back to `zond` for the audit:
+   ```bash
+   zond coverage --api <name> --union session   # after — compare to the before snapshot
+   ```
+
+## Output to the user
+
+- **Warmed:** table of `fixture → how it was warmed → live id captured`.
+- **Needs you:** fixtures that require a human action, each with the exact step
+  (e.g. "enable the Slack integration in the sandbox workspace, then re-run").
+- **Coverage:** honest-2xx before → after, so the lift is measurable.
+
+Cleanup: DELETE the resources you created (or note they live in a disposable
+sandbox). Never leave test events/files/installs on a shared account.