@kirrosh/zond 0.21.0 → 0.22.0

package/CHANGELOG.md

@@ -2,12 +2,66 @@
 
 All notable changes to this project will be documented in this file.
 
-## [Unreleased] — fix/generator-quality-improvements
+## [0.22.0] — 2026-04-29
+
+### Round-2 papercuts (TASK-68 → TASK-86)
+
+- **TASK-68: `zond run --safe` (no path) no longer crashes with `paths[0] must be of type string, got boolean`.**
+  Commander's auto-negation `--no-db` defaulted `opts.db` to `true`; the boolean leaked into `path.resolve()` via a lazy
+  cast. dbPath is now normalised the same way as elsewhere; the no-path / no-`.zond-current` error is explicit and
+  mentions both `zond use <api>` and `--api`.
+
+- **TASK-69: `zond db diagnose` no longer hides 5xx failures behind cluster summaries.**
+  `groupFailures` previously kept only the first item per group plus 2 examples — for `assertion_failed` clusters that's
+  fine, but for `api_error` (5xx) it silently dropped backend-bug evidence. 5xx groups are now always preserved in full
+  in `data.failures` and `examples`; assertion/network groups continue to fold.
+
+- **TASK-71: YAML parse errors now report `file:line:col` plus a snippet with a column pointer.**
+  `Bun.YAML.parse` exposes JS-stack coordinates, not YAML positions — on failure we re-parse with `yaml` (eemeli) just
+  for diagnostics and surface `linePos` in the error. Pre-checks for embedded NUL bytes and points at the
+  `{{$nullByte}}` generator. Adds `yaml@2.8.3` dependency.
+
+- **TASK-77: suite-level `parameterize: { key: [val, …] }` cross-product.**
+  Replaces copy-pasting one test across N endpoints. Multiple keys produce the cross-product. Captures and
+  tainted/missing-capture state are reset between iterations so values from one binding never leak into the next; step
+  names are interpolated through `{{var}}` so reporters and `db diagnose` can tell iterations apart.
+
+- **TASK-79: `probe-validation` now pairs every mutating probe with a cleanup-DELETE.**
+  When a probe accidentally returns 2xx (the bug class probe-validation hunts for), the new follow-up `DELETE` step
+  (`always: true`) consumes a `leaked_id_<i>` capture and removes the resource. When the probe correctly gets 4xx, no id
+  is captured and the cleanup is skipped automatically. If the spec defines no DELETE counterpart, the generator emits a
+  warning instead. New `--no-cleanup` flag opts out for namespace-isolated test envs.
+
+- **TASK-81: `--rate-limit auto` reads `RateLimit-*` response headers and adapts.**
+  Implements RFC `draft-ietf-httpapi-ratelimit-headers` plus the GitHub/Stripe `X-RateLimit-*` aliases. When `remaining`
+  drops to ≤5, subsequent requests pause until reset (relative-seconds vs Unix-timestamp distinguished by magnitude).
+  Static `--rate-limit N` benefits from the same hook — the cap is a floor, headers can push pauses out further.
+
+- **TASK-86: `zond generate` honours `format` even when `type` is absent or array (OpenAPI 3.1 nullable).**
+  `format: email` on a schema with no `type` (or `type: ["string", "null"]`) used to fall through to the default branch
+  and produce `{{$randomString}}`. Format-to-placeholder mapping is now dispatched before the type switch.
 
 ### Breaking changes
 
-- **MCP layer removed** — `zond mcp` command and `@modelcontextprotocol/sdk` dependency deleted.
-  The agent interface is now exclusively the CLI + skills in `skills/`. No migration path needed.
+- **MCP layer removed** (see [decision-2](backlog/decisions/decision-2%20-%20Drop-MCP-server-—-keep-CLI-agent-skills-as-the-only-integration-surface.md)) —
+  CLI is the only integration surface; agent skills in `skills/*/SKILL.md`
+  are read directly. Specifically:
+  - `zond mcp start` removed.
+  - `zond install --claude/--cursor` removed (was only used to write
+    `~/.claude/mcp.json` / `~/.cursor/mcp.json` for the MCP transport).
+  - `--integration mcp` flag of `zond init` removed; default integration
+    is now `cli` (writes a self-contained `AGENTS.md` with full workflow
+    inline). `--integration skip` still works.
+  - `@modelcontextprotocol/sdk` runtime dependency dropped.
+  - `src/mcp/` deleted entirely (~817 LOC).
+  - `src/cli/commands/install.ts` and `src/cli/commands/mcp.ts` deleted.
+  - `tests/integration/mcp*.test.ts` removed.
+  - All MCP references purged from README, ZOND.md, docs/, skills/,
+    AGENTS.md, CLAUDE.md.
+  - Migration: existing `~/.claude/mcp.json` / `~/.cursor/mcp.json` keep
+    referencing a `zond` server that no longer responds; remove the
+    `zond` entry from your client config. New flow — see updated
+    `AGENTS.md`: agents call `zond` commands directly.
 
 - **`zond migrate` removed** — the migration system was added and then removed in the same branch.
   Format changes in zond are backward-compatible or require a clean `zond generate`.
