@kirrosh/zond 0.23.0 → 0.26.0

package/CHANGELOG.md

@@ -4,7 +4,170 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
-(Empty — next development cycle.)
+## [0.26.0] — 2026-07-09
+
+Deterministic gap-fills surfaced by a docgen-core-service audit — all pass the
+litmus test (same input → same output, no severity/FP/blame judgment). Plus an
+m-25 distribution cleanup that collapses the workspace layout to one convention.
+
+### Added
+- **Multi-spec merge (ARV-375):** `zond add api <name> --spec a --spec b …`
+  unions N specs into one audit target. Deterministic last-wins on path /
+  component collisions, surfaced as warnings (path collisions + same-name /
+  different-shape schema collisions). Core in `src/core/spec/merge-specs.ts`.
+- **`zond secrets set <key> <value>` (ARV-377):** writes `apis/<name>/.secrets.yaml`
+  with a `.bak` backup, never echoes the value, and auto-strips a pasted
+  `Bearer ` prefix (`--literal` keeps it verbatim). Closes the "hand-rolled
+  python to rotate an expired token" gap and ARV-367/AC3.
+- **`zond db diagnose --union <spec>` (ARV-380):** aggregate
+  `by_recommended_action` (+ summary counts, deduped examples) across a run
+  set, reusing coverage's `--union` vocabulary (`session` / `since:<dur>` /
+  `tag:<name>` / `runs:<ids>`). `--api` scopes `since:`/`tag:` to a collection.
+- **Coverage deprecated flags (ARV-379):** `coverage --json` now carries a
+  per-entry `deprecated` boolean on the `*Endpoints` bucket arrays plus a
+  top-level `deprecatedEndpoints` list, so a consumer can split "real gap"
+  from "deprecated, skip by design" without re-reading spec.json.
+
+### Fixed
+- **`db diagnose --union` version follow-up + candidate-surfacing (ARV-381/382):**
+  disambig's parent-walk now skips version segments (`/v30/{code}`), aligning
+  with `owningCollectionForPathParam` which already strips them — resolves the
+  `_v30_code` miss-no-list class. And when prepare-fixtures can't confidently
+  derive an owner list, the item carries `candidates[]` — plausible GET/list
+  endpoints ranked by proximity (deprecated ones marked) — instead of
+  dead-ending; zond surfaces the evidence, the agent picks the value. On
+  docgen-core-merged: `miss-no-list` 40 → 22 total, 9 of those now carry
+  candidates, the rest are honest dead-ends (no listable source in the spec).
+- **Resource graph misses `/list`-style owners (ARV-376):** `resolveOwnerListPaths`
+  now links `/list` (and `/search`, `/find`) endpoints to their sibling
+  `/{code}` and `/byid/{id}` params; the `byid` accessor marker no longer
+  collapses every read-by-id param into one global `byid_id`; a malformed spec
+  whose path template (`/byid/{id}`) disagrees with the declared param name
+  (`byid_id`) is reconciled to the template; secondary lookup keys (`{code}`)
+  surface as candidates. On the docgen-core-merged spec this cut
+  prepare-fixtures `miss-no-list` from 40 → 30.
+- **`fixtures add` batch (ARV-378):** confirmed `fixtures add <pairs...>`
+  already applies N `key=value` pairs in one call (one write + one `.bak`) —
+  no shell loop needed.
+
+### Removed
+- **Flat `zond.db` workspace layout (m-25):** dropped the legacy root-level
+  `zond.db` marker and its implicit default-DB resolution. The DB now lives
+  only at `.zond/zond.db`; `zond.config.yml` / `.zond/` / `apis/` remain the
+  workspace markers. Migrate an old workspace with `mv zond.db .zond/` (or
+  re-`zond init`); an explicit `--db <path>` still opens any file. Removes the
+  dual-layout confusion that let a root `zond.db` and `.zond/zond.db` coexist.
+- **Dead `benchmarks/` references (m-25):** pruned the never-committed
+  `benchmarks/**` entries from `knip.json` and the dead `bench:api` script from
+  `package.json` (`knip` is now clean).
+
+## [0.25.0] — 2026-07-07
+
+m-24: **rebuild around the agent.** zond becomes a set of deterministic
+dumb tools — it sends requests, validates schemas, stores and diffs runs,
+and reports gaps. The autonomous heuristic layer that produced most of the
+0.24 bug-stream (auto-discovery/seed/cascade, annotate-auto guess-engine,
+severity calibrators, anti-FP suppression) is removed; the agent now owns
+every judgment call (severity, spec-vs-backend blame, "is this a false
+positive?", which value fills a fixture). The deterministic core —
+send → validate → store → diff — survives intact. A litmus test in
+`src/CLAUDE.md` keeps the heuristic layer from creeping back one
+"reasonable" fix at a time: same input → same output, or it's the agent's.
+
+### Removed (heuristic layer)
+- **Autonomous fixture seed/cascade engine gone (ARV-336):** `bootstrap.ts`
+  + `create-body.ts` deleted. Live-POST resource creation guessed bodies and
+  cascaded parent→child (1% success on Stripe). prepare-fixtures is now
+  single-pass verify + gap-report; the agent (or user) creates resources.
+- **Severity calibrators + anti-FP suppression gate removed (ARV-337 Cut A):**
+  severity is agent judgment; anti-FP `applyAntiFp` no longer gates emission —
+  the rule reasons survive as raw evidence, not as a suppress-or-emit verdict.
+- **annotate-auto guess-engine removed (ARV-337 Cut B):** `inferSeedBody`
+  fabricated bodies from format/name fallbacks and self-ranked confidence.
+  annotate now dumps the spec slice; the agent authors the YAML, zond
+  validates and merges.
+
+### Agent-facing artifacts & new mechanics
+- **YAML run summary (ARV-338):** `zond db diagnose` drops prose hints (keeps
+  the mechanical counts/grouping spine); `db … --report yaml` emits
+  agent-friendly output.
+- **Field-level run diff (ARV-339):** `zond db compare` now diffs response
+  body/schema per field, not just status.
+- **prepare-fixtures gap report (ARV-349/350):** undefined vars + unseeded
+  capture-chain roots are reported deterministically — no auto-seed.
+- **Agent-orchestrated auto-seed (ARV-355):** `zond request --capture` +
+  `zond-seed` skill — the agent reasons about creation order, zond executes.
+- **Ambiguous-id guard (ARV-334):** the hint-less fixture harvest reports
+  `miss-ambiguous-id` (naming the candidate string field) instead of silently
+  putting a numeric `id` into a string slot like `{owner}` — zond flags the
+  ambiguity, the agent/annotation picks the field.
+- **generate preserves hand-edits (ARV-361):** suite files whose auto-gen
+  header was removed are treated as agent-owned and preserved on regenerate;
+  `--force` overwrites them (was a documented no-op).
+
+### Checks, probes & safety
+- **`--safe`/`--live` parity (ARV-299)** across `checks run` and `probe`.
+- **stateful scope (ARV-325):** `--check stateful` expands to the
+  state-machine set only.
+- **cascade fast-fail (ARV-326):** prepare-fixtures aborts early on a
+  dead/scoped-wrong token instead of grinding through futile attempts.
+- **input-triggered 5xx caught (ARV-340/341):** self-generated body rejects
+  route to `fix_spec`, not `report_backend_bug`.
+- **child-exclude wired (ARV-330):** the last-attempt history lookup uses the
+  all-run-kinds query + child-exclude pattern so probe sub-resource POSTs
+  (`/v1/accounts/{id}/reject`) don't starve the real create-path window.
+- **checks reporting fixes (ARV-322/323/328):** suppressed-count accuracy,
+  SIGTERM ndjson counting, throttled stderr progress on long runs.
+
+### Sweeps & infrastructure
+- **Bounded/resumable sweeps (ARV-342):** `--skip-ops` / `--max-ops` op-window.
+- **DB retention (ARV-266):** `zond db prune` + `zond db stats`, per-run-kind
+  cutoffs, VACUUM after delete.
+- **Schema from observed runs (ARV-175/176):** `schema-from-runs` command +
+  `refresh-api --merge-schema` — union/required-intersection from real
+  responses, not guessing.
+
+### Report, triage & audit-run cleanup
+- Report-noise, severity and UX cleanup (ARV-343/344/345/346/348/351/353);
+  compare scope tag, partial summary on SIGTERM, triage depth aggregate
+  (ARV-352/354).
+- Empty-dir `zond run --output` writes a `0 tests` envelope instead of no
+  file (ARV-357); cross-phase double-emit documented for triage (ARV-358).
+- Workspace-leak fix (env-independent audit paths) + self-compare guard
+  (ARV-359/360), from a petstore audit-run.
+
+## [0.24.0] — 2026-07-03
+
+m-22 validation sprint. No new milestone surface — this release hardens the
+0.23.0 depth-checks/probe/audit stack against real APIs. ~40 fixes (ARV-260..332)
+were found by running `zond audit`/`zond-scan` live against Stripe, GitHub,
+Resend and docgen-core, not by unit tests.
+
+### Safety & contracts
+- **Safe-mode leak closed (ARV-332):** `checks run --check stateful --include
+  method:GET` no longer fires POST create-chains — CRUD groups are built from
+  the filtered op set, so `ensure_resource_availability`/`use_after_free`
+  self-skip when no write is in scope. Critical for scanning APIs you don't own.
+- Exit-code contract hardened (ARV-303/307/308/309/310): audit judges stages on
+  `envelope.ok`, not raw exit code; budget-exhaust distinguished from network error.
+- `open_cors_on_sensitive` HIGH only on 2xx + ambient (cookie) credential
+  (ARV-312/316) — kills a class of false HIGHs.
+
+### Severity calibration
+- Probe-side severity calibrator (ARV-283/300): `SecuritySeverity ↔ Severity`
+  adapter with sentinel passthrough; wired into security probe. mass-assignment/
+  static/webhooks tracked in ARV-311.
+
+### Fixture / seed pipeline
+- FK-aware body builder wires reference fields to fixtures (ARV-45).
+- Topological seed order + body-FK deferral (ARV-324/327); gap-report flags
+  unfillable complex root resources instead of silently skipping (ARV-329/330).
+
+### Ops & workflow
+- `ZOND_WORKSPACE` honored; `zond-audit` workflow added for reproducible runs.
+- ndjson reporter stability (ARV-314/318/320/322); path-casing canonicalized
+  before workspace-root walk (ARV-315).
+- Repo-wide ponytail cleanup: dead code removed, probe monoliths deduped.
 
 ## [0.23.0] — 2026-05-15
 

package/README.md

@@ -21,12 +21,12 @@ Bootstrap a workspace, register your first API, then fill its fixtures:
 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 --apply [--seed]    # fill apis/my-api/.env.yaml from live API
+zond prepare-fixtures --api my-api                     # gap report: verify fixtures + which FK vars need a value
 ```
 
-For path-FK ids that auto-discover/--seed can't reach (vendor-dashboard
-ids like `cus_*`, GitHub PR numbers, Sentry issue ids), use the manual
-helpers (ARV-195):
+`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
@@ -46,9 +46,10 @@ Each registered API gets four files in `apis/<name>/`:
 - `.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 (or `zond prepare-fixtures`) fill with
-the **values** for those vars. The manifest/values split is strict — see
-the [workspace contract](AGENTS.md#workspace-contract) for details.
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirrosh/zond",
-  "version": "0.23.0",
+  "version": "0.26.0",
   "description": "API testing platform — define tests in YAML, run from CLI, generate from OpenAPI specs",
   "license": "MIT",
   "module": "index.ts",
@@ -34,8 +34,7 @@
     "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 dist/zond && bun run scripts/codesign-darwin.ts ./dist/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",

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/commands/add-api.ts

@@ -19,11 +19,13 @@ import { printError, printSuccess } from "../output.ts";
 
 export interface AddApiOptions {
   name: string;
-  spec?: 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;
 }
@@ -31,7 +33,7 @@ export interface AddApiOptions {
 export async function addApiCommand(opts: AddApiOptions): Promise<number> {
   const ws = findWorkspaceRoot();
   if (ws.fromFallback) {
-    const m = `No workspace detected (no zond.config.yml / .zond / zond.db / apis marker). Run \`zond init\` first to bootstrap a workspace.`;
+    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;
   }
@@ -39,16 +41,18 @@ export async function addApiCommand(opts: AddApiOptions): Promise<number> {
   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,
-      spec: opts.spec,
+      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;
@@ -63,7 +67,7 @@ export async function addApiCommand(opts: AddApiOptions): Promise<number> {
     return 2;
   }
 
-  const mode: "spec" | "run-only" = opts.spec ? "spec" : "run-only";
+  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"];
@@ -106,15 +110,22 @@ export function registerAdd(program: Command): void {
   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")
+    .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);
-      if (!opts.spec && !opts.baseUrl) {
+      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;
@@ -122,11 +133,12 @@ export function registerAdd(program: Command): void {
       }
       process.exitCode = await addApiCommand({
         name,
-        spec: opts.spec,
+        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,
       });