@kirrosh/zond 0.23.0 → 0.26.1

package/src/cli/commands/api/annotate/index.ts

@@ -69,6 +69,18 @@ export interface DumpOptions {
   only?: string[];
   json?: boolean;
   dbPath?: string;
+  /** ARV-277: enrich seed-bodies bundles with the most recent
+   *  fixture-kind POST attempt to the create endpoint, so the calling
+   *  agent sees exactly what zond tried last + how the server replied
+   *  (avoids the "agent re-discovers each 400 by hand" loop). */
+  withLastAttempt?: boolean;
+  /** ARV-278: when `withLastAttempt` is true, return the most recent N
+   *  attempts (most recent first) instead of just the last one. Surfaces
+   *  the *progression* of errors as the overlay was iterated — first 400
+   *  was "missing X", after fixing the body the next 400 is "stale FK"
+   *  pulls cascade-staleness (ARV-282) onto the agent's screen one
+   *  iteration earlier. `1` keeps the old single-snapshot behaviour. */
+  historyLimit?: number;
 }
 
 export async function dumpCommand(opts: DumpOptions): Promise<number> {
@@ -87,13 +99,67 @@ export async function dumpCommand(opts: DumpOptions): Promise<number> {
   }
 
   let resources = map.resources;
+  let unknownOnly: string[] = [];
   if (opts.only && opts.only.length > 0) {
     const wanted = new Set(opts.only);
+    const knownNames = new Set(map.resources.map((r) => r.resource));
+    unknownOnly = opts.only.filter((n) => !knownNames.has(n));
     resources = resources.filter((r) => wanted.has(r.resource));
   }
   const slices = buildResourceSlices(doc, resources);
   const bundles = buildDumpBundles(opts.kind, slices, doc, map.resources);
 
+  // ARV-277: enrich seed-bodies bundles with the last fixture-kind POST
+  // attempt (from `runs/results` DB). The agent reads `last_attempt`
+  // alongside the spec slice instead of running `zond request POST …`
+  // by hand to reproduce the failure mode.
+  if (opts.withLastAttempt && opts.kind === "seed-bodies") {
+    try {
+      // ARV-330: use the wider all-run-kinds query (a create-path POST made
+      // during a check/probe run counts too, not just fixture runs) and pass
+      // the child-exclude pattern so probe sub-resource POSTs
+      // (`/v1/accounts/{id}/reject`) don't monopolise the history window.
+      const { getRecentCreatePosts } = await import("../../../../db/queries/results.ts");
+      const limit = Math.max(1, Math.floor(opts.historyLimit ?? 1));
+      for (const b of bundles) {
+        const data = b.data as Record<string, unknown> | null;
+        const endpoints = data?.endpoints as Record<string, EndpointDump | undefined> | undefined;
+        const create = endpoints?.create;
+        if (!create) continue;
+        const pattern = createUrlLikePattern(create.path);
+        const recent = getRecentCreatePosts(pattern, limit, childExcludePattern(create.path));
+        if (recent.length === 0) continue;
+        // ARV-278: keep `last_attempt` as the most-recent entry (back-compat
+        // with single-snapshot consumers) and add `attempt_history` when
+        // the caller asked for >1.
+        (b.data as Record<string, unknown>).last_attempt = recent[0];
+        if (limit > 1) (b.data as Record<string, unknown>).attempt_history = recent;
+      }
+    } catch (err) {
+      // DB lookup is best-effort — degraded dump (no `last_attempt`) is
+      // still useful, so we warn but don't fail the command.
+      process.stderr.write(`zond: --with-last-attempt: DB lookup failed (${(err as Error).message}); dump emitted without last_attempt.\n`);
+    }
+  }
+
+  // ARV-226: when `--only` filtered to resources that have no applicable
+  // surface for this kind (no list endpoint for pagination/readback, no
+  // write surface for idempotency/seed-bodies, etc.), the dump silently
+  // returns []. Distinguish "no surface" from "unknown resource" so the
+  // user can tell whether they mistyped or hit a category-not-applicable.
+  if (!opts.json && opts.only && opts.only.length > 0 && opts.kind !== "resources") {
+    const emitted = new Set(bundles.map((b) => b.resource));
+    const filteredButNoSurface = opts.only.filter(
+      (n) => !emitted.has(n) && !unknownOnly.includes(n),
+    );
+    for (const n of unknownOnly) {
+      process.stderr.write(`zond: --only: resource '${n}' not in .api-resources.yaml (refresh-api or check spelling).\n`);
+    }
+    for (const n of filteredButNoSurface) {
+      process.stderr.write(`zond: --only: resource '${n}' has no applicable surface for --${opts.kind} (skipped).\n`);
+    }
+  }
+
   if (opts.json) {
     printJson(jsonOk("api annotate dump", { kind: opts.kind, bundles }));
   } else {
@@ -102,6 +168,33 @@ export async function dumpCommand(opts: DumpOptions): Promise<number> {
   return 0;
 }
 
+/**
+ * ARV-277: convert a create-endpoint path (`/v1/customers/{customer}/sources`)
+ * to a SQL LIKE pattern matched against full request_url
+ * (`https://api.stripe.com/v1/customers/cus_…/sources?...`). Path-params
+ * collapse to `%`; the prefix and suffix wildcards cover the scheme/host
+ * and optional query string. Anchoring is intentionally loose because
+ * recorders write absolute URLs and we want to find the seed POST
+ * regardless of base_url shape.
+ */
+export function createUrlLikePattern(createPath: string): string {
+  const collapsed = createPath.replace(/\{[^}]+\}/g, "%");
+  // SQL LIKE `%` matches across slashes (no special escape needed for
+  // the path segments since we don't expect %/_ in spec paths). Leading
+  // wildcard absorbs `https://api.stripe.com`, trailing absorbs `?expand=…`.
+  return `%${collapsed}%`;
+}
+
+/**
+ * ARV-330: companion NOT-LIKE pattern that excludes child sub-resource
+ * POSTs (`/v1/accounts/{id}/reject`, `.../persons`) from a create-path
+ * match. Pairs with `createUrlLikePattern` in `getRecentCreatePosts`.
+ */
+export function childExcludePattern(createPath: string): string {
+  const collapsed = createPath.replace(/\{[^}]+\}/g, "%");
+  return `%${collapsed}/%`;
+}
+
 function buildDumpBundles(
   kind: SubcommandKind,
   slices: ResourceSlice[],
@@ -144,10 +237,20 @@ function buildDumpBundles(
     switch (kind) {
       case "seed-bodies":
       case "idempotency":
-      case "pagination":
       case "readback":
         data = sliceData(slice);
         break;
+      case "pagination": {
+        // ARV-235: when the list endpoint already declares standard
+        // page-style params, agent doesn't need to re-read the full
+        // params schema to produce the annotation — surface a precomputed
+        // hint so the response can be `{ type: page, page_param, limit_param }`
+        // without inspecting the spec slice further.
+        const hint = detectPaginationHint(slice);
+        const base = sliceData(slice) as Record<string, unknown>;
+        data = hint ? { ...base, pagination_hint: hint } : base;
+        break;
+      }
       case "lifecycle":
         data = {
           ...(sliceData(slice) as Record<string, unknown>),
@@ -175,6 +278,46 @@ function sliceData(slice: ResourceSlice): unknown {
   };
 }
 
+/**
+ * ARV-235: detect well-known page-style pagination params on the list
+ * endpoint so the dump's response shape becomes a one-liner for the
+ * agent. Returns null if the params don't match a known shape — the
+ * agent then walks the full slice as before.
+ */
+function detectPaginationHint(slice: ResourceSlice): null | {
+  detected_style: "page" | "offset";
+  page_param?: string;
+  limit_param?: string;
+  offset_param?: string;
+  note: string;
+} {
+  const list = slice.endpoints.list;
+  if (!list || !list.parameters) return null;
+  const queryNames = new Set(
+    list.parameters.filter((p) => p.in === "query").map((p) => p.name.toLowerCase()),
+  );
+  const pageParam = ["page"].find((n) => queryNames.has(n));
+  const limitParam = ["per_page", "page_size", "pagesize", "limit"].find((n) => queryNames.has(n));
+  const offsetParam = ["offset", "skip", "start"].find((n) => queryNames.has(n));
+  if (pageParam) {
+    return {
+      detected_style: "page",
+      page_param: pageParam,
+      limit_param: limitParam,
+      note: "list endpoint declares page-style params; respond with { type: 'page', page_param, limit_param } to skip rereading the full spec slice.",
+    };
+  }
+  if (offsetParam) {
+    return {
+      detected_style: "offset",
+      offset_param: offsetParam,
+      limit_param: limitParam,
+      note: "list endpoint declares offset-style params; pagination check short-circuits offset/token (per m-20). Skip annotation for this resource or return { pagination: null }.",
+    };
+  }
+  return null;
+}
+
 function isSliceApplicable(kind: SubcommandKind, slice: ResourceSlice): boolean {
   switch (kind) {
     case "seed-bodies": return seedBodies.isApplicable(slice);
@@ -226,6 +369,13 @@ export interface ApplyOptions {
   force?: boolean;
   json?: boolean;
   dbPath?: string;
+  /** ARV-281: agent-loop regression protection. When set, apply drops
+   *  any aspect-level field on a proposed patch when the existing
+   *  overlay already has that field set (regardless of value). The
+   *  agent's response can only ADD missing pieces — it can't overwrite
+   *  a previously curated `seed_body` even by accident. `--force`
+   *  ignores this flag (explicit override stays explicit). */
+  gapFillOnly?: boolean;
 }
 
 export async function applyCommand(opts: ApplyOptions): Promise<number> {
@@ -281,7 +431,19 @@ export async function applyCommand(opts: ApplyOptions): Promise<number> {
 
   const overlay = await readLocalOverlay(col.baseDir);
   const existing = (overlay.patches ?? []) as ResourcePatch[];
-  const merge = mergePatches(existing, nonEmpty.map((d) => d.patch), { force: opts.force === true });
+
+  // ARV-281: gap-fill-only — drop aspect-level fields where the existing
+  // overlay already has a value set. Keeps the agent's response strictly
+  // additive vs. previous (heuristic + curated) edits. `--force` opts out
+  // of this guard, mirroring the existing conflict semantics.
+  const filteredPatches = opts.gapFillOnly && opts.force !== true
+    ? nonEmpty.map((d) => filterToGaps(d.patch, existing))
+    : nonEmpty.map((d) => d.patch);
+  const gapDroppedFields = opts.gapFillOnly && opts.force !== true
+    ? countGapDroppedFields(nonEmpty.map((d) => d.patch), filteredPatches)
+    : 0;
+
+  const merge = mergePatches(existing, filteredPatches, { force: opts.force === true });
 
   const summary = {
     api: opts.api,
@@ -292,6 +454,11 @@ export async function applyCommand(opts: ApplyOptions): Promise<number> {
     failures: errors,
     changes: merge.changes.length,
     conflicts: merge.conflicts.length,
+    /** ARV-281: aspect-level fields the agent proposed that gap-fill-only
+     *  silently dropped because the existing overlay already had them
+     *  set. Distinct from `conflicts` which is mergePatches's concept of
+     *  field-level disagreement. */
+    gap_fill_dropped: gapDroppedFields,
   };
 
   const diff = renderChangesDiff(merge);
@@ -300,6 +467,9 @@ export async function applyCommand(opts: ApplyOptions): Promise<number> {
       printWarning(`Failed to parse ${errors.length} document(s):`);
       for (const e of errors) process.stdout.write(`  ✗ ${e.resource}: ${e.error}\n`);
     }
+    if (gapDroppedFields > 0) {
+      printWarning(`--gap-fill-only dropped ${gapDroppedFields} aspect-field(s) the agent proposed for resources that already had them set. Re-run with --force to overwrite anyway.`);
+    }
     if (diff) {
       process.stdout.write("\nProposed changes (and conflicts):\n");
       process.stdout.write(diff + "\n\n");
@@ -331,10 +501,44 @@ export async function applyCommand(opts: ApplyOptions): Promise<number> {
   if (merge.conflicts.length > 0 && !opts.force && !opts.json) {
     printWarning(`${merge.conflicts.length} conflict(s) kept existing values. Re-run with --force to overwrite.`);
   }
+  // ARV-217: after a successful apply, surface the basePaths the agent
+  // should keep in `checks run --include` so a narrowed scope doesn't
+  // silently skip the freshly annotated resources. Without this hint, the
+  // next stateful run reports "no pagination config" for every endpoint
+  // outside the include filter and the apply looks like a no-op.
+  if (!opts.json && merge.changes.length > 0) {
+    const annotatedBasePaths = new Set<string>();
+    for (const patch of merge.patches) {
+      const slice = slicesByName.get(patch.resource);
+      if (slice?.basePath) annotatedBasePaths.add(slice.basePath);
+    }
+    if (annotatedBasePaths.size > 0) {
+      const checkName = opts.kind === "pagination"
+        ? "pagination_invariants"
+        : opts.kind === "lifecycle"
+          ? "lifecycle_transitions"
+          : opts.kind === "idempotency"
+            ? "idempotency_replay"
+            : opts.kind === "readback"
+              ? "cross_call_references"
+              : opts.kind === "seed-bodies"
+                ? "stateful"
+                : "stateful";
+      const includeAlt = [...annotatedBasePaths].map(escapeForPathRegex).join("|");
+      process.stdout.write(
+        `\nTip: to exercise these annotations, scope --include to cover the annotated basePath(s):\n` +
+        `  zond checks run --api ${opts.api} --check ${checkName} --include 'path:^(${includeAlt})(/.*)?$'\n`,
+      );
+    }
+  }
   if (opts.json) printJson(jsonOk("api annotate apply", { ...summary, written: true }));
   return 0;
 }
 
+function escapeForPathRegex(path: string): string {
+  return path.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 function parseByKind(kind: SubcommandKind, parsed: unknown, slice: ResourceSlice): { patch: ResourcePatch; audit: Record<string, unknown> } {
   switch (kind) {
     case "seed-bodies": return seedBodies.parseSeedBodyResponse(parsed, slice);
@@ -391,6 +595,144 @@ async function applyResources(apiDir: string, documents: unknown[], opts: ApplyO
   return 0;
 }
 
+/**
+ * ARV-280: error-message shapes Stripe/etc emit when an account-level
+ * capability is missing rather than an overlay-level data issue.
+ * Conservative — we only tag a resource as `account_capability_missing`
+ * when the most recent attempts ALL match, because Stripe's
+ * order-of-validation can surface a transient data error first and
+ * then a capability error after the overlay is fixed.
+ */
+const HARD_BLOCKED_PATTERNS = [
+  /not\s+supported\s+for\s+country/i,
+  /not\s+available\s+in\s+your\s+account/i,
+  /capability/i,
+  /not\s+enabled/i,
+  /\bnot\s+onboarded\b/i,
+  /raw[- ]card[- ]data\s+(api|access)/i,
+  /you do not have access/i,
+  /signed up for connect/i,
+];
+
+/**
+ * ARV-330: replies from security/auth probes that POST with deliberately
+ * broken credentials. Their 401/403s say nothing about whether the
+ * resource is capability-blocked, so the classifier drops them before
+ * judging.
+ */
+const AUTH_NOISE_PATTERNS = [
+  /invalid api key/i,
+  /did not provide an api key/i,
+  /no api key provided/i,
+  /provided key '/i,
+];
+
+/**
+ * ARV-330: verdict on a resource's create-path POST history. Pure so it
+ * can be unit-tested without a DB. Returns `account_capability_missing`
+ * when the account-level gate is the blocker, else null.
+ *
+ * Logic:
+ *  1. Drop auth-probe noise (broken-cred 401/403s) — not about the resource.
+ *  2. Any 2xx among valid attempts → the resource IS seedable, never blocked.
+ *  3. A capability/onboarding gate is account-level and deterministic: one
+ *     hit on a valid-key attempt (with no success) is enough. We don't
+ *     require ALL attempts to match, because a generic-generator body can
+ *     trigger a data-shaped 400 on one attempt while a leaner body hits
+ *     the gate on another (the ARV-330 chicken-and-egg case).
+ */
+/**
+ * ARV-330: guard the loose `createUrlLikePattern` LIKE from counting
+ * child sub-resource POSTs. `%/v1/accounts%` also matches
+ * `/v1/accounts/{id}/reject` and `.../persons` — POSTs to *different*
+ * endpoints (often auth-probe noise) that would drown out the real
+ * create-path attempt. Match the recorded URL's path segment-for-segment
+ * against the create-path (`{param}` matches any single segment).
+ */
+export function urlMatchesCreatePath(requestUrl: string, createPath: string): boolean {
+  let path: string;
+  try { path = new URL(requestUrl).pathname; } catch { return false; }
+  const want = createPath.split("/").filter(Boolean);
+  const got = path.split("/").filter(Boolean);
+  if (want.length !== got.length) return false;
+  return want.every((seg, i) => seg.startsWith("{") || seg === got[i]);
+}
+
+export function classifyAttempts(
+  attempts: Array<{ response_status: number | null; response_body: string | null }>,
+): "account_capability_missing" | null {
+  const valid = attempts.filter((a) => {
+    if (a.response_status === 401 || a.response_status === 403) return false;
+    const msg = extractMessage(a.response_body);
+    return !(msg !== null && AUTH_NOISE_PATTERNS.some((re) => re.test(msg)));
+  });
+  if (valid.length === 0) return null;
+  if (valid.some((a) => a.response_status !== null && a.response_status >= 200 && a.response_status < 300)) return null;
+  const capabilityHit = valid.some((a) => {
+    const msg = extractMessage(a.response_body);
+    return msg !== null && HARD_BLOCKED_PATTERNS.some((re) => re.test(msg));
+  });
+  return capabilityHit ? "account_capability_missing" : null;
+}
+
+function extractMessage(body: string | null): string | null {
+  if (!body) return null;
+  try {
+    const parsed = JSON.parse(body);
+    const m = parsed?.error?.message;
+    return typeof m === "string" ? m : null;
+  } catch {
+    return null;
+  }
+}
+
+// ─── ARV-281: gap-fill filtering ─────────────────────────────────────
+
+/**
+ * Drop aspect-level fields on a proposed patch when the existing
+ * overlay (matched by resource name) already has that field set to a
+ * non-empty value. Returns a new patch object — never mutates input.
+ */
+export function filterToGaps(
+  proposed: ResourcePatch,
+  existing: ResourcePatch[],
+): ResourcePatch {
+  const prior = existing.find((p) => p.resource === proposed.resource);
+  if (!prior) return proposed;
+  const out: ResourcePatch = { resource: proposed.resource };
+  for (const [key, value] of Object.entries(proposed) as Array<[string, unknown]>) {
+    if (key === "resource") continue;
+    const existingVal = (prior as unknown as Record<string, unknown>)[key];
+    if (isPresent(existingVal)) continue; // already-set field → skip
+    (out as Record<string, unknown>)[key] = value;
+  }
+  return out;
+}
+
+function isPresent(v: unknown): boolean {
+  if (v === undefined || v === null) return false;
+  if (typeof v === "string") return v.length > 0;
+  if (Array.isArray(v)) return v.length > 0;
+  if (typeof v === "object") return Object.keys(v as Record<string, unknown>).length > 0;
+  return true;
+}
+
+function countGapDroppedFields(
+  before: ResourcePatch[],
+  after: ResourcePatch[],
+): number {
+  let n = 0;
+  for (let i = 0; i < before.length; i++) {
+    const b = before[i]!;
+    const a = after[i]!;
+    for (const k of Object.keys(b)) {
+      if (k === "resource") continue;
+      if (!(k in a)) n++;
+    }
+  }
+  return n;
+}
+
 // ─── I/O helpers ─────────────────────────────────────────────────────
 
 async function readInput(source: string): Promise<string> {
@@ -433,7 +775,7 @@ export function registerApiAnnotate(program: Command): void {
 
   const annotate = api
     .command("annotate")
-    .description("Agent-augmented overlay authoring. zond emits raw spec slices → agent generates YAML → zond validates+applies. Two subcommands: `dump` and `apply`.");
+    .description("Overlay authoring for .api-resources.local.yaml. Two subcommands: `dump` (emit spec slices) + `apply` (validate & merge the agent's YAML) — agent-in-the-loop, ARV-187. zond carries no inference; the agent writes the annotations, zond validates and merges.");
 
   annotate
     .command("dump")
@@ -446,6 +788,8 @@ export function registerApiAnnotate(program: Command): void {
     .option("--readback", "Create+read pair for readback_diff")
     .option("--resources", "Orphan-endpoint list for resource-graph extensions")
     .option("--only <list>", "Comma-separated resource names — restrict scope", csv)
+    .option("--with-last-attempt", "ARV-277: enrich seed-bodies bundles with the most recent fixture-kind POST attempt (`request_body`/`response_status`/`response_body`/`attempted_at`) so the agent sees what zond tried last without re-running prepare-fixtures.")
+    .option("--history <N>", "ARV-278: with --with-last-attempt, return the most recent N attempts (newest first) under `attempt_history`. Surfaces error progression as the overlay was iterated.", (v) => Number.parseInt(v, 10))
     .option("--db <path>", "SQLite db path override")
     .action(async (rawOpts, cmd: Command) => {
       const kind = pickKind(rawOpts);
@@ -454,10 +798,19 @@ export function registerApiAnnotate(program: Command): void {
         process.exitCode = 2;
         return;
       }
+      if (rawOpts.withLastAttempt === true && kind !== "seed-bodies") {
+        printWarning("--with-last-attempt is only meaningful with --seed-bodies; ignored.");
+      }
       const apiName = resolveApiArg(rawOpts, cmd);
       if (!apiName) { printError("No API selected."); process.exitCode = 2; return; }
       process.exitCode = await dumpCommand({
-        api: apiName, kind, only: rawOpts.only, dbPath: rawOpts.db, json: globalJson(cmd),
+        api: apiName,
+        kind,
+        only: rawOpts.only,
+        dbPath: rawOpts.db,
+        json: globalJson(cmd),
+        withLastAttempt: rawOpts.withLastAttempt === true,
+        historyLimit: Number.isFinite(rawOpts.history) ? rawOpts.history : undefined,
       });
     });
 
@@ -474,6 +827,7 @@ export function registerApiAnnotate(program: Command): void {
     .option("--input <file>", "Path to the YAML responses file, or `-` for stdin", "-")
     .option("--yes", "Write the proposed patches to disk (default: dry-run + diff)")
     .option("--force", "Overwrite the existing value on field-level conflict")
+    .option("--gap-fill-only", "ARV-281: drop aspect-level fields the agent proposed for resources that already have that field set in the overlay. Keeps the agent's response strictly additive — protects curated `seed_body` blocks from accidental regression. Bypassed by --force.")
     .option("--db <path>", "SQLite db path override")
     .action(async (rawOpts, cmd: Command) => {
       const kind = pickKind(rawOpts);
@@ -490,6 +844,7 @@ export function registerApiAnnotate(program: Command): void {
         input: rawOpts.input ?? "-",
         yes: rawOpts.yes === true,
         force: rawOpts.force === true,
+        gapFillOnly: rawOpts.gapFillOnly === true,
         dbPath: rawOpts.db,
         json: globalJson(cmd),
       });

package/src/cli/commands/api/annotate/lifecycle.ts

@@ -32,7 +32,7 @@ export const EXPECTED_OUTPUT_SHAPE = {
     field: "string (response field holding state, e.g. 'status')",
     states: "string[] (≥2 enum values)",
     transitions: "[{from: state, to: state[]}]",
-    actions: "{ <verb>: { endpoint: 'METHOD /path', expected_state: state, body?: object } }",
+    actions: "{ <verb>: { endpoint: 'METHOD /path', expected_state: state, body?: object } } — return {} for read-only state machines (observation mode walks the list endpoint and asserts observed ⊆ states; cannot verify transitions in this mode)",
   },
   rationale: "string (optional)",
   confidence: "low | medium | high",

package/src/cli/commands/api/annotate/overlay.ts

@@ -133,7 +133,7 @@ function stableJson(v: unknown): string {
 }
 
 function deepClone<T>(v: T): T {
-  return JSON.parse(JSON.stringify(v));
+  return structuredClone(v);
 }
 
 /**

package/src/cli/commands/api/annotate/pagination.ts

@@ -14,6 +14,8 @@ const PaginationSchema = z.object({
   limit_param: z.string().optional(),
   default_limit: z.number().int().positive().optional(),
   items_field: z.string().optional(),
+  page_param: z.string().optional(),
+  start_page: z.number().int().nonnegative().optional(),
 });
 
 const ResponseSchema = z.object({
@@ -26,13 +28,15 @@ const ResponseSchema = z.object({
 export const EXPECTED_OUTPUT_SHAPE = {
   resource: "string (echo input)",
   pagination: {
-    type: "cursor | page | offset | token",
-    cursor_param: "string (optional — query param carrying cursor value)",
-    cursor_field: "string (optional — response field that becomes next cursor)",
-    has_more_field: "string (optional — boolean response field signalling more)",
-    limit_param: "string (optional)",
-    default_limit: "integer (optional)",
+    type: "cursor | page | offset | token (cursor and page are implemented; offset/token short-circuit)",
+    cursor_param: "string (optional — only for type=cursor; query param carrying cursor value)",
+    cursor_field: "string (optional — for cursor: next-cursor field; for page: dedupe key across pages; default `id`)",
+    has_more_field: "string (optional — only for type=cursor; boolean response field signalling more)",
+    limit_param: "string (optional — page size param; default `limit` for cursor, `per_page` for page)",
+    default_limit: "integer (optional — probe page size; default 2)",
     items_field: "string (optional — response field carrying array)",
+    page_param: "string (optional — only for type=page; default `page`)",
+    start_page: "integer (optional — only for type=page; first page number, default 1; some APIs use 0)",
   },
   rationale: "string (optional)",
   confidence: "low | medium | high",

package/src/cli/commands/api/annotate/prompts.ts

@@ -95,8 +95,9 @@ function dumpEndpoint(doc: OpenAPIV3.Document, method: string, path: string): En
   if (!op) return null;
 
   const parameters: EndpointDump["parameters"] = [];
-  for (const p of [...(pathItem.parameters ?? []), ...(op.parameters ?? [])]) {
-    if ("$ref" in p) continue;
+  for (const raw of [...(pathItem.parameters ?? []), ...(op.parameters ?? [])]) {
+    const p = resolveParameter(doc, raw);
+    if (!p) continue;
     parameters.push({
       name: p.name,
       in: p.in,
@@ -181,3 +182,39 @@ function truncate(s: string | undefined, n: number): string | undefined {
   return s.length > n ? s.slice(0, n) + "…" : s;
 }
 
+/**
+ * Resolve a parameter that may be inline or a $ref. Handles
+ * `#/components/parameters/X` (canonical) and, leniently,
+ * `#/components/headers/X` — some specs (Stripe) keep their
+ * `Idempotency-Key` declaration under `components.headers` and reuse
+ * it as a parameter $ref. Returns null on unresolvable refs.
+ */
+function resolveParameter(
+  doc: OpenAPIV3.Document,
+  raw: OpenAPIV3.ParameterObject | OpenAPIV3.ReferenceObject,
+): OpenAPIV3.ParameterObject | null {
+  if (!("$ref" in raw)) return raw;
+  const ref = raw.$ref;
+  const paramMatch = ref.match(/^#\/components\/parameters\/(.+)$/);
+  if (paramMatch) {
+    const target = doc.components?.parameters?.[paramMatch[1]!];
+    if (target && !("$ref" in target)) return target as OpenAPIV3.ParameterObject;
+  }
+  const headerMatch = ref.match(/^#\/components\/headers\/(.+)$/);
+  if (headerMatch) {
+    const name = headerMatch[1]!;
+    const target = doc.components?.headers?.[name];
+    if (target && !("$ref" in target)) {
+      const h = target as OpenAPIV3.HeaderObject;
+      return {
+        name,
+        in: "header",
+        required: h.required,
+        description: h.description,
+        schema: h.schema,
+      } as OpenAPIV3.ParameterObject;
+    }
+  }
+  return null;
+}
+