@@ -100,6 +154,59 @@ All notable changes to this project will be documented in this file.
   of the expected `404` (after a DELETE), the diagnostic now surfaces a "likely soft delete" hint
   with a concrete suggestion to assert the status field value.
 
+- **5xx response highlighting** — console reporter now flags failed steps with HTTP 5xx
+  responses with a yellow `[5xx <status>]` tag, and the suite/grand-total lines show a
+  separate `<N> 5xx` count. The `--json` envelope adds `http_status` and `is_5xx` per
+  failure plus a top-level `summary.fiveXx` count, so probe-validation runs surface
+  bug candidates at a glance.
+
+- **`--report-out <file>`** on `zond run` — writes the JSON or JUnit report directly to a
+  file (with `mkdir -p`) instead of to stdout, logging `zond: <FORMAT> report written to
+  <path>` on stderr. Decouples the report from any wrapper banner that prefixes stdout
+  (notably `bun run zond -- run …`), so downstream JSON parsers don't break.
+
+#### Bug-hunting probes
+
+- **`zond probe-validation <spec>`** — generates deterministic negative-input probe
+  suites that catch the 5xx-on-bad-input class of bugs (the contract: any malformed
+  client input must produce a 4xx, never a 5xx). Per endpoint emits probes for: invalid
+  path UUIDs, empty body, missing required fields, type confusion, invalid format
+  (`email`/`uri`/`date-time`/`uuid`), boundary strings (empty, 10000-char,
+  unicode/emoji/RTL), invalid enum values and array-of-string-enum (catches the
+  webhooks-events bug shape). `--max-per-endpoint` caps probe count, `--tag` filters
+  endpoints. Generated suites embed suite-level `base_url`/auth and are runnable as-is.
+
+- **`zond probe-methods <spec>`** — HTTP method completeness sweep. For every path,
+  emits one probe per `{GET, POST, PUT, PATCH, DELETE}` method that is *not* declared
+  in the spec, expecting a 4xx (`401/403/404/405`). Path placeholders are substituted
+  with valid-shape sentinels so the request reaches the router. Catches "PUT on a
+  POST-only endpoint returns 500" bugs.
+
+- **`probe-validation --list-tags`** — lists all tags from the OpenAPI spec without
+  generating anything. `--tag X` is now case-insensitive and trims whitespace; matching
+  zero endpoints exits 2 with a clear error and the available-tags list.
+
+#### Runner
+
+- **`zond run --sequential`** — opt-out of parallel suite execution. Forces
+  sequential runs of all suites (useful when a setup token must propagate or when
+  rate-limits make parallel suites trigger 429s).
+
+- **Auto-load `./.env.yaml`** — `zond run` now also tries `$PWD/.env.yaml` when
+  `--env` is not given and neither searchDir nor its parent has one. Logs
+  `zond: using ./.env.yaml (cwd fallback)` on stderr. Unblocks running absolute test
+  paths from a collection cwd.
+
+#### Reporter / DB
+
+- **Cascade-skip reason inline** — console reporter now prints
+  `(skipped: <error>)` instead of just `(skipped)`, surfacing the underlying
+  capture/auth failure on the very same line.
+
+- **Run classification** — `zond db runs` now classifies a run with `total > 0`,
+  `passed == 0`, and many errors as **FAIL** instead of PASS. Prevents a probe run
+  with all 5xx responses from looking green in the runs listing.
+
 ---
 
 ### Fixes

package/README.md

@@ -4,35 +4,37 @@ AI-powered API testing for Claude Code, Cursor, and CI/CD.
 
 Say "test my API" — get working tests, coverage dashboard, and CI config in minutes.
 
