@kirrosh/zond 0.22.0 → 0.26.0

package/src/cli/commands/discover.ts

@@ -0,0 +1,1356 @@
+/**
+ * `zond discover` — auto-fill `.env.yaml` from list-endpoints (TASK-136).
+ *
+ * Phase 2.5 of the audit flow used to be manual: `zond request GET /audiences`,
+ * pluck the slug, paste into `.env.yaml`, repeat for every FK. ~15 min per
+ * API. This command walks the resource map (`.api-resources.yaml`), hits
+ * every owner-resource list-endpoint with the user's auth token, extracts
+ * the first id, and proposes a diff. By default dry-run; `--apply` writes
+ * with a `.env.yaml.bak` backup.
+ *
+ * Scope (v1):
+ *  - Only list-endpoints with no path-params (collection-level GETs).
+ *  - Only FK vars whose owner is identified in `.api-resources.yaml`.
+ *  - Skips vars already present in `.env.yaml` unless their value is empty
+ *    or a `# TODO` placeholder.
+ */
+import { join } from "path";
+import { copyFile } from "fs/promises";
+import {
+  readOpenApiSpec,
+  extractEndpoints,
+  extractSecuritySchemes,
+} from "../../core/generator/index.ts";
+import { loadEnvFile } from "../../core/parser/variables.ts";
+import {
+  composeSpec,
+  type ComposedSpec,
+  type SpecLayer,
+} from "../../core/spec/layers.ts";
+import { liveAuthHeaders } from "../../core/probe/shared.ts";
+import { executeRequest } from "../../core/runner/http-client.ts";
+import { writeFixtureGaps, type FixtureGap } from "../../core/workspace/fixture-gaps.ts";
+import { reportFixtureGaps, type FixtureGapReport } from "../../core/workspace/fixture-gap-report.ts";
+import { parseSafe } from "../../core/parser/yaml-parser.ts";
+
+/** Strip a trailing FK-shape suffix (`_id`, `Id`, `_uuid`, `_slug`, `_name`,
+ *  `_code`) from a var name and return the stem. Used by ARV-69 to find an
+ *  owner resource when the resource map doesn't link the var to a list
+ *  endpoint explicitly (common-style {id} placeholders).
+ */
+function stemFromVarName(varName: string): string | null {
+  const lower = varName.toLowerCase();
+  for (const suffix of ["_id", "_uuid", "_slug", "_name", "_code"]) {
+    if (lower.endsWith(suffix)) return lower.slice(0, -suffix.length);
+  }
+  // CamelCase: `domainId` → `domain`.
+  const m = varName.match(/^(.+?)(Id|Uuid)$/);
+  if (m) return m[1]!.toLowerCase();
+  return null;
+}
+
+/** ARV-69 (feedback round-02 / F10): try to find a resource whose
+ *  list endpoint is a plausible source for `varName` based on the var's
+ *  name stem. Matches singular ↔ plural and is case-insensitive. Returns
+ *  the FkTarget on hit, undefined on miss.
+ */
+export function inferOwnerFromVarName(
+  varName: string,
+  map: ApiResourceMapYaml,
+): FkTarget | undefined {
+  const stem = stemFromVarName(varName);
+  if (!stem) return undefined;
+  const candidates = new Set([stem, `${stem}s`, stem.endsWith("s") ? stem.slice(0, -1) : stem]);
+  for (const r of map.resources) {
+    if (!r.endpoints?.list) continue;
+    const lower = r.resource.toLowerCase();
+    if (candidates.has(lower)) {
+      return { varName, ownerResource: r.resource, listLabel: r.endpoints.list };
+    }
+  }
+  return undefined;
+}
+
+/** Return the first object in a list-response (bare array or a `data`/`items`/
+ *  `results`/`records` envelope), or undefined. Distinguishes a non-empty
+ *  recognized list ("resource exists, agent must pick a value") from an
+ *  unrecognized shape. */
+function firstListItem(body: unknown): Record<string, unknown> | undefined {
+  const pick = (arr: unknown): Record<string, unknown> | undefined =>
+    Array.isArray(arr) && arr[0] && typeof arr[0] === "object"
+      ? (arr[0] as Record<string, unknown>)
+      : undefined;
+  if (Array.isArray(body)) return pick(body);
+  if (body && typeof body === "object") {
+    const obj = body as Record<string, unknown>;
+    for (const key of ["data", "items", "results", "records"]) {
+      const hit = pick(obj[key]);
+      if (hit) return hit;
+    }
+  }
+  return undefined;
+}
+
+/** True when the list-response is well-shaped but contains zero items.
+ *  Used to distinguish "no <entity> in target API yet — go create one"
+ *  from "response shape unrecognized" (TASK-273). */
+export function isEmptyListBody(body: unknown): boolean {
+  if (Array.isArray(body)) return body.length === 0;
+  if (body && typeof body === "object") {
+    const obj = body as Record<string, unknown>;
+    for (const key of ["data", "items", "results", "records"]) {
+      if (key in obj) {
+        const arr = obj[key];
+        return Array.isArray(arr) && arr.length === 0;
+      }
+    }
+  }
+  return false;
+}
+import { printError, printSuccess, printWarning } from "../output.ts";
+import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+import { getSecretRegistry } from "../../core/secrets/registry.ts";
+import type { EndpointInfo, SecuritySchemeInfo } from "../../core/generator/types.ts";
+import type { RecommendedAction } from "../../core/diagnostics/failure-hints.ts";
+
+export interface DiscoverOptions {
+  specPath: string;
+  /** Path to `apis/<name>/` — used to read .api-resources.yaml and write .env.yaml. */
+  apiDir: string;
+  /** Default `apis/<name>/.env.yaml`. */
+  envPath?: string;
+  apply?: boolean;
+  /** Per-request timeout (ms). */
+  timeoutMs?: number;
+  json?: boolean;
+  /** TASK-281: GET each fixture's read-by-id endpoint to classify live/stale/
+   *  unknown. Without `--apply` this is a read-only report; with `--apply` (or
+   *  the `--refresh` shortcut) stale fixtures are unset and re-resolved
+   *  through the normal discover flow. */
+  verify?: boolean;
+  /** ARV-205/F19 (R10/R13/R14): command name surfaced in the JSON envelope.
+   *  prepare-fixtures delegates here for the single-pass path; the envelope
+   *  should reflect the user-facing command, not the internal "discover". */
+  commandName?: string;
+}
+
+export interface FkTarget {
+  /** Env var name to fill (e.g. `audience_id`). */
+  varName: string;
+  /** Resource that owns the id (e.g. `audiences`). */
+  ownerResource: string;
+  /** List endpoint label, e.g. `GET /audiences`. */
+  listLabel: string;
+}
+
+export interface DiscoveryItem {
+  varName: string;
+  resource: string;
+  listPath: string;
+  /** What was found, if anything. */
+  discovered?: string;
+  /** What's currently in env (may be empty/placeholder). */
+  current?: string;
+  /** Gap/verify classification. ARV-362 (m-25): discover never harvests a
+   *  value — the write path is gone. Non-empty lists surface as
+   *  `miss-needs-value` (resource exists, agent picks); everything else is a
+   *  verify state or a miss-* gap. */
+  status:
+    | "skip-already-set"
+    | "skip-not-required"
+    | "miss-no-list"
+    | "miss-nested-list"
+    | "miss-no-owner"
+    | "miss-network"
+    | "miss-status"
+    | "miss-empty"
+    | "miss-no-id"
+    // ARV-362: got a non-empty list, but which record/field fills the slot is
+    // the agent's call (ARV-334 lived here). discover reports the gap.
+    | "miss-needs-value"
+    // TASK-281 verify-mode states
+    | "verify-live"
+    | "verify-stale"
+    | "verify-unknown"
+    | "verify-no-read"
+    | "verify-skip-empty"
+    // ARV-143: filled var classified as trusted user input — manifest source
+    // is user-config (auth/server/header) or there's no read-by-id endpoint
+    // for its resource. Refresh has no verification path, so we mark it as
+    // such instead of silently omitting (the doctor view that says set:true).
+    | "verify-user-config";
+  /** ARV-46: manifest-grade status enum projected onto agent-readable
+   *  envelope. Filled when discover ran in manifest-driven mode.
+   *  filled | failed:no-list-endpoint | failed:list-empty | failed:miss-network
+   *  | skipped:already-set | skipped:not-required */
+  manifestStatus?: ManifestStatus;
+  /** ARV-46: source classification copied from `.api-fixtures.yaml`. */
+  manifestSource?: FixtureManifestEntry["source"];
+  reason?: string;
+  /** ARV-382: when zond can't CONFIDENTLY derive the owner list endpoint
+   *  (miss-no-list), it surfaces the plausible GET/list endpoints — ranked by
+   *  structural proximity to where the id is consumed — instead of dead-ending.
+   *  zond does NOT pick a value; the agent reads these, picks one, and sets the
+   *  fixture (or fires one `zond request` against the top candidate). Empty
+   *  when nothing structurally plausible exists. */
+  candidates?: string[];
+  /** TASK-294: agent-routable action for items the user must fix.
+   *  miss-* / verify-stale / verify-unknown → `fix_fixture`.
+   *  miss-network → `fix_network_config`.
+   *  skip-* / verify-live → undefined. */
+  recommended_action?: RecommendedAction;
+  /** ARV-362: set when --refresh drops (unsets) a stale fixture. Marks which
+   *  vars to unset on disk and feeds the summary `dropped` count. */
+  wasStale?: boolean;
+}
+
+/** TASK-294: derive recommended_action from a DiscoveryItem's status. */
+export function discoveryAction(status: DiscoveryItem["status"]): RecommendedAction | undefined {
+  if (status === "miss-network") return "fix_network_config";
+  if (status.startsWith("miss-") || status === "verify-stale" || status === "verify-unknown") {
+    return "fix_fixture";
+  }
+  return undefined;
+}
+
+/** ARV-46: stable manifest-grade status enum for agent consumers. The CLI
+ *  prints this column when discover runs in manifest-driven mode and it's
+ *  exposed verbatim in the JSON envelope. */
+export type ManifestStatus =
+  | "failed:no-list-endpoint"
+  | "failed:list-empty"
+  | "failed:needs-value"
+  | "failed:miss-network"
+  | "skipped:already-set"
+  | "skipped:not-required";
+
+export function toManifestStatus(status: DiscoveryItem["status"]): ManifestStatus {
+  switch (status) {
+    case "skip-already-set":
+      return "skipped:already-set";
+    case "skip-not-required":
+      return "skipped:not-required";
+    case "miss-network":
+      return "failed:miss-network";
+    case "miss-empty":
+      return "failed:list-empty";
+    // ARV-362: list has records but discover won't pick — the agent fills it.
+    case "miss-needs-value":
+      return "failed:needs-value";
+    // miss-no-list / miss-nested-list / miss-no-owner / miss-status / miss-no-id —
+    // the underlying cause is "we have no usable list endpoint to read from", so
+    // they collapse onto the same manifest-level bucket.
+    default:
+      return "failed:no-list-endpoint";
+  }
+}
+
+/** ARV-324: project confirmed-empty/inaccessible/needs-value list-probes into
+ *  the `.fixture-gaps.yaml` shape. `miss-status` (list endpoint rejected the
+ *  request), `miss-empty` (200 with an empty collection) and `miss-needs-value`
+ *  (ARV-362: 200 with records the agent must pick from) all carry an actual
+ *  observed response worth cross-referencing against a later `checks run` —
+ *  the other miss-* statuses mean "we never even sent a request" (no list
+ *  endpoint / no owner resource). De-dupes by (method, path); a later pass's
+ *  entry for the same var wins. */
+export function gapsFromItems(items: DiscoveryItem[]): FixtureGap[] {
+  const byKey = new Map<string, FixtureGap>();
+  for (const item of items) {
+    if (
+      item.status !== "miss-status" &&
+      item.status !== "miss-empty" &&
+      item.status !== "miss-needs-value"
+    ) continue;
+    if (!item.listPath) continue;
+    byKey.set(`GET ${item.listPath}`, {
+      method: "GET",
+      path: item.listPath,
+      resource: item.resource,
+      var: item.varName,
+      reason: item.reason ?? item.status,
+    });
+  }
+  return [...byKey.values()];
+}
+
+export function isPlaceholder(value: string | undefined): boolean {
+  if (!value) return true;
+  const trimmed = value.trim();
+  if (trimmed === "") return true;
+  // `var: ""  # TODO: fill in` lands as "" after YAML parse.
+  if (/^TODO/i.test(trimmed)) return true;
+  return false;
+}
+
+function parseEndpointLabel(label: string): { method: string; path: string } | null {
+  const parts = label.trim().split(/\s+/);
+  if (parts.length < 2) return null;
+  return { method: parts[0]!.toUpperCase(), path: parts[1]! };
+}
+
+export interface ResourceYaml {
+  resource: string;
+  basePath: string;
+  itemPath: string;
+  idParam: string;
+  captureField?: string;
+  hasFullCrud?: boolean;
+  endpoints: { list?: string; create?: string; read?: string; update?: string; delete?: string };
+  fkDependencies: Array<{ var: string; param: string; in: "path" | "body"; ownerResource: string | null }>;
+  /** ARV-169: optional POST→GET drift overrides. snake_case to match
+   *  yaml on disk; loaders preserve as-is so the check can read it. */
+  readback_diff?: {
+    ignore_fields?: string[];
+    write_to_read_map?: Record<string, string>;
+  };
+  /** ARV-170: opt-in idempotency-replay probe for this resource's
+   *  create endpoint. */
+  idempotency?: {
+    header?: string;
+    scope?: "endpoint" | "global";
+    ignore_response_fields?: string[];
+  };
+  /** ARV-171: pagination-invariants probe for this resource's list
+   *  endpoint. */
+  pagination?: {
+    type?: "cursor" | "page" | "offset" | "token";
+    cursor_param?: string;
+    cursor_field?: string;
+    has_more_field?: string;
+    limit_param?: string;
+    default_limit?: number;
+    items_field?: string;
+    page_param?: string;
+    start_page?: number;
+  };
+  /** ARV-172: per-resource state machine + action endpoints. */
+  lifecycle?: {
+    field: string;
+    states: string[];
+    transitions: Array<{ from: string; to: string[] }>;
+    actions: Record<string, {
+      endpoint: string;
+      expected_state: string;
+      body?: Record<string, unknown>;
+    }>;
+  };
+  /** ARV-187: LLM-authored example POST body for stateful checks that
+   *  need a valid create payload. When present, stateful CRUD checks
+   *  (cross_call_references, idempotency_replay, lifecycle_transitions,
+   *  ensure_resource_availability, use_after_free) prefer this over
+   *  `generateFromSchema(create.requestBodySchema)`. The fallback path
+   *  stays — yaml is purely additive. `content_type` defaults to the
+   *  create endpoint's `requestBodyContentType`. */
+  seed_body?: {
+    content_type?: string;
+    body: Record<string, unknown>;
+  };
+}
+
+export interface ApiResourceMapYaml {
+  resources: ResourceYaml[];
+}
+
+/** ARV-122 layer ids — exported so downstream code (doctor, future
+ *  catalog --provenance) can compare against the provenance map
+ *  without re-typing the strings. */
+export const RESOURCE_LAYER_UPSTREAM = "upstream";
+export const RESOURCE_LAYER_EXTENSION = "extension";
+
+/** ARV-122: build the two-layer SpecLayer set for an API's resource
+ *  map. Kept here (and not in `core/spec/layers.ts`) so the YAML
+ *  loaders stay co-located with the schema types they parse. */
+function buildResourceLayers(apiDir: string): SpecLayer<ResourceYaml>[] {
+  return [
+    {
+      id: RESOURCE_LAYER_UPSTREAM,
+      path: join(apiDir, ".api-resources.yaml"),
+      precedence: 10,
+      scope: "resources",
+      mergePolicy: "override",
+      load: async () => {
+        const file = Bun.file(join(apiDir, ".api-resources.yaml"));
+        if (!(await file.exists())) return [];
+        const parsed = Bun.YAML.parse(await file.text());
+        if (!parsed || typeof parsed !== "object") return [];
+        return (parsed as { resources?: ResourceYaml[] }).resources ?? [];
+      },
+    },
+    {
+      id: RESOURCE_LAYER_EXTENSION,
+      path: join(apiDir, ".api-resources.local.yaml"),
+      precedence: 20,
+      scope: "resources",
+      mergePolicy: "override",
+      load: () => readResourceExtensions(apiDir),
+    },
+  ];
+}
+
+/** ARV-122: compose the resource map through the SpecLayer pipeline,
+ *  exposing the provenance map for callers that need to know which
+ *  layer contributed a given resource (doctor diagnostics, m-18 CLI
+ *  surface). `readResourceMap` keeps the legacy shape for callers
+ *  that don't care. */
+export async function composeResourceMap(
+  apiDir: string,
+): Promise<ComposedSpec<ResourceYaml>> {
+  return composeSpec(buildResourceLayers(apiDir), (r) => r.resource);
+}
+
+export async function readResourceMap(apiDir: string): Promise<ApiResourceMapYaml | null> {
+  // Old contract: return null when the upstream `.api-resources.yaml`
+  // is missing (callers branch on this to surface a setup error). The
+  // SpecLayer pipeline returns an empty list in that case, so check
+  // existence explicitly to preserve behaviour.
+  const upstream = Bun.file(join(apiDir, ".api-resources.yaml"));
+  if (!(await upstream.exists())) return null;
+
+  // ARV-122: route the merge through composeSpec. Behaviour is
+  // identical to the previous ad-hoc Map merge — extension wins on
+  // name collision (precedence 20 > 10, mergePolicy: "override") —
+  // and the same path also feeds provenance into composeResourceMap.
+  const composed = await composeResourceMap(apiDir);
+  // ARV-169: field-level overlay for adding readback_diff / idempotency
+  // / pagination / lifecycle without re-declaring the whole entry.
+  const patches = await readResourcePatches(apiDir);
+  return { resources: applyResourcePatches(composed.entries, patches) };
+}
+
+/** ARV-111: read `apis/<name>/.api-resources.local.yaml`. Same `resources:`
+ *  shape as the main file (top-level `extensions:` key is the only
+ *  difference, so the user can recognise it as a sibling). Returns [] when
+ *  missing or empty so the merge path stays simple. */
+export async function readResourceExtensions(apiDir: string): Promise<ResourceYaml[]> {
+  const path = join(apiDir, ".api-resources.local.yaml");
+  const file = Bun.file(path);
+  if (!(await file.exists())) return [];
+  const text = await file.text();
+  const parsed = Bun.YAML.parse(text);
+  if (!parsed || typeof parsed !== "object") return [];
+  const obj = parsed as { extensions?: ResourceYaml[] };
+  return obj.extensions ?? [];
+}
+
+/** ARV-169 (m-20): partial overlay for adding fields (readback_diff,
+ *  future idempotency / pagination / lifecycle) to an existing
+ *  resource entry without re-declaring its CRUD wiring. Lives in the
+ *  same `.api-resources.local.yaml` under top-level `patches:`. Each
+ *  entry MUST carry `resource:` (the merge key); any other declared
+ *  field overlays the upstream value, leaving omitted fields intact.
+ *
+ *  Unlike `extensions:` (full replacement, ARV-111) this is field-
+ *  level merge. Both can coexist in the same file. Returns [] when
+ *  the file is missing or carries no `patches:` key. */
+export async function readResourcePatches(apiDir: string): Promise<Array<Partial<ResourceYaml> & { resource: string }>> {
+  const path = join(apiDir, ".api-resources.local.yaml");
+  const file = Bun.file(path);
+  if (!(await file.exists())) return [];
+  const text = await file.text();
+  const parsed = Bun.YAML.parse(text);
+  if (!parsed || typeof parsed !== "object") return [];
+  const obj = parsed as { patches?: Array<Partial<ResourceYaml> & { resource?: string }> };
+  const raw = obj.patches ?? [];
+  return raw.filter((p): p is Partial<ResourceYaml> & { resource: string } =>
+    typeof p?.resource === "string" && p.resource.length > 0,
+  );
+}
+
+/** ARV-169: apply partial patches over a composed resource list.
+ *  Patch fields overwrite matching upstream fields; absent fields
+ *  are preserved. Patches whose `resource` doesn't match anything
+ *  upstream are dropped silently — callers wanting to ADD a whole
+ *  resource use `extensions:` instead. */
+function applyResourcePatches(
+  resources: ResourceYaml[],
+  patches: Array<Partial<ResourceYaml> & { resource: string }>,
+): ResourceYaml[] {
+  if (patches.length === 0) return resources;
+  const byName = new Map(resources.map((r) => [r.resource, r] as const));
+  for (const p of patches) {
+    const upstream = byName.get(p.resource);
+    if (!upstream) continue;
+    byName.set(p.resource, { ...upstream, ...p });
+  }
+  return resources.map((r) => byName.get(r.resource) ?? r);
+}
+
+export interface FixtureManifestEntry {
+  name: string;
+  source: "auth" | "server" | "path" | "header" | "body-fk" | "capture-chain";
+  required: boolean;
+  description?: string;
+  defaultValue?: string;
+  affectedEndpoints?: string[];
+}
+
+export interface FixtureManifestYaml {
+  fixtures: FixtureManifestEntry[];
+}
+
+/** Read `.api-fixtures.yaml`. Returns null when missing — caller falls back
+ *  to the legacy resource-map-driven path. */
+export async function readFixtureManifest(apiDir: string): Promise<FixtureManifestYaml | null> {
+  const path = join(apiDir, ".api-fixtures.yaml");
+  const file = Bun.file(path);
+  if (!(await file.exists())) return null;
+  const text = await file.text();
+  const parsed = Bun.YAML.parse(text);
+  if (!parsed || typeof parsed !== "object") return null;
+  const obj = parsed as { fixtures?: FixtureManifestEntry[] };
+  return { fixtures: obj.fixtures ?? [] };
+}
+
+/** Build the unique target list from FK deps. Each FK var = one discovery
+ *  attempt (we hit the owner's list endpoint once and reuse the result).
+ *
+ *  ARV-133: also include each resource's own idParam (when it has a list
+ *  endpoint) — these are root-level required path-params with no fkDep edge
+ *  to another resource, but they're trivially harvestable from the resource's
+ *  own list endpoint. Without this, cascade silently skipped vars like
+ *  `domain_id`, `webhook_id`, `template_id` even though `/domains`,
+ *  `/webhooks`, `/templates` returned live data. Optional `manifest`
+ *  parameter wires manifest-required path/body-fk vars onto a list endpoint
+ *  via `inferOwnerFromVarName` (singular ↔ plural matching) so vars whose
+ *  name doesn't appear in the resource map's idParam table still get
+ *  attempted. */
+/** ARV-382: for a fixture var that resolved to no confident owner list
+ *  endpoint, surface the structurally-plausible GET/list endpoints instead of
+ *  dead-ending. We walk back from each `{param}` segment in the endpoints the
+ *  var affects and collect any GET whose path is that collection prefix (or
+ *  prefix + a list verb), ranked by proximity (deeper prefix = closer). This
+ *  is deterministic candidate EVIDENCE — zond does not pick a value or a
+ *  winner; the agent judges. Reuses the existing list-verb set (no new
+ *  markers). Returns [] when nothing plausible exists. */
+export function findCandidateListEndpoints(
+  affectedLabels: string[],
+  endpoints: Array<{ method: string; path: string; deprecated?: boolean }>,
+): string[] {
+  const strip = (p: string) => (p.length > 1 && p.endsWith("/") ? p.slice(0, -1) : p);
+  const isParam = (s: string | undefined) => !!s && /^\{[^}]+\}$/.test(s);
+  // Prefer live endpoints; still surface a deprecated-only list (marked) so the
+  // agent — not zond — decides whether an EOL read is acceptable to seed an id.
+  const getByPath = new Map<string, { label: string; deprecated: boolean }>();
+  for (const e of endpoints) {
+    if (e.method.toUpperCase() !== "GET") continue;
+    const key = strip(e.path);
+    const entry = { label: `${e.method.toUpperCase()} ${e.path}`, deprecated: !!e.deprecated };
+    const prev = getByPath.get(key);
+    if (!prev || (prev.deprecated && !entry.deprecated)) getByPath.set(key, entry); // live wins
+  }
+  const VERBS = ["", "/list", "/search", "/find"];
+  const scored = new Map<string, number>();
+  const consider = (label: string, score: number) => {
+    if ((scored.get(label) ?? -1) < score) scored.set(label, score);
+  };
+  for (const label of affectedLabels) {
+    const path = label.slice(label.indexOf(" ") + 1);
+    const segs = strip(path).split("/");
+    for (let i = 0; i < segs.length; i++) {
+      if (!isParam(segs[i])) continue;
+      // Walk back over the run of non-param segments before this param.
+      for (let k = i; k >= 1; k--) {
+        if (isParam(segs[k - 1])) break;
+        const prefix = segs.slice(0, k).join("/");
+        if (prefix.includes("{")) continue; // an inner param — not a concrete GET path
+        for (const v of VERBS) {
+          const hit = getByPath.get(prefix + v);
+          if (!hit) continue;
+          // deeper prefix = closer; deprecated candidates rank below all live.
+          consider(hit.deprecated ? `${hit.label} (deprecated)` : hit.label, (hit.deprecated ? 0 : 1000) + k);
+        }
+      }
+    }
+  }
+  return [...scored.entries()].sort((a, b) => b[1] - a[1]).map((e) => e[0]).slice(0, 5);
+}
+
+export function collectTargets(
+  map: ApiResourceMapYaml,
+  manifest?: FixtureManifestYaml,
+): FkTarget[] {
+  const seen = new Set<string>();
+  const out: FkTarget[] = [];
+  const push = (t: FkTarget): void => {
+    if (seen.has(t.varName)) return;
+    seen.add(t.varName);
+    out.push(t);
+  };
+
+  // 1. fkDeps — parent-id edges declared by resource-builder.
+  for (const r of map.resources) {
+    for (const dep of r.fkDependencies ?? []) {
+      if (dep.in !== "path") continue;
+      if (!dep.ownerResource) continue;
+      const owner = map.resources.find(x => x.resource === dep.ownerResource);
+      const listLabel = owner?.endpoints.list ?? "";
+      push({ varName: dep.var, ownerResource: dep.ownerResource, listLabel });
+    }
+  }
+
+  // 2. Each resource's own idParam → its own list endpoint. resource-builder's
+  //    collectPathFkDeps skips this case (it emits only *parent* FKs), so
+  //    without an explicit pass `domain_id`/`webhook_id`/etc. drop out of
+  //    cascade entirely.
+  for (const r of map.resources) {
+    if (!r.idParam) continue;
+    if (!r.endpoints?.list) continue;
+    push({ varName: r.idParam, ownerResource: r.resource, listLabel: r.endpoints.list });
+  }
+
+  // 3. Manifest-required vars (path / body-fk) whose name doesn't match any
+  //    fkDep edge or resource idParam. Use singular↔plural stemming to find
+  //    an owner — same logic as the discover-via-manifest path uses (ARV-69).
+  if (manifest) {
+    for (const entry of manifest.fixtures) {
+      if (!entry.required) continue;
+      if (entry.source !== "path" && entry.source !== "body-fk") continue;
+      if (seen.has(entry.name)) continue;
+      const inferred = inferOwnerFromVarName(entry.name, map);
+      if (inferred) push(inferred);
+    }
+  }
+
+  return out;
+}
+
+export async function probeOne(
+  target: FkTarget,
+  current: string | undefined,
+  endpoints: EndpointInfo[],
+  schemes: SecuritySchemeInfo[],
+  vars: Record<string, string>,
+  baseUrl: string,
+  timeoutMs: number,
+): Promise<DiscoveryItem> {
+  const item: DiscoveryItem = {
+    varName: target.varName,
+    resource: target.ownerResource,
+    listPath: "",
+    current,
+    status: "miss-no-list",
+  };
+  if (!target.listLabel) {
+    item.status = "miss-no-list";
+    item.reason = `resource "${target.ownerResource}" has no list endpoint in .api-resources.yaml`;
+    return item;
+  }
+  const parsed = parseEndpointLabel(target.listLabel);
+  if (!parsed) {
+    item.status = "miss-no-list";
+    item.reason = `cannot parse endpoint label "${target.listLabel}"`;
+    return item;
+  }
+  if (parsed.method !== "GET") {
+    item.status = "miss-no-list";
+    item.reason = `expected GET for list of ${target.ownerResource}, got ${parsed.method}`;
+    return item;
+  }
+  // For nested list paths (e.g. /orgs/{org}/projects/), substitute any
+  // parent path-params that are already known in vars. If all params resolve,
+  // proceed as a normal list call. Only bail if a param is still missing.
+  let effectivePath = parsed.path;
+  if (parsed.path.includes("{")) {
+    effectivePath = parsed.path.replace(/\{([^}]+)\}/g, (_, name: string) => {
+      const val = vars[name];
+      return typeof val === "string" && val ? val : `{${name}}`;
+    });
+    if (effectivePath.includes("{")) {
+      item.status = "miss-nested-list";
+      item.reason = `nested collection (${parsed.path}) — missing parent fixture(s) in .env.yaml`;
+      return item;
+    }
+  }
+  item.listPath = effectivePath;
+
+  // Already filled and not a placeholder → skip the call (live API, save it).
+  if (!isPlaceholder(current)) {
+    item.status = "skip-already-set";
+    return item;
+  }
+
+  const listEp = endpoints.find(
+    e => e.method.toUpperCase() === "GET" && e.path === parsed.path && !e.deprecated,
+  );
+  if (!listEp) {
+    item.status = "miss-no-list";
+    item.reason = `${parsed.path} not found in spec endpoints (resource map drift?)`;
+    return item;
+  }
+
+  const url = `${baseUrl.replace(/\/+$/, "")}${effectivePath}`;
+  const headers: Record<string, string> = {
+    accept: "application/json",
+    ...liveAuthHeaders(listEp, schemes, vars),
+  };
+
+  let resp;
+  try {
+    // ARV-48: 1 network-class retry with exp+jitter backoff. Transient
+    // DNS/connection-reset blips on shared CI runners must not cost the
+    // user a whole prepare-fixtures rerun. Only network errors retry —
+    // 4xx/5xx HTTP statuses keep their existing branches (miss-status).
+    resp = await executeRequest(
+      { method: "GET", url, headers },
+      { timeout: timeoutMs, retries: 0, network_retries: 1 },
+    );
+  } catch (err) {
+    item.status = "miss-network";
+    item.reason = `network error: ${err instanceof Error ? err.message : String(err)}`;
+    return item;
+  }
+  if (resp.status < 200 || resp.status >= 300) {
+    item.status = "miss-status";
+    // ARV-99: bare `METHOD path → status` leaves the agent guessing what
+    // to do. Append a status-specific next-step hint so 404 / 401 / 403 /
+    // 5xx each get a routed action. Spec drift (404) and token scope
+    // (401/403) are the two common root causes — call them out.
+    let hint = "";
+    if (resp.status === 404) {
+      hint =
+        ` — list endpoint 404'd. Spec may have a stale path. Try \`zond refresh-api <name>\` to re-sync; ` +
+        `if the path is correct, the API likely doesn't expose this resource for your token — add the var to ` +
+        `.api-resources.local.yaml as a custom create endpoint (extension overlay) or fill .env.yaml by hand`;
+    } else if (resp.status === 401 || resp.status === 403) {
+      hint =
+        ` — auth/scope rejection on the list endpoint. Check token scope; if the token genuinely cannot list ${target.ownerResource}, ` +
+        `fill .env.yaml by hand or rerun with \`--no-seed\` to skip futile attempts`;
+    } else if (resp.status >= 500) {
+      hint = ` — server-side error; retry later or check provider status before treating this as a fixture gap`;
+    }
+    item.reason = `${parsed.method} ${parsed.path} → ${resp.status}${hint}`;
+    return item;
+  }
+  // ARV-362 (m-25): discover no longer harvests a value from the list —
+  // which record/field fills the slot is the agent's call (ARV-334 lived in
+  // that guess). We only classify the gap so the agent knows the next step.
+  const respBody = resp.body_parsed ?? resp.body;
+  if (isEmptyListBody(respBody)) {
+    // TASK-273: empty target API — nothing to pick. Point the agent at
+    // creating the resource first.
+    item.status = "miss-empty";
+    item.reason =
+      `no ${target.ownerResource} in target API — create the resource yourself ` +
+      `(in the product UI or via API), then set its id in .env.yaml (or run ` +
+      `\`zond fixtures add\`) and re-run \`zond prepare-fixtures --api <name>\``;
+    return item;
+  }
+  if (!firstListItem(respBody)) {
+    item.status = "miss-no-id";
+    item.reason = `response shape unrecognized (no array/data/items/results/records field)`;
+    return item;
+  }
+  // Non-empty recognized list: the resource exists, but discover won't choose
+  // a record/field — the agent picks and fills .env.yaml by hand.
+  item.status = "miss-needs-value";
+  item.reason =
+    `${target.ownerResource} list has records but discover won't choose one — ` +
+    `pick a value and set {${target.varName}} in .env.yaml (or run \`zond fixtures add\`), ` +
+    `then re-run \`zond prepare-fixtures --api <name>\``;
+  return item;
+}
+
+/** TASK-281: GET <ownerResource>'s read-by-id endpoint with the current
+ *  fixture value and classify the result. 5xx is treated as `unknown` (don't
+ *  trash valid fixtures over a flaky API). */
+export async function verifyOne(
+  target: FkTarget,
+  current: string | undefined,
+  ownerResource: ResourceYaml | undefined,
+  endpoints: EndpointInfo[],
+  schemes: SecuritySchemeInfo[],
+  vars: Record<string, string>,
+  baseUrl: string,
+  timeoutMs: number,
+): Promise<DiscoveryItem> {
+  const item: DiscoveryItem = {
+    varName: target.varName,
+    resource: target.ownerResource,
+    listPath: "",
+    current,
+    status: "verify-unknown",
+  };
+  if (isPlaceholder(current)) {
+    item.status = "verify-skip-empty";
+    item.reason = "fixture is empty/placeholder — nothing to verify";
+    return item;
+  }
+  if (!ownerResource?.endpoints?.read) {
+    item.status = "verify-no-read";
+    item.reason = `resource "${target.ownerResource}" has no read-by-id endpoint in .api-resources.yaml`;
+    return item;
+  }
+  const parsed = parseEndpointLabel(ownerResource.endpoints.read);
+  if (!parsed) {
+    item.status = "verify-no-read";
+    item.reason = `cannot parse read endpoint label "${ownerResource.endpoints.read}"`;
+    return item;
+  }
+  // Substitute parent path-params from env vars; the resource's own idParam is
+  // taken from `current` (we are verifying that very value).
+  const idParam = ownerResource.idParam;
+  let effectivePath = parsed.path.replace(/\{([^}]+)\}/g, (_, name: string) => {
+    if (name === idParam) return current!;
+    const val = vars[name];
+    return typeof val === "string" && val ? val : `{${name}}`;
+  });
+  if (effectivePath.includes("{")) {
+    item.status = "verify-unknown";
+    item.reason = `cannot resolve parent path-params for ${parsed.path}`;
+    return item;
+  }
+  item.listPath = effectivePath;
+
+  const ep = endpoints.find(
+    e => e.method.toUpperCase() === "GET" && e.path === parsed.path && !e.deprecated,
+  );
+  const url = `${baseUrl.replace(/\/+$/, "")}${effectivePath}`;
+  const headers: Record<string, string> = {
+    accept: "application/json",
+    ...(ep ? liveAuthHeaders(ep, schemes, vars) : {}),
+  };
+  let resp;
+  try {
+    // ARV-48: same single network-class retry as the discover probe.
+    resp = await executeRequest({ method: "GET", url, headers }, { timeout: timeoutMs, retries: 0, network_retries: 1 });
+  } catch (err) {
+    item.status = "verify-unknown";
+    item.reason = `network error: ${err instanceof Error ? err.message : String(err)}`;
+    return item;
+  }
+  if (resp.status >= 200 && resp.status < 300) {
+    item.status = "verify-live";
+    item.discovered = current;
+    return item;
+  }
+  if (resp.status === 404 || resp.status === 410) {
+    item.status = "verify-stale";
+    item.reason = `${parsed.method} ${effectivePath} → ${resp.status}`;
+    return item;
+  }
+  // 401/403 — token/scope issue, not a stale id; 5xx — flake; treat both as
+  // unknown so we never delete a fixture on shaky evidence.
+  item.status = "verify-unknown";
+  item.reason = `${parsed.method} ${effectivePath} → ${resp.status}`;
+  return item;
+}
+
+/** Append-or-update a key in YAML text. Conservative: matches `<key>:` at
+ *  the start of a line and rewrites the value, preserving trailing comments
+ *  that documented original placeholders. */
+export function upsertEnvLine(yamlText: string, key: string, value: string): string {
+  const lines = yamlText.split("\n");
+  const re = new RegExp(`^${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*:`);
+  const idx = lines.findIndex(l => re.test(l));
+  const newLine = `${key}: ${JSON.stringify(value)}`;
+  if (idx === -1) {
+    // Insert before final newline if file ends with one, otherwise append.
+    if (lines[lines.length - 1] === "") {
+      lines.splice(lines.length - 1, 0, newLine);
+    } else {
+      lines.push(newLine);
+    }
+  } else {
+    lines[idx] = newLine;
+  }
+  return lines.join("\n");
+}
+
+/** First 8 `{{var}}` names + "… and N more" — keeps the gap warning readable
+ *  when a barely-provisioned account leaves dozens of required fixtures empty. */
+function capNames(names: string[], max = 8): string {
+  const head = names.slice(0, max).map(n => `{{${n}}}`).join(", ");
+  return names.length > max ? `${head}, … and ${names.length - max} more` : head;
+}
+
+export async function discoverCommand(options: DiscoverOptions): Promise<number> {
+  const commandName = options.commandName ?? "discover";
+  try {
+    const doc = await readOpenApiSpec(options.specPath);
+    const endpoints = extractEndpoints(doc);
+    const securitySchemes = extractSecuritySchemes(doc);
+
+    const resourceMap = await readResourceMap(options.apiDir);
+    if (!resourceMap || resourceMap.resources.length === 0) {
+      const msg = `No .api-resources.yaml in ${options.apiDir}. Run 'zond refresh-api <name>' to (re)build it.`;
+      if (options.json) printJson(jsonError(commandName, [msg]));
+      else printError(msg);
+      return 2;
+    }
+
+    const envPath = options.envPath ?? join(options.apiDir, ".env.yaml");
+    const env = (await loadEnvFile(envPath)) ?? {};
+    // ARV-143 follow-up (security regression fix): register every loaded var
+    // with the SecretRegistry so the user-config bucket (and any other path
+    // that incidentally echoes a value) can't leak `.secrets.yaml`-resolved
+    // tokens to stdout / scrollback / tee. base_url is filtered out because
+    // we have to print it verbatim in the discovery header.
+    {
+      const reg = getSecretRegistry();
+      for (const [k, v] of Object.entries(env)) {
+        if (k === "base_url") continue;
+        reg.register(k, v);
+      }
+    }
+    const baseUrl = env["base_url"];
+    if (!baseUrl) {
+      const msg = `base_url is required in ${envPath} (live API calls need it).`;
+      if (options.json) printJson(jsonError(commandName, [msg]));
+      else printError(msg);
+      return 2;
+    }
+
+    // ARV-46: manifest is the source-of-truth for the *list* of variables
+    // this API needs (per decision-7). When `.api-fixtures.yaml` exists,
+    // discover iterates it instead of `.env.yaml` keys / FK deps directly,
+    // so vars present in tests but absent from FK deps still show up in the
+    // status table — and env keys without a manifest entry surface as a
+    // warning instead of being silently ignored.
+    const manifest = await readFixtureManifest(options.apiDir);
+
+    const targets = collectTargets(resourceMap);
+    if (targets.length === 0 && !manifest) {
+      if (options.json) {
+        printJson(jsonOk(commandName, { items: [], message: "No path-FK dependencies with known owner resources." }));
+      } else {
+        console.log("No path-FK dependencies with known owner resources — nothing to discover.");
+      }
+      return 0;
+    }
+    // Index targets by var name so manifest entries can resolve their owner
+    // resource via the FK chain (manifest knows *what*, resource map knows
+    // *where to fetch*).
+    const targetsByVar = new Map<string, FkTarget>();
+    for (const t of targets) targetsByVar.set(t.varName, t);
+    // Resource map's `collectPathFkDeps` skips the resource's own idParam —
+    // it only emits *parent* FKs. The manifest legitimately wants discover
+    // to fill `api_key_id` (idParam of /api-keys/{api_key_id}) from the list
+    // endpoint /api-keys, so wire each resource's own idParam onto its list
+    // endpoint here. This is what makes "discover walks the manifest" not
+    // collapse 80% of entries into failed:no-list-endpoint.
+    for (const r of resourceMap.resources) {
+      if (!r.idParam || !r.endpoints?.list) continue;
+      if (targetsByVar.has(r.idParam)) continue;
+      targetsByVar.set(r.idParam, {
+        varName: r.idParam,
+        ownerResource: r.resource,
+        listLabel: r.endpoints.list,
+      });
+    }
+
+    // TASK-281: --verify mode — GET the read-by-id endpoint for every fixture
+    // and classify (live / stale / unknown). Without --apply this is purely
+    // diagnostic; with --apply we unset stale entries and re-resolve them via
+    // the regular discover flow below.
+    const items: DiscoveryItem[] = [];
+    if (options.verify) {
+      for (const target of targets) {
+        const owner = resourceMap.resources.find(r => r.resource === target.ownerResource);
+        const item = await verifyOne(
+          target,
+          env[target.varName],
+          owner,
+          endpoints,
+          securitySchemes,
+          env,
+          baseUrl,
+          options.timeoutMs ?? 30000,
+        );
+        items.push(item);
+      }
+
+      // ARV-362 (m-25): --refresh drops the known-bad stale id (unsets it in
+      // .env.yaml, disk-write below) so the var resurfaces as a gap. discover
+      // no longer re-resolves a replacement value — the agent picks the new
+      // one. `wasStale` marks which vars to unset on disk.
+      if (options.apply) {
+        for (const item of items) {
+          if (item.status === "verify-stale") {
+            delete env[item.varName];
+            item.wasStale = true;
+          }
+        }
+      }
+
+      // ARV-143: surface filled vars that verify can't validate so the user
+      // doesn't think they're missing. Two buckets:
+      //   1. manifest user-config sources (auth / server / header) — never
+      //      had a read endpoint, refresh just trusts the value.
+      //   2. targets whose verifyOne returned verify-no-read (resource exists
+      //      but `.api-resources.yaml` has no read endpoint) — same story.
+      // Without this, refresh emitted "0 stale" + silence on these vars,
+      // contradicting doctor's set:true reporting (feedback-02 F12).
+      if (manifest) {
+        const seen = new Set(items.map(i => i.varName));
+        for (const entry of manifest.fixtures) {
+          if (seen.has(entry.name)) continue;
+          const current = env[entry.name];
+          if (!current || isPlaceholder(current)) continue;
+          const isUserConfig =
+            entry.source === "auth" ||
+            entry.source === "server" ||
+            entry.source === "header";
+          if (!isUserConfig) continue;
+          items.push({
+            varName: entry.name,
+            resource: "",
+            listPath: "",
+            current,
+            status: "verify-user-config",
+            manifestSource: entry.source,
+            reason: `${entry.source} var — no verification path, value trusted from .env.yaml`,
+          });
+        }
+        // Promote verify-no-read items with a filled value to the same bucket
+        // so they show up under "trusted user input" in the summary instead of
+        // being lumped with empty/skip items.
+        for (const item of items) {
+          if (item.status === "verify-no-read" && item.current && !isPlaceholder(item.current)) {
+            item.status = "verify-user-config";
+            item.reason = `no read-by-id endpoint in .api-resources.yaml — value trusted from .env.yaml`;
+          }
+        }
+      }
+    } else if (manifest) {
+      // ARV-46: drive the loop by manifest entries (one row per entry).
+      // Each entry's status maps onto the manifest-grade enum so agents
+      // get a stable contract independent of the underlying probe shape.
+      for (const entry of manifest.fixtures) {
+        const current = env[entry.name];
+        const placeholder: DiscoveryItem = {
+          varName: entry.name,
+          resource: "",
+          listPath: "",
+          current,
+          status: "skip-not-required",
+          manifestSource: entry.source,
+        };
+
+        // Sources that discover does not own: the user fills these (auth/
+        // server/header) or the runtime captures them (capture-chain).
+        // required:false manifest entries (currently capture-chain) are also
+        // not the discover loop's responsibility.
+        const isOwnedByDiscover =
+          entry.required && (entry.source === "path" || entry.source === "body-fk");
+        if (!isOwnedByDiscover) {
+          placeholder.status = "skip-not-required";
+          placeholder.manifestStatus = "skipped:not-required";
+          items.push(placeholder);
+          continue;
+        }
+
+        // Already filled (and not a TODO placeholder) — leave it alone.
+        if (!isPlaceholder(current)) {
+          placeholder.status = "skip-already-set";
+          placeholder.manifestStatus = "skipped:already-set";
+          items.push(placeholder);
+          continue;
+        }
+
+        // Resolve owner resource via FK chain. body-fk vars often share the
+        // name with a path-param of another resource (audience_id ↔
+        // /audiences/{id}); resource map's collectBodyFkDeps already does
+        // name-stemming inference for us. A miss here means we have nothing
+        // to GET — the entry stays in the table as failed:no-list-endpoint.
+        let target = targetsByVar.get(entry.name);
+        if (!target) {
+          // ARV-69 (feedback round-02 / F10): the resource map only links a
+          // var to a list endpoint when the path explicitly carries it as a
+          // path-param (e.g. /audiences/{audience_id}). common-style APIs
+          // commonly use the generic {id} placeholder, so vars like
+          // `domain_id` / `segment_id` / `log_id` end up with no fkDep edge
+          // even though /domains, /segments, /logs are perfectly usable as
+          // list endpoints. Try a name-stemming fallback: strip the FK
+          // suffix and match a resource whose name is the singular or plural
+          // form.
+          const inferred = inferOwnerFromVarName(entry.name, resourceMap);
+          if (inferred) target = inferred;
+        }
+        if (!target) {
+          // ARV-382: no confident owner — surface plausible list endpoints as
+          // evidence instead of dead-ending. The agent picks (zond doesn't).
+          const candidates = findCandidateListEndpoints(entry.affectedEndpoints ?? [], endpoints);
+          placeholder.status = "miss-no-list";
+          placeholder.manifestStatus = "failed:no-list-endpoint";
+          if (candidates.length > 0) {
+            placeholder.candidates = candidates;
+            placeholder.reason = `${entry.source}-source var has no confident owner in .api-resources.yaml — ${candidates.length} candidate list endpoint(s) surfaced; GET one, pick a record, set the value`;
+          } else {
+            placeholder.reason = `${entry.source}-source var has no owner resource in .api-resources.yaml — cannot derive a list endpoint`;
+          }
+          items.push(placeholder);
+          continue;
+        }
+
+        const item = await probeOne(
+          target,
+          current,
+          endpoints,
+          securitySchemes,
+          env,
+          baseUrl,
+          options.timeoutMs ?? 30000,
+        );
+        item.manifestSource = entry.source;
+        item.manifestStatus = toManifestStatus(item.status);
+        items.push(item);
+      }
+    } else {
+      // Legacy path: no manifest in the workspace — probe FK targets directly.
+      for (const target of targets) {
+        const current = env[target.varName];
+        const item = await probeOne(
+          target,
+          current,
+          endpoints,
+          securitySchemes,
+          env,
+          baseUrl,
+          options.timeoutMs ?? 30000,
+        );
+        items.push(item);
+      }
+    }
+
+    // TASK-294: stamp every item with recommended_action before consumers
+    // (--json envelope, summary printer) read it.
+    for (const it of items) {
+      const action = discoveryAction(it.status);
+      if (action) it.recommended_action = action;
+    }
+
+    // ARV-362 (m-25): discover never writes discovered values — that's the
+    // agent's call. The only disk mutation is --refresh unsetting stale ids so
+    // the known-bad value is removed and the var resurfaces as a gap.
+    const unsets = options.verify && options.apply
+      ? items.filter(i => i.wasStale === true).map(i => i.varName)
+      : [];
+    let applied = false;
+    let backupPath: string | null = null;
+    if (unsets.length > 0) {
+      backupPath = `${envPath}.bak`;
+      try {
+        await copyFile(envPath, backupPath);
+      } catch {
+        // missing source — write fresh; no backup needed.
+        backupPath = null;
+      }
+      const file = Bun.file(envPath);
+      let text = (await file.exists()) ? await file.text() : "";
+      for (const v of unsets) {
+        text = upsertEnvLine(text, v, "");
+      }
+      if (!text.endsWith("\n")) text += "\n";
+      await Bun.write(envPath, text);
+      applied = true;
+    }
+
+    // ARV-46: env keys without a manifest entry are noise — the user (or a
+    // legacy hand-edit) put them there; the API doesn't actually need them.
+    // Surface as warning so they can be removed; do not act on them.
+    // ARV-260: exclude auto-managed auth keys (auth_token, api_key) — zond
+    // itself writes them at `add api` time and uses them to inject the
+    // Authorization/X-API-Key header even when the spec lacks
+    // securitySchemes. They are not in the fixtures manifest by design.
+    // Without this filter, prepare-fixtures tells users to "drop them from
+    // .env.yaml or run refresh-api" — both wrong actions that would break
+    // auth.
+    const AUTO_MANAGED_KEYS = new Set(["auth_token", "api_key"]);
+    let unknownEnvKeys: string[] = [];
+    if (manifest) {
+      const manifestNames = new Set(manifest.fixtures.map(f => f.name));
+      unknownEnvKeys = Object.keys(env).filter(
+        k => !manifestNames.has(k) && !AUTO_MANAGED_KEYS.has(k),
+      );
+    }
+
+    // ARV-324: persist confirmed empty/inaccessible operations so a later,
+    // separate `checks run` invocation can tell "known fixture gap" apart
+    // from "new backend bug" instead of mislabeling both report_backend_bug.
+    // Rewritten wholesale every run so a since-fixed gap doesn't linger.
+    await writeFixtureGaps(options.apiDir, gapsFromItems(items));
+
+    // ARV-349/350: report suite vars this single-pass run cannot resolve.
+    // Load the generated suites (best-effort — absent tests/ dir is fine) and
+    // scan them against the env we'd end up with (current + this run's writes).
+    // Report only; never invent values / auto-seed.
+    let gapReport: FixtureGapReport = { undefinedVars: [], unseededRoots: [] };
+    try {
+      const { suites } = await parseSafe(join(options.apiDir, "tests"));
+      if (suites.length > 0) {
+        // ARV-362: discover writes nothing, so the effective env is just what's
+        // already on disk (minus any stale ids --refresh unset above).
+        const effectiveEnv: Record<string, string> = { ...env };
+        // Required manifest vars still empty after this pass = candidate
+        // chain-roots. Source-agnostic: real specs model these as `path`
+        // required:true with an empty default, not only `capture-chain`.
+        const requiredEmptyVars = new Set(
+          (manifest?.fixtures ?? [])
+            .filter(f => f.required && !(effectiveEnv[f.name] && effectiveEnv[f.name]!.length > 0))
+            .map(f => f.name),
+        );
+        gapReport = reportFixtureGaps(suites, effectiveEnv, requiredEmptyVars);
+      }
+    } catch { /* suite scan is best-effort — never fail prepare-fixtures on it */ }
+
+    const requiredManifestCount = manifest
+      ? manifest.fixtures.filter(f => f.required).length
+      : 0;
+    // ARV-362: discover never fills a value, so "filled" means "already set on
+    // disk". Manifest-driven mode reports skip-already-set; verify mode reports
+    // verify-live / verify-user-config. The "Filled X/Y" line agrees with
+    // doctor and the user_config bucket isn't double-counted as UNSET.
+    const filledCount = items.filter(i =>
+      i.manifestStatus === "skipped:already-set" ||
+      i.status === "verify-live" ||
+      i.status === "verify-user-config",
+    ).length;
+
+    if (options.json) {
+      // ARV-143 follow-up: strip raw secret values from items[].current so the
+      // JSON envelope can't leak `.secrets.yaml`-resolved tokens. The
+      // SecretRegistry registered every non-base_url env var above, so
+      // redactObject swaps any registered value for `<redacted:<name>>`.
+      const safeItems = getSecretRegistry().redactObject(items);
+      printJson(jsonOk(commandName, {
+        envPath,
+        applied,
+        backup: backupPath,
+        items: safeItems,
+        summary: {
+          total: items.length,
+          // ARV-362: discover writes no values; --refresh may unset stale ids.
+          unset: unsets.length,
+          alreadySet: items.filter(i => i.status === "skip-already-set").length,
+          misses: items.filter(i => i.status.startsWith("miss-")).length,
+          // ARV-349/350: gaps prepare-fixtures cannot resolve deterministically.
+          // Present so an agent/user can fill them; values are never invented.
+          fixtureGaps: gapReport,
+          ...(manifest ? {
+            manifest: {
+              required: requiredManifestCount,
+              filled: filledCount,
+              unknownEnvKeys,
+            },
+          } : {}),
+          ...(options.verify ? {
+            verify: {
+              live: items.filter(i => i.status === "verify-live").length,
+              // Items classified stale. With --refresh they are also unset on
+              // disk (see `dropped`); without it they stay for the agent to fix.
+              stale: items.filter(i => i.status === "verify-stale").length,
+              // ARV-362: stale ids --refresh removed from .env.yaml (now gaps).
+              dropped: items.filter(i => i.wasStale === true).length,
+              unknown: items.filter(i => i.status === "verify-unknown").length,
+              skipped: items.filter(i => i.status === "verify-skip-empty" || i.status === "verify-no-read").length,
+              // ARV-143: filled vars with no verify path (user-config /
+              // resource-without-read). Doctor reports these as set:true;
+              // refresh now agrees by surfacing them in their own bucket.
+              user_config: items.filter(i => i.status === "verify-user-config").length,
+            },
+          } : {}),
+        },
+      }));
+    } else {
+      console.log(`Discovery against ${baseUrl} (${envPath}):`);
+      console.log("");
+      const cols = ["var", "source", "resource", "list", "status", "value/reason"];
+      const rows = items.map(i => [
+        i.varName,
+        i.manifestSource ?? "—",
+        i.resource || "—",
+        i.listPath || "—",
+        i.manifestStatus ?? i.status,
+        i.status === "skip-already-set"
+          ? `(kept: ${i.current})`
+          : i.status === "skip-not-required"
+            ? `(not owned by discover)`
+            : i.status === "verify-live"
+              ? `(live: ${i.current})`
+              : i.status === "verify-stale"
+                ? `(stale: ${i.current})${i.reason ? ` — ${i.reason}` : ""}`
+                : i.status === "verify-user-config"
+                  // ARV-143 follow-up: never echo the raw value here —
+                  // auth/header sources routinely carry tokens, and even
+                  // server URLs can be sensitive. Mirror doctor's
+                  // set/length-only contract from .secrets.yaml handling.
+                  ? `(trusted, length=${(i.current ?? "").length})`
+                  : (i.reason ?? ""),
+      ]);
+      // ARV-143 follow-up: redact every text cell through SecretRegistry so
+      // an `auth_token` that happens to slip into a `(kept: ...)` /
+      // `(live: ...)` cell can't reach stdout / scrollback / tee. The
+      // verify-user-config branch already substitutes length-only — this
+      // is defense in depth for the other status branches.
+      const reg = getSecretRegistry();
+      for (const r of rows) for (let i = 0; i < r.length; i++) r[i] = reg.redact(r[i]!);
+      const widths = cols.map((h, i) => Math.max(h.length, ...rows.map(r => r[i]!.length)));
+      const fmt = (cells: string[]) => cells.map((c, i) => c.padEnd(widths[i]!)).join("  ");
+      console.log(fmt(cols));
+      console.log(widths.map(w => "─".repeat(w)).join("  "));
+      for (const r of rows) console.log(fmt(r));
+      console.log("");
+      if (options.verify) {
+        const live = items.filter(i => i.status === "verify-live").length;
+        const stale = items.filter(i => i.status === "verify-stale").length;
+        const unknown = items.filter(i => i.status === "verify-unknown").length;
+        // ARV-362: stale ids --refresh removed from .env.yaml (now gaps).
+        const dropped = items.filter(i => i.wasStale === true).length;
+        // ARV-143: filled vars verify can't reach — call them out as trusted.
+        const userConfig = items.filter(i => i.status === "verify-user-config").length;
+        const parts = [`${live} live`, `${stale} stale`];
+        if (dropped > 0) parts.push(`${dropped} dropped`);
+        parts.push(`${unknown} unknown`);
+        if (userConfig > 0) parts.push(`${userConfig} trusted (no-verify-path)`);
+        console.log(`Verify summary: ${parts.join(", ")}.`);
+        if (stale > 0 && !options.apply) {
+          printWarning(`${stale} stale fixture(s) detected. Re-run with --refresh to drop them (agent refills .env.yaml).`);
+        }
+      }
+      if (manifest) {
+        console.log(`Filled ${filledCount} / ${requiredManifestCount} manifest entries.`);
+      }
+      // ARV-350: chain-roots that gate whole CRUD suites — flag first, they're
+      // the highest-leverage gap (one id un-skips a dependent chain). Cap the
+      // inline list; the full set is in the JSON envelope for agent consumption.
+      if (gapReport.unseededRoots.length > 0) {
+        printWarning(
+          `${gapReport.unseededRoots.length} unseeded chain-root(s): ${capNames(gapReport.unseededRoots.map(r => r.variable))}. ` +
+          `Dependent CRUD suites skip until these are set — supply an id via \`fixtures add\` / .env.yaml ` +
+          `(prepare-fixtures does not auto-seed; use --json for the full list).`,
+        );
+      }
+      // ARV-349: suite vars nothing produces — no env value, capture, or param.
+      if (gapReport.undefinedVars.length > 0) {
+        printWarning(
+          `${gapReport.undefinedVars.length} unresolved suite var(s): ${capNames(gapReport.undefinedVars.map(v => v.variable))}. ` +
+          `Fill them via \`fixtures add\` / .env.yaml (prepare-fixtures does not invent values; use --json for the full list).`,
+        );
+      }
+      if (unknownEnvKeys.length > 0) {
+        printWarning(
+          `${unknownEnvKeys.length} env key(s) not in manifest, ignored: ${unknownEnvKeys.join(", ")}. Drop them from .env.yaml or run \`zond refresh-api\` if the manifest is stale.`,
+        );
+      }
+      if (applied) {
+        printSuccess(`Unset ${unsets.length} stale fixture(s) in ${envPath}` + (backupPath ? ` (backup: ${backupPath})` : "") + ` — refill by hand / \`fixtures add\`.`);
+      } else if (!options.verify) {
+        console.log("discover reports gaps only — it never writes values (fill .env.yaml by hand or via `fixtures add`).");
+      }
+    }
+    return 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (options.json) printJson(jsonError(commandName, [message]));
+    else printError(message);
+    return 2;
+  }
+}
+
+// ARV-130 (m-19): file kept on purpose. CLI registration is owned by
+// ./prepare-fixtures.ts (TASK-299, m-13 D); the `discoverCommand` core
+// above is consumed both by that wrapper and by direct unit tests
+// (`tests/cli/discover*.test.ts`). It is NOT a deprecated alias for a
+// top-level `zond discover` command — that command does not exist and
+// has never been registered in `src/cli/program.ts`. See the m-19
+// audit note in backlog/tasks/arv-130.