@kirrosh/zond 0.22.0 → 0.26.0

package/README.md

@@ -15,18 +15,51 @@ curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh
 iwr https://raw.githubusercontent.com/kirrosh/zond/master/install.ps1 | iex        # Windows
 ```
 
-Bootstrap a workspace and register your first API:
+Bootstrap a workspace, register your first API, then fill its fixtures:
 
 ```bash
-zond init --workspace --with-spec ./openapi.json
+zond init                                              # bootstrap workspace (no fixture changes)
+zond add api my-api --spec ./openapi.json              # register: copies spec.json + emits manifest
+zond doctor --api my-api --missing-only                # gap report: which vars are UNSET
+zond prepare-fixtures --api my-api                     # gap report: verify fixtures + which FK vars need a value
 ```
 
-`zond init` writes a self-contained [`AGENTS.md`](AGENTS.md) — agents read it
-and use the CLI directly (`zond run`, `zond probe-validation`,
-`zond db diagnose`, …). No daemon, no transport, no extra configuration.
+`prepare-fixtures` **reports** gaps — it never harvests a value (which
+record/field fills a path slot is your call). Fill each gap with the
+manual helpers (ARV-195):
+
+```bash
+zond fixtures add --api my-api customer_id=cus_123 --validate --apply
+pbpaste | zond fixtures import --api my-api --from-curl --apply        # paste a curl from devtools
+```
+
+`zond init` writes a self-contained [`AGENTS.md`](AGENTS.md) and Claude Code
+skills — agents read it and use the CLI directly (`zond run`,
+`zond probe static`, `zond db diagnose`, …). No daemon, no transport, no
+extra configuration. `init` is workspace-only — it never touches
+`.env.yaml`; the fixture loop above is the canonical path.
+
+Each registered API gets four files in `apis/<name>/`:
+
+- `spec.json` — dereferenced OpenAPI snapshot (canonical machine source).
+- `.api-catalog.yaml` — endpoint index for agents (cheap to read).
+- `.api-resources.yaml` — CRUD chains, FK dependencies, ETag/soft-delete flags.
+- `.api-fixtures.yaml` — **manifest** of required `{{vars}}` (read-only, auto-generated).
+
+Plus a sibling `.env.yaml` that **you** fill with the **values** for those
+vars (`zond prepare-fixtures` only reports which are missing). The
+manifest/values split is strict — see the
+[workspace contract](AGENTS.md#workspace-contract) for details.
+
+Run `zond refresh-api <name> [--spec <new-source>]` to re-snapshot when the
+upstream spec changes.
 
 Then say to your agent: _"Safely cover the API from openapi.json with tests."_
 
+Want the whole pipeline at once? `zond audit --api my-api` runs
+prepare-fixtures → generate → probes → run → coverage → HTML report in a
+single shot.
+
 <details>
 <summary>Other installation methods (npx)</summary>
 
@@ -58,6 +91,11 @@ Claude Code can write pytest from scratch — but it takes 30-60 minutes per flo
 | **Spec-Grounded** | Tests are derived from your OpenAPI schema, not invented from scratch. The spec is the source of truth. |
 | **Full Visibility** | Every run is stored in SQLite. Compare runs, track regressions, see exactly what the server returned. |
 | **Coverage Tracking** | See which endpoints are tested, which aren't, and what broke since last run. |
+| **Schema Validation** | `--validate-schema` checks every JSON response against the OpenAPI schema (types, required, enum, format, `$ref`) — catches contract drift the YAML expectations miss. |
+| **Spec Linting** | `zond check spec` static-analyses the OpenAPI document for internal-consistency bugs (e.g. example violates `format: date-time`) and strictness gaps (path-params without `format`, integer params without min/max) — surfaces issues before any HTTP request. |
+| **Depth Checks (m-15)** | `zond checks run` runs a schemathesis-style catalog of conformance + security probes (`status_code_conformance`, `negative_data_rejection`, `ignored_auth`, `use_after_free`, …) — boundary-value coverage, broken-auth detection, soft-deleted resource leaks. Every finding ships with a `recommended_action` enum so the agent triages without parsing messages. |
+| **SARIF for Code Scanning** | `--report sarif` emits SARIF v2.1.0 with stable `partialFingerprints` — drop-in for `github/codeql-action/upload-sarif@v3` so depth-checks findings show up in GitHub's Security tab. |
+| **Concurrent Workers** | `--workers auto` parallelizes runs at the operation level (bounded async-pool, no threading) — runs that took minutes finish in seconds. Pair with `--rate-limit` to stay within an API's RPS budget. |
 | **CI-Ready** | One command generates GitHub Actions or GitLab CI workflow. Tests in YAML, in git, with code review. |
 
 ## Try It
@@ -69,6 +107,21 @@ Claude Code can write pytest from scratch — but it takes 30-60 minutes per flo
 "Set up CI for API tests"
 ```
 