-<!-- TODO: add demo GIF (15 sec: plugin install → "cover openapi.json with tests" → 42/47 endpoints covered → dashboard) -->
-
-Zond reads your OpenAPI spec and gives your AI agent everything it needs to test your API: structured tools, safety guardrails, coverage tracking, and run history. You don't need to learn anything new — just describe what you want and the agent handles the rest.
+Zond reads your OpenAPI spec and gives your AI agent everything it needs to test your API: a focused CLI, safety guardrails, coverage tracking, and run history. You don't need to learn anything new — just describe what you want and the agent runs `zond` commands.
 
 ## Quick Start
 
+Install the binary (no Node.js required):
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh   # macOS/Linux
+iwr https://raw.githubusercontent.com/kirrosh/zond/master/install.ps1 | iex        # Windows
 ```
-/plugin marketplace add kirrosh/zond
-/plugin install zond@zond-marketplace
+
+Bootstrap a workspace and register your first API:
+
+```bash
+zond init --workspace --with-spec ./openapi.json
 ```
 
-Then say: _"Safely cover the API from openapi.json with tests"_
+`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.
 
-You get auto-validation hooks and CLI tools — all in one package.
+Then say to your agent: _"Safely cover the API from openapi.json with tests."_
 
 <details>
-<summary>Other installation methods (CLI, binary)</summary>
-
-### CLI / Binary
+<summary>Other installation methods (npx)</summary>
 
 ```bash
 npx -y @kirrosh/zond --version
-
-# Standalone binary (no Node.js required)
-curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh   # macOS/Linux
-iwr https://raw.githubusercontent.com/kirrosh/zond/master/install.ps1 | iex        # Windows
 ```
 
-See [ZOND.md](ZOND.md) for full CLI reference.
+See [ZOND.md](ZOND.md) for the full CLI reference.
 
 </details>
 
