@kirrosh/zond 0.20.0 → 0.22.0

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,
+  };
+}

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

@@ -0,0 +1,45 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import zondSkill from "./templates/skills/zond.md" with { type: "text" };
+import scenariosSkill from "./templates/skills/scenarios.md" with { type: "text" };
+
+export interface SkillResult {
+  name: string;
+  path: string;
+  action: "created" | "updated" | "noop";
+}
+
+interface SkillTemplate {
+  name: string;
+  body: string;
+}
+
+const SKILLS: SkillTemplate[] = [
+  { name: "zond", body: zondSkill },
+  { name: "zond-scenarios", body: scenariosSkill },
+];
+
+/**
+ * Idempotently writes Claude Code skills into `<cwd>/.claude/skills/<name>/SKILL.md`.
+ * Body is identical to the in-binary template — overwrites on drift, noop on match.
+ */
+export function upsertSkills(cwd: string, opts: { dryRun?: boolean } = {}): SkillResult[] {
+  return SKILLS.map(({ name, body }) => {
+    const path = join(cwd, ".claude", "skills", name, "SKILL.md");
+    const desired = body.endsWith("\n") ? body : body + "\n";
+
+    if (!existsSync(path)) {
+      if (!opts.dryRun) {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, desired, "utf-8");
+      }
+      return { name, path, action: "created" };
+    }
+
+    const current = readFileSync(path, "utf-8");
+    if (current === desired) return { name, path, action: "noop" };
+    if (!opts.dryRun) writeFileSync(path, desired, "utf-8");
+    return { name, path, action: "updated" };
+  });
+}

package/src/cli/commands/init/templates/agents.md