+## Upgrading
+
+`zond update` was removed in favour of system package managers:
+
+```bash
+# macOS / Linux — re-run the installer
+curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh
+
+# npm
+npm install -g @kirrosh/zond@latest
+
+# bun
+bun install -g @kirrosh/zond@latest
+```
+
 ## Shell completions
 
 ```bash
@@ -82,7 +135,7 @@ zond completions fish > ~/.config/fish/completions/zond.fish
 - [ZOND.md](ZOND.md) — full CLI reference
 - [docs/quickstart.md](docs/quickstart.md) — step-by-step quickstart (RU)
 - [docs/ci.md](docs/ci.md) — CI/CD integration
-- [backlog/](backlog/) — project tasks (powered by [Backlog.md](https://backlog.md), see [docs/backlog.md](docs/backlog.md))
+- [backlog/](backlog/) — project tasks (powered by [Backlog.md](https://backlog.md))
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kirrosh/zond",
-  "version": "0.22.0",
-  "description": "API testing platform — define tests in YAML, run from CLI or WebUI, generate from OpenAPI specs",
+  "version": "0.26.0",
+  "description": "API testing platform — define tests in YAML, run from CLI, generate from OpenAPI specs",
   "license": "MIT",
   "module": "index.ts",
   "type": "module",
@@ -28,15 +28,17 @@
     "backlog": "bunx backlog",
     "board": "bunx backlog board",
     "test": "bun run test:unit && bun run test:mocked",
-    "test:unit": "bun test tests/db/ tests/parser/ tests/runner/ tests/generator/ tests/core/ tests/core/meta/ tests/diagnostics/ tests/cli/program.test.ts tests/cli/cli-smoke.test.ts tests/cli/completions.test.ts tests/cli/ci-init.test.ts tests/cli/commands.test.ts tests/cli/safe-run.test.ts tests/cli/json-envelope.test.ts tests/cli/describe.test.ts tests/cli/catalog.test.ts tests/cli/db.test.ts tests/cli/request.test.ts tests/cli/init.test.ts tests/cli/init/agents-md.test.ts tests/cli/init/bootstrap.test.ts tests/cli/use.test.ts tests/cli/guide.test.ts tests/cli/update.test.ts tests/cli/serve.test.ts tests/integration/ tests/web/ tests/reporter/",
+    "test:unit": "bun test tests/",
     "test:mocked": "bun run scripts/run-mocked-tests.ts",
     "check": "tsc --noEmit --project tsconfig.json",
+    "schemas": "bun run scripts/emit-json-schemas.ts",
+    "schemas:check": "bun run scripts/emit-json-schemas.ts --check",
     "lint:dead": "knip --reporter compact",
-    "build": "bun build --compile src/cli/index.ts --outfile zond",
-    "bench:api": "bun benchmarks/api/server.ts"
+    "build": "bun build --compile src/cli/index.ts --outfile dist/zond && bun run scripts/codesign-darwin.ts ./dist/zond"
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "ajv-draft-04": "^1.0.0",
     "backlog.md": "^1.44.0",
     "knip": "^6.7.0"
   },
@@ -47,10 +49,10 @@
     "typescript": "^5"
   },
   "dependencies": {
-    "@hono/zod-openapi": "^1.2.2",
     "@readme/openapi-parser": "^5.5.0",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
     "commander": "^14.0.0",
-    "hono": "^4.12.2",
     "openapi-types": "^12.1.3",
     "yaml": "^2.8.3",
     "zod": "^4.3.6"

package/src/CLAUDE.md

@@ -0,0 +1,112 @@
+# src/ — architecture map
+
+Этот файл — точка входа в **код** zond. Workspace-контракт (`.api-fixtures.yaml` vs `.env.yaml`) — в [`../AGENTS.md`](../AGENTS.md), пользовательский CLI-референс — в [`../ZOND.md`](../ZOND.md).
+
+zond — API hygiene scanner. **Dumb-tool**: умеет дёргать API, собирать evidence, проверять конформность спеки. Не зовёт LLM, не делает решения — это работа агента, который скармливает zond'у YAML и читает обратно отчёты.
+
+### Litmus-тест: что кладём в zond, а что оставляем агенту
+
+m-24 срезал эвристический слой (discovery/seed/cascade, severity-калибраторы, anti-FP-гейты, annotate-auto). Чтобы он не наползал обратно по одному «разумному» фиксу за раз — **каждое изменение zond проходит один тест: детерминировано ли оно?** Один и тот же вход → один и тот же выход, без догадок про намерение / вину / серьёзность / «баг ли это на самом деле».
+
+- ✅ **В zond** (детерминированное, быстрое, скучное): слать запросы, валидировать схемы, считать диффы, эмитить evidence + closed-enum хинты, **корректно ограничивать scope чека** (какие case-kinds / методы он оценивает), плюс plumbing/скорость/артефакты. zond — удобный работающий быстрый инструмент.
+- ❌ **Агенту** (суждение): severity, приоритет, атрибуция вины (spec vs backend), «это false-positive?», «это эксплуатируемо?», выдумывание фикстур, многопроходный discovery. Сложное решает умный агент, читая сырой evidence.
+
+Практическое следствие для «zond что-то пропустил/зашумил» из аудита: **чини scope чека детерминированно** (напр. ARV-340 — чек смотрел не те case-kinds) — но **не добавляй suppression/down-rank «это FP»** (это ровно тот anti-FP-гейт, что убрал ARV-337; FP отсекает агент в триаже). `recommended_action` — самая размытая из выживших поверхностей: это тонкий routing-хинт, держи его тупым, не выращивай в мини-классификатор.
+
+**Evidence-over-inference (ARV-376):** статические инференсеры по форме URL (какой `/list` владеет `{id}`, какой ресурс за `{code}`) имеют бесконечный хвост идиосинкразий спеков. **Не** закрывай хвост растущими хардкод-списками маркеров/глаголов (`LIST_VERB_SUFFIXES`, `ACCESSOR_MARKER_SEGS`, версии) — это ровно тот creep «по одному разумному за раз». Правило: **новый маркер/глагол добавляется только под реальный спек, который его упражняет**, никогда «на всякий случай» (так был убран спекулятивный `bycode`). А когда вывод неуверенный — не тупик (`miss-no-list`), а **`item.candidates`**: правдоподобные эндпоинты, ранжированные по структурной близости, БЕЗ выбора значения. Граф — детерминизм zond'а; выбор — суждение агента. Выравнивание двух слоёв, где один уже что-то делает (напр. version-strip, ARV-381), — это консистентность, не новое знание, и ок.
+
+## Top-level layout
+
+| Каталог | Назначение |
+|---|---|
+| `cli/` | CLI surface: парсинг argv, регистрация команд, форматирование вывода. |
+| `core/` | Бизнес-логика: probes, checks, generators, runner, reporters. **Никакой зависимости от commander/process.argv** — это переиспользуемое ядро. |
+| `db/` | SQLite-слой: schema, migrations, queries для истории runs/results. |
+
+**Правило**: `cli/commands/<cmd>.ts` парсит флаги и зовёт функции из `core/`. Бизнес-логика в `cli/` — code-smell (см. ARV-257 про `bootstrap.ts`/`discover.ts`, которые лежат в `cli/commands/` но не регистрируют команды).
+
+## cli/
+
+| Файл | Что |
+|---|---|
+| `index.ts` | Entry point бинаря. |
+| `program.ts` | Commander root: регистрирует все top-level команды. |
+| `argv.ts`, `resolve.ts` | Аргумент-парсинг и `--api` chain resolution (per-command > global > `ZOND_API` > `.zond/current-api`). |
+| `runtime.ts` | Глобальный runtime context (`api`, workspace paths, http auditor). |
+| `output.ts`, `json-envelope.ts`, `json-schemas.ts` | Forматирование результатов: текстовый/JSON envelope + Ajv-валидация envelope-схем. |
+| `status-filter.ts` | Общий парсер `--status` фильтров. |
+| `commands/` | Один файл на команду; `commands/init/`, `commands/api/`, `commands/probe/` — кластеры с subcommands. |
+
+Контракт команды: парсит флаги, валидирует через зависимости из `core/`, эмиттит результат через `output.ts` (envelope) или streaming-репортер.
+
+## core/ — подсистемы
+
+| Подкаталог | Роль |
+|---|---|
+| `parser/`, `spec/` | Парсинг OpenAPI, dereferenced spec.json, extraction схем. |
+| `generator/` | Синтез тестовых YAML-сьютов из spec: `suite-generator.ts`, `data-factory.ts`, `resources-builder.ts`. |
+| `runner/` | HTTP-исполнение: `executor.ts`, retry, assertions, schema validation. |
+| `checks/` | Schemathesis-style depth checks (status_code_conformance, response_schema_conformance, idempotency, …). Орк — `checks/runner.ts`. Один файл = один check class. |
+| `probe/` | Активные security/mass-assignment probes. Сейчас два монолита (`security-probe.ts`, `mass-assignment-probe.ts`) — кандидаты на split (ARV-295, ARV-296). |
+| `lint/` | Static spec-lint (`check spec`). Не путать с `checks/` — это разные команды и разные envelope'ы. |
+| `diagnostics/` | Triage финдингов: классификация ошибок, hints, `recommended_action` mapping. |
+| `severity/` | Per-finding severity calibration (ARV-283–288 актуализирует). |
+| `anti-fp/` | Anti-false-positive guard'ы; registry-pattern частично (см. ARV-259). |
+| `coverage/` | Покрытие endpoint'ов: test-runs + audit-runs, dual-metric. |
+| `reporter/` | Форматирование `Run`/`Check`/`Probe` результатов в текст/JSON/NDJSON/SARIF/JUnit/HTML. |
+| `exporter/` | HTML-отчёты, case studies. |
+| `audit/` | Высокоуровневая `audit` команда — wraps checks + probe + report для CI-smoke. |
+| `workspace/` | Layout API-папки: `apis/<name>/{spec,catalog,resources,fixtures,env,secrets}`. |
+| `context/`, `identity/`, `secrets/` | Загрузка контекста запуска, identity tokens, секреты. |
+| `util/`, `utils.ts` | Общие хелперы. URL/headers/schema-валидация частично дублируются с `probe/shared.ts` — кандидат на консолидацию (ARV-297). |
+| `selectors/`, `meta/`, `classifier/` | Endpoint-classification и meta-аттрибуты для дискавери и группировки. |
+| `setup-api.ts` | Регистрация нового API в workspace (used by `add api`/`refresh-api`). |
+
+## db/
+
+SQLite на bun. `migrations/` — versioned migrations, `schema.ts` — текущий schema, `queries/` — типизированные SQL. Используется reporter'ами и `coverage` для исторических runs. Retention (ARV-266): `zond db stats` — счётчики строк per `run_kind`; `zond db prune` — opt-in удаление (per-kind defaults: check/probe/request/fixture старше 7d, `regular` — forever; `--older-than 30d` для uniform-cutoff), VACUUM после delete.
+
+## Data-flow по фазам
+
+zond работает по 5 фазам — это ментальная модель CLI и skills:
+
+```
+Setup ──► Generate ──► Run ──► Analyze ──► Report
+```
+
+| Фаза | Команды | Что происходит | Артефакты |
+|---|---|---|---|
+| **Setup** | `init`, `add api`, `refresh-api`, `use`, `doctor`, `prepare-fixtures` | Регистрируем API, тянем spec, заполняем `.env.yaml`. | `apis/<name>/{spec.json, .api-catalog.yaml, .api-resources.yaml, .api-fixtures.yaml, .env.yaml}` |
+| **Generate** | `generate`, `api annotate`, `prepare-fixtures` | Синтез тестовых YAML из spec + аннотации (seed-bodies, idempotency, pagination, lifecycle). | `apis/<name>/tests/*.yaml`, annotations |
+| **Run** | `run`, `session`, `request`, `audit`, `checks run`, `probe <class>` | Дергаем API: тесты, depth-checks, probes. Пишем runs/results в SQLite. | `runs/` (DB), HTTP-аудит |
+| **Analyze** | `coverage`, `db {runs,run,collections,diagnose,compare}`, `check spec`, `describe`, `catalog` | Триаж результатов, coverage-гэпы, lint спеки. Финдинги через `recommended_action`. | Envelope JSON, finding-streams |
+| **Report** | `report`, `report-bundle`, `--report {json,ndjson,sarif,junit,html,markdown}` | Конвертация runs/findings в shareable форматы. | NDJSON-stream, SARIF, HTML, JUnit |
+
+Полная картина с iron-rules и pre-flight checklist'ами — в skill-документах (`src/cli/commands/init/templates/skills/*.md`), которые ставятся через `zond init`.
+
+## Extension points
+
+Когда добавляешь новую функциональность — это **типичные точки расширения**:
+
+| Хочу добавить | Куда |
+|---|---|
+| Новый depth-check (schemathesis-style) | `core/checks/checks/<name>.ts` + регистрация в `core/checks/runner.ts`. |
+| Новый probe-class (security/mass-assignment-like) | `core/probe/<class>/` подмодуль; subcommand в `cli/commands/probe/`. Не клади всё в один монолит — см. ARV-295/ARV-296. |
+| Новый reporter format | `core/reporter/<format>.ts`; зарегистрировать в `cli/output.ts` или per-command `--report`. |
+| Новый CLI флаг с envelope-выводом | `cli/commands/<cmd>.ts` + Ajv-схема в `cli/json-schemas.ts`. Envelope shape — единый, не плоди вариации. |
+| Анти-FP guard для check/probe | `core/anti-fp/rules/<rule>.ts` (registry-pattern в развитии — ARV-259). |
+| Новая diagnostic-hint | `core/diagnostics/` — closed-enum `recommended_action`, не магические строки. |
+| Новая DB-сущность | `src/db/migrations/<NNNN>-<name>.sql` + tiped query в `db/queries/`. |
+
+## Workspace contract (ссылка)
+
+Артефакты в `apis/<name>/` (`spec.json` / `.api-catalog.yaml` / `.api-resources.yaml` / **`.api-fixtures.yaml` manifest** / **`.env.yaml` values**) — описаны в [`../AGENTS.md`](../AGENTS.md). Главное правило: **manifest — source of truth о списке переменных, env — только values**.
+
+## Conventions
+
+- TypeScript strict mode, `bun run check` = `tsc --noEmit` без warnings (`noUnusedLocals`/`noUnusedParameters` включены).
+- Тесты — `bun test` (unit + integration), `bun run test:mocked` (HTTP-mocked).
+- Сборка — `bun run build` → single-file `dist/zond` бинарь.
+- Никаких `console.log` в `core/` — выводи через `cli/output.ts` или reporter slot.
+- Никаких SDK Anthropic/Ollama/прочих LLM-провайдеров внутри zond — это dumb-tool (см. `feedback_zond_no_llm_calls`).
+- Финдинги — через closed-enum `recommended_action`, агент триажит по enum, не по тексту message.

package/src/cli/argv.ts

@@ -0,0 +1,122 @@
+/**
+ * Pre-commander argv handling and shared argument parsers used across the
+ * commander tree. Pulled out of program.ts (TASK-190, m-11) so program.ts
+ * shrinks toward "just command registration" and these helpers can be
+ * unit-tested in isolation.
+ */
+
+import { InvalidArgumentError } from "commander";
+import type { ReporterName } from "../core/reporter/types.ts";
+
+// ── MSYS path preprocessing ──
+//
+// Git Bash on Windows converts API paths like "/users" → "C:/Program Files/Git/users".
+// We reverse that for flags whose values are API paths, not filesystem paths.
+
+const MSYS_PREFIX_RE = /^[A-Z]:[\\/](?:Program Files[\\/]Git|msys64|usr)[\\/]/i;
+
+const API_PATH_FLAGS = new Set(["--path", "--json-path"]);
+
+function stripMsysPath(value: string): string {
+  if (!MSYS_PREFIX_RE.test(value)) return value;
+  return value.replace(MSYS_PREFIX_RE, "/");
+}
+
+/**
+ * Pre-process argv before commander sees it: undo Git Bash's MSYS path conversion
+ * for `--path` and `--json-path` values (both `--path X` and `--path=X` forms).
+ */
+export function preprocessArgv(argv: string[]): string[] {
+  const out = [...argv];
+  for (let i = 0; i < out.length; i++) {
+    const arg = out[i]!;
+
+    // --flag=value form
+    const eqIdx = arg.indexOf("=");
+    if (arg.startsWith("--") && eqIdx !== -1) {
+      const flag = arg.slice(0, eqIdx);
+      if (API_PATH_FLAGS.has(flag)) {
+        out[i] = `${flag}=${stripMsysPath(arg.slice(eqIdx + 1))}`;
+      }
+      continue;
+    }
+
+    // --flag value form
+    if (API_PATH_FLAGS.has(arg)) {
+      const next = out[i + 1];
+      if (next !== undefined && !next.startsWith("-")) {
+        out[i + 1] = stripMsysPath(next);
+      }
+    }
+  }
+  return out;
+}
+
+// ── Argument parsers ──
+
+export function parsePositiveInt(name: string): (raw: string) => number {
+  return (raw: string) => {
+    const n = Number.parseInt(raw, 10);
+    if (Number.isNaN(n) || n <= 0) {
+      throw new InvalidArgumentError(`Invalid ${name} value: ${raw}`);
+    }
+    return n;
+  };
+}
+
+/** `--rate-limit` accepts a positive integer (req/sec cap) or the literal
+ *  string `auto` (no static cap; throttle adaptively from ratelimit-* headers). */
+export function parseRateLimit(raw: string): number | "auto" {
+  if (raw.toLowerCase() === "auto") return "auto";
+  const n = Number.parseInt(raw, 10);
+  if (Number.isNaN(n) || n <= 0) {
+    throw new InvalidArgumentError(`Invalid --rate-limit value: ${raw} (expected a positive integer or "auto")`);
+  }
+  return n;
+}
+
+export function parseNonNegativeInt(name: string): (raw: string) => number {
+  return (raw: string) => {
+    const n = Number.parseInt(raw, 10);
+    if (Number.isNaN(n) || n < 0 || String(n) !== raw.trim()) {
+      throw new InvalidArgumentError(`Invalid ${name} value: ${raw} (expected a non-negative integer)`);
+    }
+    return n;
+  };
+}
+
+export function parseInteger(name: string): (raw: string) => number {
+  return (raw: string) => {
+    const n = Number.parseInt(raw, 10);
+    if (Number.isNaN(n)) {
+      throw new InvalidArgumentError(`Invalid ${name} value: ${raw}`);
+    }
+    return n;
+  };
+}
+
+export function parsePercentage(raw: string): number {
+  const n = Number.parseInt(raw, 10);
+  if (Number.isNaN(n) || n < 0 || n > 100) {
+    throw new InvalidArgumentError(`Invalid --fail-on-coverage value: ${raw} (must be 0–100)`);
+  }
+  return n;
+}
+
+export const collect = (val: string, prev: string[]): string[] => [...prev, val];
+
+const VALID_REPORTERS = new Set<string>(["console", "json", "junit"]);
+
+export function parseReporter(raw: string): ReporterName {
+  if (!VALID_REPORTERS.has(raw)) {
+    throw new InvalidArgumentError(`Unknown reporter: ${raw}. Available: console, json, junit`);
+  }
+  return raw as ReporterName;
+}
+
+/** Helper: split repeatable values like ["a,b", "c"] → ["a", "b", "c"] */
+export function flatSplit(values: string[] | undefined): string[] | undefined {
+  if (!values || values.length === 0) return undefined;
+  const out = values.flatMap((v) => v.split(",")).filter(Boolean);
+  return out.length > 0 ? out : undefined;
+}