@@ -67,11 +69,20 @@ Claude Code can write pytest from scratch — but it takes 30-60 minutes per flo
 "Set up CI for API tests"
 ```
 
+## Shell completions
+
+```bash
+zond completions bash > ~/.local/share/bash-completion/completions/zond
+zond completions zsh  > ~/.zsh/completions/_zond   # then `compinit`
+zond completions fish > ~/.config/fish/completions/zond.fish
+```
+
 ## Documentation
 
 - [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))
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirrosh/zond",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "API testing platform — define tests in YAML, run from CLI or WebUI, generate from OpenAPI specs",
   "license": "MIT",
   "module": "index.ts",
@@ -25,17 +25,20 @@
   },
   "scripts": {
     "zond": "bun run src/cli/index.ts",
+    "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/diagnostics/ tests/cli/args.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/guide.test.ts tests/integration/ tests/web/ tests/reporter/ tests/version-sync.test.ts",
+    "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:mocked": "bun run scripts/run-mocked-tests.ts",
     "check": "tsc --noEmit --project tsconfig.json",
+    "lint:dead": "knip --reporter compact",
     "build": "bun build --compile src/cli/index.ts --outfile zond",
-    "version:sync": "bun run scripts/sync-version.ts",
-    "postversion": "bun run scripts/sync-version.ts && git add .claude-plugin/plugin.json",
     "bench:api": "bun benchmarks/api/server.ts"
   },
   "devDependencies": {
-    "@types/bun": "latest"
+    "@types/bun": "latest",
+    "backlog.md": "^1.44.0",
+    "knip": "^6.7.0"
   },
   "engines": {
     "bun": ">=1.1.0"
@@ -44,11 +47,12 @@
     "typescript": "^5"
   },
   "dependencies": {
-    "@humanwhocodes/momoa": "^2.0.3",
     "@hono/zod-openapi": "^1.2.2",
     "@readme/openapi-parser": "^5.5.0",
+    "commander": "^14.0.0",
     "hono": "^4.12.2",
     "openapi-types": "^12.1.3",
+    "yaml": "^2.8.3",
     "zod": "^4.3.6"
   }
 }

package/src/cli/commands/ci-init.ts

@@ -42,13 +42,16 @@ jobs:
       - name: Run smoke tests (read-only, safe for production)
         run: |
           mkdir -p test-results
-          zond run apis/ --tag smoke --safe --report junit --no-db > test-results/smoke.xml
+          # --exclude-tag needs-id skips positive smoke that needs real IDs from .env.yaml
+          zond run apis/ --tag smoke --exclude-tag needs-id --safe --report junit --no-db > test-results/smoke.xml
           # Use --env-var "API_KEY=\${{ secrets.API_KEY }}" to inject secrets without writing to disk
         continue-on-error: true
 
-      - name: Run CRUD tests (staging only)
+      - name: Run CRUD tests (staging only — ephemeral suites only)
         run: |
-          zond run apis/ --tag crud --env staging --report junit --no-db > test-results/crud.xml
+          # --exclude-tag persistent-write keeps only ephemeral CRUD (suites that DELETE what they create).
+          # Drop --exclude-tag persistent-write to opt into write suites that leave residual data.
+          zond run apis/ --tag crud --exclude-tag persistent-write --env staging --report junit --no-db > test-results/crud.xml
           # Add --env-var "BASE_URL=\${{ secrets.STAGING_URL }}" for staging URL
         continue-on-error: true
 
@@ -86,8 +89,9 @@ api-smoke:
     - curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh
   script:
     - mkdir -p test-results
-    # Use --env-var to inject secrets without writing to disk
-    - zond run apis/ --tag smoke --safe --report junit --no-db --env-var "API_KEY=$API_KEY" > test-results/smoke.xml
+    # Use --env-var to inject secrets without writing to disk.
+    # --exclude-tag needs-id skips positive smoke that needs real IDs from .env.yaml.
+    - zond run apis/ --tag smoke --exclude-tag needs-id --safe --report junit --no-db --env-var "API_KEY=$API_KEY" > test-results/smoke.xml
   allow_failure:
     exit_codes: 1
   artifacts:
@@ -102,7 +106,9 @@ api-crud:
     - curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh
   script:
     - mkdir -p test-results
-    - zond run apis/ --tag crud --env staging --report junit --no-db > test-results/crud.xml
+    # --exclude-tag persistent-write keeps only ephemeral CRUD (suites that DELETE what they create).
+    # Drop --exclude-tag persistent-write to opt into write suites that leave residual data.
+    - zond run apis/ --tag crud --exclude-tag persistent-write --env staging --report junit --no-db > test-results/crud.xml
   allow_failure:
     exit_codes: 1
   artifacts:

package/src/cli/commands/completions.ts

@@ -0,0 +1,176 @@
+/**
+ * Shell completion script generator.
+ *
+ * Builds a static completion script from a commander program tree. No external
+ * completion library — bash/zsh/fish templates are inlined.
+ *
+ * Install:
+ *   bash:  zond completions bash > ~/.local/share/bash-completion/completions/zond
+ *   zsh:   zond completions zsh  > ~/.zsh/completions/_zond  (then `compinit`)
+ *   fish:  zond completions fish > ~/.config/fish/completions/zond.fish
+ */
+
+import type { Command } from "commander";
+
+export const COMPLETION_SHELLS = ["bash", "zsh", "fish"] as const;
+export type CompletionShell = (typeof COMPLETION_SHELLS)[number];
+
+export interface CompletionsOptions {
+  shell: CompletionShell;
+  program: Command;
+}
+
+interface CommandSpec {
+  name: string;
+  description: string;
+  options: string[]; // long flags only, e.g. ["--tag", "--safe"]
+  subcommands: CommandSpec[];
+}
+
+function extractSpec(cmd: Command): CommandSpec {
+  // Option's internal shape exposes `long`; commander v14 keeps this stable.
+  const rawOpts = cmd.options as unknown as Array<{ long?: string }>;
+  const opts: string[] = rawOpts
+    .map((o) => o.long)
+    .filter((s): s is string => typeof s === "string");
+
+  return {
+    name: cmd.name(),
+    description: cmd.description(),
+    options: opts,
+    // Drop commander's auto `help` subcommand to keep templates lean.
+    subcommands: cmd.commands
+      .filter((c) => c.name() !== "help")
+      .map(extractSpec),
+  };
+}
+
+// ── bash ──
+
+function renderBash(root: CommandSpec): string {
+  const topLevel = root.subcommands.map((s) => s.name).join(" ");
+
+  const perCmd = root.subcommands
+    .map((sub) => {
+      const flags = sub.options.join(" ");
+      const subs = sub.subcommands.map((s) => s.name).join(" ");
+      return `        ${sub.name})
+            COMPREPLY=( $(compgen -W "${[flags, subs].filter(Boolean).join(" ")}" -- "$cur") )
+            return 0
+            ;;`;
+    })
+    .join("\n");
+
+  return `# bash completion for zond — generated by 'zond completions bash'
+_zond_completion() {
+    local cur prev
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+    if [ "\$COMP_CWORD" -eq 1 ]; then
+        COMPREPLY=( $(compgen -W "${topLevel} --help --version" -- "$cur") )
+        return 0
+    fi
+
+    case "\${COMP_WORDS[1]}" in
+${perCmd}
+    esac
+}
+complete -F _zond_completion zond
+`;
+}
+
+// ── zsh ──
+
+function renderZsh(root: CommandSpec): string {
+  const cmdLines = root.subcommands
+    .map((s) => `        '${s.name}:${s.description.replace(/'/g, "'\\''")}'`)
+    .join(" \\\n");
+
+  const perCmd = root.subcommands
+    .map((sub) => {
+      const flagSpecs = sub.options
+        .map((f) => `                    '${f}[${f.slice(2)}]'`)
+        .join(" \\\n");
+      const subCmds = sub.subcommands.length > 0
+        ? `\n                _values 'subcommand' \\\n` +
+          sub.subcommands.map((s) => `                    '${s.name}[${s.description.replace(/'/g, "'\\''")}]'`).join(" \\\n")
+        : "";
+      return `        ${sub.name})
+            _arguments \\
+${flagSpecs || "                    ':path:_files'"}${subCmds}
+            ;;`;
+    })
+    .join("\n");
+
+  return `#compdef zond
+# zsh completion for zond — generated by 'zond completions zsh'
+
+_zond() {
+    local context state state_descr line
+    local -A opt_args
+
+    _arguments -C \\
+        '1: :->command' \\
+        '*::arg:->args'
+
+    case $state in
+        command)
+            _values 'zond command' \\
+${cmdLines}
+            ;;
+        args)
+            case $line[1] in
+${perCmd}
+            esac
+            ;;
+    esac
+}
+
+_zond "$@"
+`;
+}
+
+// ── fish ──
+
+function renderFish(root: CommandSpec): string {
+  const lines: string[] = [
+    "# fish completion for zond — generated by 'zond completions fish'",
+  ];
+
+  for (const sub of root.subcommands) {
+    const desc = sub.description.replace(/'/g, "\\'");
+    lines.push(`complete -c zond -n '__fish_use_subcommand' -a '${sub.name}' -d '${desc}'`);
+  }
+  lines.push(`complete -c zond -n '__fish_use_subcommand' -l help -d 'Show help'`);
+  lines.push(`complete -c zond -n '__fish_use_subcommand' -l version -d 'Show version'`);
+
+  for (const sub of root.subcommands) {
+    const condition = `__fish_seen_subcommand_from ${sub.name}`;
+    for (const opt of sub.options) {
+      lines.push(`complete -c zond -n '${condition}' -l ${opt.slice(2)}`);
+    }
+    for (const nested of sub.subcommands) {
+      const desc = nested.description.replace(/'/g, "\\'");
+      lines.push(`complete -c zond -n '${condition}' -a '${nested.name}' -d '${desc}'`);
+    }
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+// ── Public entry ──
+
+export function completionsCommand(options: CompletionsOptions): number {
+  const spec = extractSpec(options.program);
+
+  let script: string;
+  switch (options.shell) {
+    case "bash": script = renderBash(spec); break;
+    case "zsh":  script = renderZsh(spec);  break;
+    case "fish": script = renderFish(spec); break;
+  }
+
+  process.stdout.write(script);
+  return 0;
+}

package/src/cli/commands/db.ts

@@ -46,7 +46,8 @@ export async function dbCommand(options: DbOptions): Promise<number> {
           } else {
             for (const r of runs) {
               const run = r as any;
-              const status = run.failed > 0 ? "FAIL" : "PASS";
+              const isFail = run.failed > 0 || (run.total > 0 && run.passed === 0);
+              const status = isFail ? "FAIL" : "PASS";
               console.log(`#${run.id} ${status} ${run.passed}/${run.total} passed (${run.started_at})`);
             }
           }

package/src/cli/commands/generate.ts

@@ -92,7 +92,6 @@ export async function generateCommand(options: GenerateOptions): Promise<number>
     await writeMeta(options.output, {
       zondVersion: ZOND_VERSION,
       lastSyncedAt: new Date().toISOString(),
-      specUrl: options.specPath,
       specHash: hashSpec(specContent),
       files: { ...(existingMeta?.files ?? {}), ...metaFiles },
     });

package/src/cli/commands/init/agents-md.ts

@@ -0,0 +1,61 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import agentsTemplate from "./templates/agents.md" with { type: "text" };
+
+export const START_MARKER = "<!-- zond:start -->";
+export const END_MARKER = "<!-- zond:end -->";
+
+export interface AgentsBlockResult {
+  path: string;
+  action: "created" | "updated" | "noop";
+}
+
+function blockBody(): string {
+  return agentsTemplate.trim();
+}
+
+function wrap(body: string): string {
+  return `${START_MARKER}\n${body}\n${END_MARKER}`;
+}
+
+const BLOCK_RE = new RegExp(
+  `${escapeRe(START_MARKER)}[\\s\\S]*?${escapeRe(END_MARKER)}`,
+);
+
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Idempotently inserts (or updates) the zond instruction block in `<cwd>/AGENTS.md`.
+ *
+ * - Missing file → create with just the block.
+ * - File without markers → append block at the end (preceded by `\n\n---\n\n`).
+ * - File with existing markers → replace the body between them.
+ * - File whose existing block already matches → noop.
+ */
+export function upsertAgentsBlock(cwd: string): AgentsBlockResult {
+  const path = join(cwd, "AGENTS.md");
+  const next = wrap(blockBody());
+
+  if (!existsSync(path)) {
+    writeFileSync(path, next + "\n", "utf-8");
+    return { path, action: "created" };
+  }
+
+  const current = readFileSync(path, "utf-8");
+
+  if (BLOCK_RE.test(current)) {
+    const updated = current.replace(BLOCK_RE, next);
+    if (updated === current) return { path, action: "noop" };
+    writeFileSync(path, updated, "utf-8");
+    return { path, action: "updated" };
+  }
+
+  // Append with separator
+  const sep = current.endsWith("\n") ? "\n" : "\n\n";
+  const updated = current + sep + "---\n\n" + next + "\n";
+  writeFileSync(path, updated, "utf-8");
+  return { path, action: "updated" };
+}

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

@@ -0,0 +1,79 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { upsertAgentsBlock, type AgentsBlockResult } from "./agents-md.ts";
+import { upsertSkills, type SkillResult } from "./skills.ts";
+import zondConfigTemplate from "./templates/zond-config.yml" with { type: "text" };
+
+export interface BootstrapOptions {
+  cwd?: string;
+  /** Whether to write/upsert AGENTS.md. Defaults to true. */
+  writeAgents?: boolean;
+  /** Whether to write Claude Code skills under .claude/skills/. Defaults to true. */
+  writeSkills?: boolean;
+  /** Override $HOME — used by tests and intentional overrides. */
+  home?: string;
+  dryRun?: boolean;
+}
+
+export interface BootstrapResult {
+  cwd: string;
+  configPath: string;
+  configAction: "created" | "noop";
+  apisDir: string;
+  apisAction: "created" | "noop";
+  agents: AgentsBlockResult | null;
+  skills: SkillResult[];
+  warnings: string[];
+}
+
+/**
+ * Idempotent workspace bootstrap. Creates `zond.config.yml`, `apis/`, and
+ * (unless `writeAgents` is false) `AGENTS.md`.
+ */
+export function bootstrapWorkspace(opts: BootstrapOptions = {}): BootstrapResult {
+  const cwd = resolve(opts.cwd ?? process.cwd());
+  const warnings: string[] = [];
+  const writeAgents = opts.writeAgents ?? true;
+  const writeSkills = opts.writeSkills ?? true;
+
+  // 1. zond.config.yml
+  const configPath = join(cwd, "zond.config.yml");
+  let configAction: "created" | "noop" = "noop";
+  if (!existsSync(configPath)) {
+    if (!opts.dryRun) writeFileSync(configPath, zondConfigTemplate, "utf-8");
+    configAction = "created";
+  }
+
+  // 2. apis/
+  const apisDir = join(cwd, "apis");
+  let apisAction: "created" | "noop" = "noop";
+  if (!existsSync(apisDir)) {
+    if (!opts.dryRun) mkdirSync(apisDir, { recursive: true });
+    apisAction = "created";
+  }
+
+  // 3. AGENTS.md
+  let agents: AgentsBlockResult | null = null;
+  if (writeAgents) {
+    if (!opts.dryRun) {
+      agents = upsertAgentsBlock(cwd);
+    } else {
+      agents = { path: join(cwd, "AGENTS.md"), action: existsSync(join(cwd, "AGENTS.md")) ? "updated" : "created" };
+    }
+  }
+
+  // 4. .claude/skills/zond-*/SKILL.md
+  const skills: SkillResult[] = writeSkills ? upsertSkills(cwd, { dryRun: opts.dryRun }) : [];
+
+  return {
+    cwd,
+    configPath,
+    configAction,
+    apisDir,
+    apisAction,
+    agents,
+    skills,
+    warnings,
+  };
+}