@@ -0,0 +1,73 @@
+## API testing with zond
+
+This workspace uses [zond](https://github.com/kirrosh/zond) for API testing. The MCP
+server is **not** configured for this workspace, so use the CLI directly.
+
+### Detailed playbooks (skills)
+
+Detailed task-specific playbooks live in `.claude/skills/` and are auto-discovered by
+Claude Code. Other agents (Codex, Cursor, Aider) can read them as plain markdown:
+
+- `.claude/skills/zond/SKILL.md` — end-to-end API testing: generate from OpenAPI,
+  run, diagnose failures, hunt bugs via probes, report coverage. Has explicit
+  entry points so narrow requests (only diagnose, only probe) skip earlier phases.
+- `.claude/skills/zond-scenarios/SKILL.md` — author multi-step user-journey tests
+  and fixture creation via the API (hand-written YAML with captures,
+  `setup: true`, `always: true`). NOT for spec coverage or bug hunting.
+
+### Mandatory rules (always-on)
+
+- **NEVER** read OpenAPI/Swagger/JSON spec files with Read/cat — use `zond describe`,
+  `zond catalog`, or the generated `.api-catalog.yaml`.
+- **NEVER** use curl/wget for ad-hoc requests — use `zond request <method> <url>`.
+- **NEVER** write test YAML from scratch — start with `zond generate <spec> --output <dir>`,
+  then edit failing cases.
+- **NEVER** hardcode tokens — put them in `apis/<name>/.env.yaml` (already gitignored)
+  and reference as `{{auth_token}}` in test YAML.
+- `--safe` enforces GET-only; never run CRUD tests against production without explicit
+  user confirmation and a staging environment.
+- When `zond db diagnose` reports `recommended_action: report_backend_bug` — STOP, do
+  not change the test to make it pass.
+
+### Workflow — covering an API end-to-end
+
+```bash
+# 1. Register the API
+zond init --spec <path-or-url> --name <name> [--base-url <url>]
+zond use <name>                              # remember as current
+
+# 2. Inspect endpoints (avoid reading the raw spec)
+zond catalog <spec> --output apis/<name>     # writes .api-catalog.yaml
+zond describe <spec> --compact
+
+# 3. Generate test stubs and run smoke (GET-only)
+zond generate <spec> --output apis/<name>/tests --tag smoke
+zond run --safe --json
+
+# 4. Diagnose failures
+zond db runs --limit 5
+zond db diagnose <run-id> --json
+
+# 5. Coverage gate
+zond coverage --fail-on-coverage 50
+
+# 6. CRUD only with explicit user confirmation + staging env
+zond run --tag crud --dry-run                # show what would be sent
+zond run --tag crud --env staging
+```
+
+### Filtering by tag
+
+`--tag <name>` filters suites. If a `setup` suite primes auth tokens, always include
+its tag together with the target group: `--tag crud,setup`.
+
+### Auth patterns
+
+For in-memory or test backends that issue tokens via login, use a `setup.yaml` suite
+with `setup: true`. Captured variables (e.g. `auth_token`) propagate to subsequent
+suites in the same run. Do NOT hardcode bearer tokens for these flows.
+
+### Environments
+
+`zond run --env <name>` loads `.env.<name>.yaml` (or `.env.yaml` by default) from the
+API directory. Environment files are auto-gitignored by `zond init`.

package/src/cli/commands/init/templates/markdown.d.ts

@@ -0,0 +1,4 @@
+declare module "*.md" {
+  const content: string;
+  export default content;
+}

package/src/cli/commands/init/templates/skills/scenarios.md

@@ -0,0 +1,97 @@
+---
+name: zond-scenarios
+description: |
+  Author multi-step API scenario tests (user journeys) with zond. Use when asked to:
+  write a scenario, model a user flow, replay a UI flow via API, chain requests with
+  captures, set up test data via API, test a workflow end-to-end. Activates on:
+  "user scenario", "API workflow", "multi-step test", "login then ...", "create then ...".
+allowed-tools: [Read, Write, Bash(zond *), Bash(bunx zond *)]
+---
+
+# zond — API Scenario Tests
+
+CLI-only skill. Scenarios are **hand-written** YAML chaining multiple requests
+with captures (no `zond generate` for scenarios — `generate` only emits per-endpoint suites).
+
+## Critical rules
+- **NEVER** run `zond generate` to produce scenarios — write them manually from `.api-catalog.yaml`.
+- **NEVER** read OpenAPI/Swagger specs directly — use `zond catalog` or `zond describe`.
+- **NEVER** invent endpoints — only use entries present in `.api-catalog.yaml`.
+- **Captures are file-scoped** — variables defined in one file do not leak into others
+  unless the producing suite is marked `setup: true`.
+- Tag every scenario `[scenario, <flow-name>]`. Run by `--tag scenario` or `--tag <flow>,setup`.
+- Keep one user journey per file; chain steps within that file.
+
+## Workflow
+```bash
+# 1. Make sure the catalog is current
+zond catalog <spec> --output apis/<name>/tests
+
+# 2. Read the catalog to pick endpoints (NOT the raw spec)
+cat apis/<name>/tests/.api-catalog.yaml
+
+# 3. Author the scenario YAML (see structure below)
+
+# 4. Validate + run
+zond validate apis/<name>/tests/scenarios/<flow>.yaml
+zond run apis/<name>/tests/scenarios/<flow>.yaml --json
+
+# 5. Diagnose failures
+zond db diagnose <run-id> --json
+```
+
+## Scenario YAML — minimal structure
+```yaml
+name: user_signup_to_first_purchase
+tags: [scenario, signup_purchase]
+steps:
+  - name: register
+    request:
+      method: POST
+      url: "{{base_url}}/auth/register"
+      body: { email: "{{generate.email}}", password: "{{generate.password}}" }
+    expect: { status: 201 }
+    capture:
+      user_id: "$.id"
+      auth_token: "$.token"
+
+  - name: create_cart
+    request:
+      method: POST
+      url: "{{base_url}}/carts"
+      headers: { Authorization: "Bearer {{auth_token}}" }
+    expect: { status: 201 }
+    capture: { cart_id: "$.id" }
+
+  - name: checkout
+    request:
+      method: POST
+      url: "{{base_url}}/carts/{{cart_id}}/checkout"
+      headers: { Authorization: "Bearer {{auth_token}}" }
+    expect: { status: 200 }
+
+  - name: cleanup
+    always: true                       # runs even if earlier steps failed
+    request:
+      method: DELETE
+      url: "{{base_url}}/users/{{user_id}}"
+      headers: { Authorization: "Bearer {{auth_token}}" }
+```
+
+Key building blocks (full reference in `ZOND.md`):
+- `capture: { var: "$.json.path" }` — JSONPath extraction into scenario-local vars.
+- `expect.status` / `expect.json` / `expect.headers` — assertions.
+- `{{generate.email}}`, `{{generate.uuid}}`, `{{generate.int(1,100)}}` — value generators.
+- `always: true` on a step — guaranteed cleanup (runs on prior failure).
+- `setup: true` at the suite level — captures propagate to other suites in the run.
+
+## Sharing auth across scenarios
+Put login in `apis/<name>/tests/setup.yaml` with `setup: true`; scenarios reference
+`{{auth_token}}` directly. Run with `--tag <flow>,setup`.
+
+## When to hand off
+- Need broad endpoint coverage, bug hunting, or run diagnosis → `zond`.
+- This skill is **only** for hand-written multi-step flows / fixture creation.
+
+For full YAML structure (assertions, flow control, generators, conditional steps),
+see the YAML format section of `ZOND.md` at the repo root.

package/src/cli/commands/init/templates/skills/zond.md

@@ -0,0 +1,184 @@
+---
+name: zond
+description: |
+  End-to-end API testing with zond — generate tests from an OpenAPI spec, run them,
+  diagnose failures, and hunt for typical backend bugs via probe suites. Use when
+  asked to: test an API, cover endpoints, raise coverage, find bugs, diagnose
+  failed runs, fix failing tests, debug 4xx/5xx, run probes, sync tests after a
+  spec change, set up API test infrastructure. Activates on: openapi.json,
+  openapi.yaml, swagger.json, .api-catalog.yaml, "test this API", "cover this
+  spec", "tests are failing", "diagnose run", "find bugs", "probe", "5xx",
+  "negative input".
+allowed-tools: [Read, Write, Bash(zond *), Bash(bunx zond *)]
+---
+
+# zond — API Coverage, Diagnosis & Bug Hunting
+
+CLI-only skill. zond is invoked directly via shell. Run `zond --version` first;
+if missing, install via `curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh`.
+
+For multi-step user journeys / fixture creation through the API, hand off to
+`zond-scenarios` instead — that is a different concern.
+
+## Critical rules (always-on)
+
+- **NEVER** open OpenAPI/Swagger files with Read/cat/grep — use `zond describe`,
+  `zond catalog`, or the generated `.api-catalog.yaml`.
+- **NEVER** use curl/wget — use `zond request <method> <url>`.
+- **NEVER** write test YAML from scratch — start with `zond generate`, then edit failures.
+- **NEVER** hardcode tokens — `apis/<name>/.env.yaml` (auto-gitignored), reference as `{{auth_token}}`.
+- **`--safe` enforces GET-only** — required for first-pass smoke against unknown envs.
+- **`recommended_action: report_backend_bug` (5xx) → STOP**. Do NOT modify
+  `expect: status` to make the test pass. Surface the bug to the user with the
+  request/response excerpt.
+- **5xx in any run is a bug candidate** — never edit assertions to mask it.
+- For multi-suite tag filters always include the setup tag: `--tag crud,setup`.
+- Captures are file-scoped — pass auth across suites via a `setup: true` suite.
+- Re-run after each fix with `--safe --json`; do not batch many edits without verifying.
+
+## Entry points (skip phases when the request is narrow)
+
+| User asked... | Start at phase | Skip |
+|---|---|---|
+| "cover this API", "raise coverage", "test this spec" | 1 (Discover) | — |
+| "find bugs", "probe this API", "test for 5xx" | 1 then 5 (Probes) | — |
+| "tests are failing", "diagnose run X", "fix failures" | 4 (Diagnose) | 1–3 |
+| "the run after my fix" | 3.x (Run) → 4 (Diagnose) | 1–2 |
+
+## Phase 1 — Discover
+
+```bash
+# Workspace + register API (idempotent)
+zond init --with-spec <spec> --name <name> [--base-url <url>]
+zond use <name>
+
+# Endpoint discovery (do NOT read the raw spec)
+zond catalog <spec> --output apis/<name>/tests   # writes .api-catalog.yaml
+zond describe <spec> --compact                   # quick overview
+zond guide <spec> --tests-dir apis/<name>/tests  # uncovered + suggestions
+```
+
+## Phase 2 — Generate
+
+```bash
+zond generate <spec> --output apis/<name>/tests              # all
+zond generate <spec> --output apis/<name>/tests --tag <tag>  # by spec tag
+zond generate <spec> --output apis/<name>/tests --uncovered-only
+zond validate apis/<name>/tests                              # YAML lint
+```
+
+`generate` fills bodies with `{{$randomString}}`. Format-strict APIs will reject
+many of these — that is a **test-fix**, not a backend bug. See phase 4 for the fix flow.
+
+## Phase 3 — Run (sanity → smoke → full)
+
+```bash
+# 3.1 Sanity gate — must pass before broad runs
+zond run apis/<name>/tests --tag sanity --json
+
+# 3.2 Smoke (GET-only)
+zond run apis/<name>/tests --safe --json
+
+# 3.3 Full CRUD — only after setup-token capture works
+zond run apis/<name>/tests --tag crud,setup --json
+```
+
+## Phase 4 — Diagnose failures
+
+```bash
+zond db runs --limit 5 --json                # find failed runId
+zond db diagnose <run-id> --json             # full DiagnoseResult (grouped by root_cause)
+zond db run <id> --status 500 --json         # filter results within a run
+zond db run <id> --method POST --json
+zond db compare <idA> <idB> --json           # regression diff between runs
+```
+
+DiagnoseResult guide:
+- `agent_directive` — literal next step. Do exactly that.
+- `recommended_action`:
+  - `fix_test_logic` → edit the YAML (assertion, generator, capture).
+  - `report_backend_bug` → STOP, report to user.
+  - `update_expectation` → only if the user confirms the new contract is correct.
+- `root_cause` groups identical failures so one fix covers many cases.
+
+### 4a. Fixing 4xx caused by stub generators
+
+When `recommended_action: fix_test_logic` and the body is rejected on format
+(400/422 with a field name and an "expected ..." message):
+
+1. Read the failure body: `zond db run <id> --status 422 --json`.
+2. **First pass** — swap `{{$randomString}}` for the matching typed generator:
+
+   | API expects   | Use                  |
+   |---------------|----------------------|
+   | email         | `{{$randomEmail}}`   |
+   | hostname/FQDN | `{{$randomFqdn}}`    |
+   | URL           | `{{$randomUrl}}`     |
+   | IPv4          | `{{$randomIpv4}}`    |
+   | UUID          | `{{$uuid}}`          |
+   | integer       | `{{$randomInt}}`     |
+   | ISO date      | `{{$randomIsoDate}}` |
+   | date          | `{{$randomDate}}`    |
+   | person name   | `{{$randomName}}`    |
+
+3. **Second pass** — if a typed generator still fails (regex too strict, enum,
+   business constraint), drop to a hardcoded literal that satisfies the contract
+   (e.g. `"https://example.com"`, `"info@example.com"`, `"2026-01-01T00:00:00Z"`).
+4. **Dependent IDs** (`audience_id`, `topic_id`, anything that must reference an
+   existing resource) — generators cannot help. Either capture the ID from a
+   prior `create_*` step in the same suite, or move that creation into a
+   `setup: true` suite and reference the captured variable.
+
+## Phase 5 — Proactive bug hunting (probes)
+
+Run on a passing API to surface latent bugs.
+
+```bash
+# Negative-input — 5xx on malformed bodies/query/path
+zond probe-validation <spec> --output apis/<name>/probes/validation
+zond run apis/<name>/probes/validation --json
+
+# Undeclared HTTP methods — 5xx or unexpected 2xx on methods not in spec
+zond probe-methods <spec> --output apis/<name>/probes/methods
+zond run apis/<name>/probes/methods --json
+
+# Triage
+zond db diagnose <run-id> --json
+```
+
+Typical findings:
+- **5xx on null / empty / oversized body** → missing input validation.
+- **5xx on wrong type** (string for int, etc.) → unguarded coercion.
+- **2xx on undeclared method** → contract drift (spec lies, or method is unprotected).
+- **5xx on missing required field** → uncaught NPE on the server.
+
+Filter probe scope when an API is large:
+```bash
+zond probe-validation <spec> --tag <spec-tag> --max-per-endpoint 20
+zond probe-methods <spec> --tag <spec-tag>
+```
+
+## Phase 6 — Coverage report & spec drift
+
+```bash
+zond coverage --api <name> --fail-on-coverage 80
+zond coverage --api <name> --run-id <id>          # per-run breakdown
+zond sync <spec> --tests apis/<name>/tests        # detect new/removed endpoints
+```
+
+## Auth / environments
+
+- Tokens go in `apis/<name>/.env.yaml` (auto-gitignored), referenced as `{{auth_token}}`.
+- Login-flow tokens: a `setup: true` suite captures into vars that propagate to later
+  suites in the same run. See `apis/<name>/tests/setup.yaml` examples emitted by `zond generate`.
+- `zond run --env <name>` loads `.env.<name>.yaml` from the API directory.
+
+## When to hand off to `zond-scenarios`
+
+- The user asks for a multi-step user journey, business flow, or fixture creation
+  through the API (login → create cart → checkout → cleanup).
+- A failing run's root cause requires a hand-written multi-step suite that
+  `zond generate` cannot express.
+
+For YAML format (assertions, generators, captures, `always: true` cleanup,
+`setup: true` propagation), see `ZOND.md` at the repo root or `zond run --help`.

package/src/cli/commands/init/templates/zond-config.yml

@@ -0,0 +1,15 @@
+# zond workspace config
+#
+# The presence of this file marks the workspace root for `zond` walk-up
+# resolution (zond.db, apis/<name>/, .zond-current are anchored here).
+#
+# Schema below is a placeholder — TASK-12 will wire a real config loader.
+# Uncomment and edit as needed.
+
+version: 1
+
+# default_reporter: console     # console | json | junit
+# default_safe: false
+# default_timeout_ms: 30000
+# default_tags: []
+# fail_on_coverage: 0

package/src/cli/commands/init.ts

@@ -1,8 +1,10 @@
-import { setupApi } from "../../core/setup-api.ts";
+import { setupApi, type SetupApiResult } from "../../core/setup-api.ts";
 import { printError, printSuccess } from "../output.ts";
 import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
+import { bootstrapWorkspace, type BootstrapResult } from "./init/bootstrap.ts";
 
 export interface InitOptions {
+  // register-an-API options (existing)
   name?: string;
   spec?: string;
   baseUrl?: string;
@@ -11,47 +13,138 @@ export interface InitOptions {
   insecure?: boolean;
   dbPath?: string;
   json?: boolean;
+
+  // workspace bootstrap (new)
+  workspace?: boolean;
+  withSpec?: string;
+  /** Skip writing AGENTS.md. */
+  noAgents?: boolean;
+  /** Skip writing Claude Code skills under .claude/skills/. */
+  noSkills?: boolean;
+  /** Override cwd for bootstrap (used by tests; CLI always uses process.cwd()). */
+  cwd?: string;
+  /** Override $HOME for MCP install (used by tests). */
+  home?: string;
+}
+
+type InitMode = "register" | "workspace" | "bootstrap+register";
+
+function resolveMode(options: InitOptions): InitMode {
+  if (options.spec) return "register";
+  if (options.withSpec) return "bootstrap+register";
+  return "workspace";
 }
 
 export async function initCommand(options: InitOptions): Promise<number> {
+  // Reject conflicting combos
+  if (options.spec && options.workspace) {
+    const msg = "Cannot use --spec and --workspace together. Use --with-spec to bootstrap and register in one step.";
+    if (options.json) printJson(jsonError("init", [msg]));
+    else printError(msg);
+    return 2;
+  }
+
+  const mode = resolveMode(options);
+  const writeAgents = !options.noAgents;
+  const writeSkills = !options.noSkills;
+
   try {
-    const envVars: Record<string, string> = {};
-    if (options.baseUrl) envVars.base_url = options.baseUrl;
-
-    const result = await setupApi({
-      name: options.name,
-      spec: options.spec,
-      dir: options.dir,
-      envVars: Object.keys(envVars).length > 0 ? envVars : undefined,
-      dbPath: options.dbPath,
-      force: options.force,
-      insecure: options.insecure,
-    });
+    if (mode === "register") {
+      const result = await registerApi(options);
+      printRegisterResult(options, result);
+      return 0;
+    }
+
+    const bootstrap = bootstrapWorkspace({ writeAgents, writeSkills, cwd: options.cwd, home: options.home });
+    let register: SetupApiResult | null = null;
+
+    if (mode === "bootstrap+register") {
+      register = await registerApi({ ...options, spec: options.withSpec });
+    }
 
     if (options.json) {
-      printJson(jsonOk("init", {
-        collectionId: result.collectionId,
-        baseDir: result.baseDir,
-        testPath: result.testPath,
-        endpoints: result.specEndpoints,
-        warnings: result.warnings ?? [],
-      }, result.warnings));
-    } else {
-      printSuccess(`Created API '${options.name ?? "api"}' at ${result.baseDir} (${result.specEndpoints} endpoints)`);
-      if (result.warnings) {
-        for (const w of result.warnings) {
-          process.stderr.write(`Warning: ${w}\n`);
-        }
+      const data: Record<string, unknown> = {
+        mode,
+        configPath: bootstrap.configPath,
+        configAction: bootstrap.configAction,
+        apisDir: bootstrap.apisDir,
+        apisAction: bootstrap.apisAction,
+        agentsPath: bootstrap.agents?.path ?? null,
+        agentsAction: bootstrap.agents?.action ?? null,
+        skills: bootstrap.skills.map((s) => ({ name: s.name, path: s.path, action: s.action })),
+      };
+      if (register) {
+        data.collectionId = register.collectionId;
+        data.baseDir = register.baseDir;
+        data.testPath = register.testPath;
+        data.endpoints = register.specEndpoints;
       }
+      printJson(jsonOk("init", data, [...bootstrap.warnings, ...(register?.warnings ?? [])]));
+    } else {
+      printBootstrapResult(bootstrap, writeAgents);
+      if (register) printRegisterResult(options, register);
     }
     return 0;
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    if (options.json) {
-      printJson(jsonError("init", [message]));
-    } else {
-      printError(message);
-    }
+    if (options.json) printJson(jsonError("init", [message]));
+    else printError(message);
     return 2;
   }
 }
+
+async function registerApi(options: InitOptions): Promise<SetupApiResult> {
+  const envVars: Record<string, string> = {};
+  if (options.baseUrl) envVars.base_url = options.baseUrl;
+
+  return await setupApi({
+    name: options.name,
+    spec: options.spec ?? options.withSpec,
+    dir: options.dir,
+    envVars: Object.keys(envVars).length > 0 ? envVars : undefined,
+    dbPath: options.dbPath,
+    force: options.force,
+    insecure: options.insecure,
+  });
+}
+
+function printRegisterResult(options: InitOptions, result: SetupApiResult): void {
+  if (options.json) {
+    // Only used by the legacy "register"-only path
+    printJson(jsonOk("init", {
+      mode: "register",
+      collectionId: result.collectionId,
+      baseDir: result.baseDir,
+      testPath: result.testPath,
+      endpoints: result.specEndpoints,
+    }, result.warnings));
+    return;
+  }
+  printSuccess(`Created API '${options.name ?? "api"}' at ${result.baseDir} (${result.specEndpoints} endpoints)`);
+  if (result.warnings) {
+    for (const w of result.warnings) process.stderr.write(`Warning: ${w}\n`);
+  }
+}
+
+function printBootstrapResult(b: BootstrapResult, writeAgents: boolean): void {
+  const lines: string[] = [];
+  lines.push(`  ${verb(b.configAction)} zond.config.yml`);
+  lines.push(`  ${verb(b.apisAction)} apis/`);
+  if (b.agents) lines.push(`  ${verb(b.agents.action)} AGENTS.md`);
+  for (const s of b.skills) {
+    lines.push(`  ${verb(s.action)} .claude/skills/${s.name}/SKILL.md`);
+  }
+  for (const w of b.warnings) {
+    process.stderr.write(`Warning: ${w}\n`);
+  }
+  process.stdout.write(lines.join("\n") + "\n");
+  if (!writeAgents) {
+    printSuccess("Workspace ready. Run `zond init --spec <path>` to register your first API.");
+  } else {
+    printSuccess("Workspace ready. See AGENTS.md for the CLI workflow.");
+  }
+}
+
+function verb(action: "created" | "updated" | "noop"): string {
+  return action === "created" ? "Created" : action === "updated" ? "Updated" : "Up-to-date:";
+}