package/src/cli/commands/add-api.ts

@@ -0,0 +1,146 @@
+/**
+ * `zond add api <name> --spec <path|url>` — register a new API in the
+ * current workspace.
+ *
+ * The split from `zond init --spec` exists so the two operations
+ * (workspace bootstrap vs. API registration) have separate names and
+ * separate skill mentions. `init --spec` still works as a deprecated
+ * alias.
+ *
+ * This command refuses to run when no workspace marker is present,
+ * pointing the user at `zond init` first. setupApi handles spec
+ * snapshot + artifact generation.
+ */
+
+import { setupApi, type SetupApiResult } from "../../core/setup-api.ts";
+import { findWorkspaceRoot } from "../../core/workspace/root.ts";
+import { jsonOk, jsonError, printJson, zerr } from "../json-envelope.ts";
+import { printError, printSuccess } from "../output.ts";
+
+export interface AddApiOptions {
+  name: string;
+  /** One or more specs. Multiple → deterministic union (ARV-375). */
+  specs?: string[];
+  baseUrl?: string;
+  dir?: string;
+  force?: boolean;
+  insecure?: boolean;
+  caPath?: string;
+  dbPath?: string;
+  json?: boolean;
+}
+
+export async function addApiCommand(opts: AddApiOptions): Promise<number> {
+  const ws = findWorkspaceRoot();
+  if (ws.fromFallback) {
+    const m = `No workspace detected (no zond.config.yml / .zond / apis marker). Run \`zond init\` first to bootstrap a workspace.`;
+    if (opts.json) printJson(jsonError("add-api", [m])); else printError(m);
+    return 2;
+  }
+
+  const envVars: Record<string, string> = {};
+  if (opts.baseUrl) envVars.base_url = opts.baseUrl;
+
+  const hasSpec = (opts.specs?.length ?? 0) > 0;
+  let result: SetupApiResult;
+  try {
+    result = await setupApi({
+      name: opts.name,
+      specs: opts.specs,
+      dir: opts.dir,
+      envVars: Object.keys(envVars).length > 0 ? envVars : undefined,
+      dbPath: opts.dbPath,
+      force: opts.force,
+      insecure: opts.insecure,
+      caPath: opts.caPath,
+    });
+  } catch (err) {
+    const m = (err as Error).message;
+    // Tag known spec-ingest failures with a structured code so downstream
+    // tooling (skills, retry logic) can branch on it (ARV-145). Cyclic
+    // structures escape decycleSchema only when @readme/openapi-parser
+    // builds an unusual graph — surface that as spec_load_failure with a
+    // pointer to the underlying serializer message.
+    const isCycleError = /cyclic structures|spec_serialize_failed/i.test(m);
+    const errInput = isCycleError ? zerr("spec_load_failure", m) : m;
+    if (opts.json) printJson(jsonError("add-api", [errInput])); else printError(m);
+    return 2;
+  }
+
+  const mode: "spec" | "run-only" = hasSpec ? "spec" : "run-only";
+  const artifacts = mode === "spec"
+    ? ["spec.json", ".api-catalog.yaml", ".api-resources.yaml", ".api-fixtures.yaml", ".env.yaml"]
+    : [".env.yaml"];
+
+  if (opts.json) {
+    printJson(jsonOk("add-api", {
+      api: opts.name,
+      mode,
+      collectionId: result.collectionId,
+      baseDir: result.baseDir,
+      testPath: result.testPath,
+      endpoints: result.specEndpoints,
+      artifacts,
+    }, result.warnings));
+  } else {
+    if (mode === "spec") {
+      printSuccess(`Registered API '${opts.name}' at ${result.baseDir} (${result.specEndpoints} endpoints)`);
+      process.stdout.write(`  Artifacts: spec.json + .api-catalog.yaml + .api-resources.yaml + .api-fixtures.yaml\n`);
+      if (result.authVars && result.authVars.length > 0) {
+        const list = result.authVars.map((v) => `\`${v}\``).join(", ");
+        process.stdout.write(`  Auth required: fill ${list} in ${result.baseDir}/.secrets.yaml (already wired via @secret in .env.yaml).\n`);
+      }
+      process.stdout.write(`  Next: run \`zond doctor --api ${opts.name}\` to see required fixtures.\n`);
+    } else {
+      printSuccess(`Registered API '${opts.name}' at ${result.baseDir} (no spec — run-only mode)`);
+      process.stdout.write(`  Artifacts: .env.yaml (base_url=${opts.baseUrl})\n`);
+      process.stdout.write(`  Next: write tests in ${result.testPath}/, run \`zond run --api ${opts.name} <test.yaml>\`.\n`);
+      process.stdout.write(`  To enable generate/probe/validate-schema, attach a spec: \`zond refresh-api ${opts.name} --spec <path|url>\`.\n`);
+    }
+    if (result.warnings) for (const w of result.warnings) process.stderr.write(`Warning: ${w}\n`);
+  }
+  return 0;
+}
+
+import type { Command } from "commander";
+import { globalJson } from "../resolve.ts";
+
+export function registerAdd(program: Command): void {
+  const add = program.command("add").description("Register objects in the workspace");
+  add
+    .command("api <name>")
+    .description("Register an API: from an OpenAPI spec (full toolkit) or just --base-url (run-only mode)")
+    .option(
+      "--spec <path>",
+      "Path or URL to OpenAPI spec — enables generate/probe/validate-schema. Repeat --spec to union multiple specs (e.g. v1 + v2) into one merged audit target (ARV-375).",
+      (val: string, acc: string[]) => acc.concat(val),
+      [] as string[],
+    )
+    .option("--base-url <url>", "Base URL recorded in .env.yaml (required if --spec is omitted)")
+    .option("--dir <path>", "Target directory (defaults to apis/<name>/)")
+    .option("--force", "Overwrite an existing API with the same name")
+    .option("--insecure", "Skip TLS verification when fetching the spec from https")
+    .option("--ca <path>", "PEM CA bundle to trust for the spec fetch (adds to public roots; also reads NODE_EXTRA_CA_CERTS) — use instead of --insecure for internal/corp CAs")
+    .option("--db <path>", "Path to SQLite database file")
+    .action(async (name: string, opts, cmd: Command) => {
+      const json = globalJson(cmd);
+      const specs: string[] = Array.isArray(opts.spec) ? opts.spec : (opts.spec ? [opts.spec] : []);
+      if (specs.length === 0 && !opts.baseUrl) {
+        const m = "Provide --spec <path|url> for a full registration, or --base-url <url> for run-only mode.";
+        if (json) printJson(jsonError("add-api", [m])); else printError(m);
+        process.exitCode = 2;
+        return;
+      }
+      process.exitCode = await addApiCommand({
+        name,
+        specs,
+        baseUrl: opts.baseUrl,
+        dir: opts.dir,
+        force: opts.force === true,
+        insecure: opts.insecure === true,
+        caPath: typeof opts.ca === "string" ? opts.ca : undefined,
+        dbPath: typeof opts.db === "string" ? opts.db : undefined,
+        json,
+      });
+    });
+}

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

@@ -0,0 +1,59 @@
+/**
+ * ARV-187 / idempotency: parser + expected shape.
+ */
+
+import { z } from "zod";
+import type { ResourcePatch } from "./overlay.ts";
+import type { ResourceSlice } from "./prompts.ts";
+
+const IdempotencySchema = z.object({
+  header: z.string().default("Idempotency-Key"),
+  scope: z.enum(["endpoint", "global"]).optional(),
+  ignore_response_fields: z.array(z.string()).optional(),
+});
+
+const ResponseSchema = z.object({
+  resource: z.string(),
+  idempotency: IdempotencySchema.nullable(),
+  rationale: z.string().optional(),
+  confidence: z.enum(["low", "medium", "high"]).optional(),
+});
+
+export const EXPECTED_OUTPUT_SHAPE = {
+  resource: "string (echo input)",
+  idempotency: {
+    header: "string (header name, e.g. 'Idempotency-Key')",
+    scope: "endpoint | global (optional)",
+    ignore_response_fields: "string[] (optional — fields that change between replays, e.g. 'created')",
+  },
+  rationale: "string (optional)",
+  confidence: "low | medium | high",
+  null_form: "if create endpoint doesn't support idempotency-replay, return { resource, idempotency: null }",
+};
+
+export function parseIdempotencyResponse(parsed: unknown, slice: ResourceSlice): { patch: ResourcePatch; audit: Record<string, unknown> } {
+  const validated = ResponseSchema.safeParse(parsed);
+  if (!validated.success) {
+    throw new Error(`idempotency response failed schema for ${slice.resource}: ${validated.error.message}`);
+  }
+  const v = validated.data;
+  if (v.idempotency == null) {
+    return {
+      patch: { resource: slice.resource },
+      audit: { resource: slice.resource, rationale: v.rationale, confidence: v.confidence, dropped: "no Idempotency-Key support" },
+    };
+  }
+  return {
+    patch: {
+      resource: slice.resource,
+      idempotency: {
+        header: v.idempotency.header,
+        scope: v.idempotency.scope,
+        ignore_response_fields: v.idempotency.ignore_response_fields,
+      },
+    },
+    audit: { resource: slice.resource, rationale: v.rationale, confidence: v.confidence },
+  };
+}
+
+export function isApplicable(slice: ResourceSlice): boolean { return Boolean(slice.endpoints.create); }