cool-workflow 0.1.95 → 0.1.97

package/dist/trust-audit.js

@@ -11,6 +11,8 @@ exports.recordTrustAuditEvent = recordTrustAuditEvent;
 exports.recordSandboxPathDecision = recordSandboxPathDecision;
 exports.recordSandboxPolicyDecision = recordSandboxPolicyDecision;
 exports.recordHostAttestation = recordHostAttestation;
+exports.setAuditEventCache = setAuditEventCache;
+exports.clearAuditEventCache = clearAuditEventCache;
 exports.listTrustAuditEvents = listTrustAuditEvents;
 exports.searchAuditEvents = searchAuditEvents;
 exports.summarizeTrustAudit = summarizeTrustAudit;
@@ -300,9 +302,25 @@ function recordHostAttestation(run, input) {
         source: "host-attested"
     });
 }
+// Per-request event log cache (v0.1.95). When set, readEvents returns
+// memoized results keyed by event log path. Clears after each request.
+let _eventLogCache = null;
+function setAuditEventCache(cache) {
+    _eventLogCache = cache;
+}
+function clearAuditEventCache() {
+    _eventLogCache = null;
+}
 function listTrustAuditEvents(run) {
     const audit = ensureTrustAudit(run);
-    return readEventsRaw(audit.eventLogPath).events.sort(compareEvents);
+    if (_eventLogCache) {
+        const cached = _eventLogCache.get(audit.eventLogPath);
+        if (cached)
+            return cached;
+    }
+    const events = readEventsRaw(audit.eventLogPath).events.sort(compareEvents);
+    _eventLogCache?.set(audit.eventLogPath, events);
+    return events;
 }
 /** Search audit events by kind, worker, or candidate (v0.1.65).
  *  Filters are AND-ed; empty filters match all. */
@@ -515,7 +533,14 @@ function auditRoot(run) {
     return run.paths.auditDir || node_path_1.default.join(run.paths.runDir, "audit");
 }
 function readEvents(eventLogPath) {
-    return readEventsRaw(eventLogPath).events.sort(compareEvents);
+    if (_eventLogCache) {
+        const cached = _eventLogCache.get(eventLogPath);
+        if (cached)
+            return cached;
+    }
+    const events = readEventsRaw(eventLogPath).events.sort(compareEvents);
+    _eventLogCache?.set(eventLogPath, events);
+    return events;
 }
 function workerRows(events, run) {
     const workerIds = unique([...(run.workers || []).map((worker) => worker.id), ...events.map((event) => event.workerId || "")]).sort();

package/dist/util/fingerprint.js

@@ -0,0 +1,19 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fingerprintStrings = fingerprintStrings;
+exports.fingerprintRecords = fingerprintRecords;
+// Deterministic content fingerprint — the single canonical implementation.
+// Replaces duplicated copies in observability.ts and run-registry.ts (v0.1.95).
+// Pure function of its arguments; never imports run state or high-level modules.
+const node_crypto_1 = __importDefault(require("node:crypto"));
+function fingerprintStrings(values) {
+    const hash = node_crypto_1.default.createHash("sha256");
+    hash.update(JSON.stringify([...values].sort()));
+    return `sha256:${hash.digest("hex").slice(0, 32)}`;
+}
+function fingerprintRecords(records) {
+    return fingerprintStrings(records.map((r) => `${r.id}:${r.status || ""}`).sort());
+}

package/dist/util/fingerprint.test.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// Unit test for the canonical fingerprint utility (v0.1.95).
+// Pure function — no run state or tmpdir needed.
+const strict_1 = require("node:assert/strict");
+const node_test_1 = require("node:test");
+const fingerprint_1 = require("../util/fingerprint");
+(0, node_test_1.test)("fingerprintStrings returns a sha256: prefix", () => {
+    const fp = (0, fingerprint_1.fingerprintStrings)(["a", "b"]);
+    (0, strict_1.ok)(fp.startsWith("sha256:"), "must have sha256: prefix");
+    (0, strict_1.equal)(fp.length, 32 + "sha256:".length, "must be 32 hex chars");
+});
+(0, node_test_1.test)("fingerprintStrings is deterministic and order-independent", () => {
+    const a = (0, fingerprint_1.fingerprintStrings)(["b", "a", "c"]);
+    const b = (0, fingerprint_1.fingerprintStrings)(["c", "b", "a"]);
+    (0, strict_1.equal)(a, b, "same values in different order must produce same fingerprint");
+});
+(0, node_test_1.test)("fingerprintStrings produces distinct values for different inputs", () => {
+    const a = (0, fingerprint_1.fingerprintStrings)(["x"]);
+    const b = (0, fingerprint_1.fingerprintStrings)(["y"]);
+    (0, strict_1.ok)(a !== b, "different inputs must produce different fingerprints");
+});
+(0, node_test_1.test)("fingerprintRecords uses id:status sorted", () => {
+    const a = (0, fingerprint_1.fingerprintRecords)([{ id: "b", status: "ok" }, { id: "a", status: "fail" }]);
+    const b = (0, fingerprint_1.fingerprintRecords)([{ id: "a", status: "fail" }, { id: "b", status: "ok" }]);
+    (0, strict_1.equal)(a, b, "records in different order must produce same fingerprint");
+});

package/dist/version.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MIN_SUPPORTED_RUN_STATE_SCHEMA_VERSION = exports.LEGACY_RUN_STATE_SCHEMA_VERSION = exports.CURRENT_RUN_STATE_SCHEMA_VERSION = exports.WORKFLOW_APP_SCHEMA_VERSION = exports.CURRENT_COOL_WORKFLOW_VERSION = void 0;
-exports.CURRENT_COOL_WORKFLOW_VERSION = "0.1.95";
+exports.CURRENT_COOL_WORKFLOW_VERSION = "0.1.97";
 exports.WORKFLOW_APP_SCHEMA_VERSION = 1;
 exports.CURRENT_RUN_STATE_SCHEMA_VERSION = 1;
 exports.LEGACY_RUN_STATE_SCHEMA_VERSION = 0;

package/dist/workbench-host.js

@@ -24,6 +24,7 @@ exports.WorkbenchHost = void 0;
 const node_http_1 = __importDefault(require("node:http"));
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
 const workbench_1 = require("./workbench");
 const ALLOWED_HOSTNAMES = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
 const CONTENT_TYPES = {
@@ -85,7 +86,23 @@ class WorkbenchHost {
             if ((req.method || "GET").toUpperCase() !== "GET") {
                 return this.send(res, 405, { error: "read-only: only GET is permitted" }, { Allow: "GET" });
             }
+            // Optional token auth (CW_WORKBENCH_TOKEN). When set, every request must
+            // carry the token as an Authorization: Bearer header or ?token= query param.
+            // Off by default — single-user loopback is already gated by the OS boundary.
             const url = new URL(req.url || "/", `http://${this.host}`);
+            const requiredToken = (process.env.CW_WORKBENCH_TOKEN || "").trim();
+            if (requiredToken) {
+                const bearer = (req.headers.authorization || "").replace(/^Bearer\s+/i, "").trim();
+                const queryToken = url.searchParams.get("token") || "";
+                const tokenBuf = Buffer.from(requiredToken);
+                const bearerBuf = Buffer.from(bearer);
+                const queryBuf = Buffer.from(queryToken);
+                const tokenOk = bearerBuf.length === tokenBuf.length && node_crypto_1.default.timingSafeEqual(bearerBuf, tokenBuf);
+                const queryOk = queryBuf.length === tokenBuf.length && node_crypto_1.default.timingSafeEqual(queryBuf, tokenBuf);
+                if (!tokenOk && !queryOk) {
+                    return this.send(res, 401, { error: "unauthorized: token mismatch" });
+                }
+            }
             const route = decodeURIComponent(url.pathname);
             if (route === "/" || route === "/index.html")
                 return this.sendAsset(res, "index.html");

package/dist/workbench.js

@@ -110,23 +110,25 @@ function buildPanels(runner, runId) {
  *  never fabricated. */
 function buildWorkbenchRunView(runner, runId) {
     const id = String(runId || "");
-    let resolved = true;
-    let error;
-    try {
-        runner.loadRun(id);
-    }
-    catch (caught) {
-        resolved = false;
-        error = caught instanceof Error ? caught.message : String(caught);
-    }
-    return {
-        schemaVersion: 1,
-        surface: "workbench",
-        runId: id,
-        resolved,
-        ...(error ? { error } : {}),
-        panels: buildPanels(runner, id)
-    };
+    return runner.loadWithCache((r) => {
+        let resolved = true;
+        let error;
+        try {
+            r.loadRun(id);
+        }
+        catch (caught) {
+            resolved = false;
+            error = caught instanceof Error ? caught.message : String(caught);
+        }
+        return {
+            schemaVersion: 1,
+            surface: "workbench",
+            runId: id,
+            resolved,
+            ...(error ? { error } : {}),
+            panels: buildPanels(r, id)
+        };
+    });
 }
 // ---------------------------------------------------------------------------
 // Cross-run entry (v0.1.28 Run Registry) — composed from already-declared

package/dist/worker-isolation.js

@@ -393,7 +393,31 @@ function recordWorkerRetryAttempt(run, workerId, attempts, reason, options = {})
 function validateWorkerBoundary(run, workerId, options = {}) {
     const scope = requireWorkerScope(run, workerId);
     const rawPath = String(options.path || scope.resultPath);
-    return (0, sandbox_profile_1.validateSandboxWrite)(sandboxPolicyForBoundary(run, scope, options), rawPath, workerId);
+    const policy = sandboxPolicyForBoundary(run, scope, options);
+    const violation = (0, sandbox_profile_1.validateSandboxWrite)(policy, rawPath, workerId);
+    if (!violation) {
+        // Write paths are enforced by CW at this boundary. Command and network limits
+        // are declared in the sandbox policy but enforced by the execution backend
+        // (the host/container runtime). Record the policy split transparently so the
+        // audit trail shows what CW checked vs what was delegated to the host.
+        (0, trust_audit_1.recordTrustAuditEvent)(run, {
+            kind: "worker.sandbox-boundary",
+            decision: "allowed",
+            source: "cw-validated",
+            workerId,
+            taskId: scope.taskId,
+            sandboxProfileId: policy.id,
+            policyRef: `execute=${policy.execute.mode} network=${policy.network.mode} env.inherit=${policy.env.inherit}`,
+            command: policy.execute.mode,
+            networkTarget: policy.network.mode,
+            metadata: {
+                enforced_by_cw: ["write-paths"],
+                delegated_to_host: ["execute", "network", "env"],
+                env_inherit: policy.env.inherit
+            }
+        });
+    }
+    return violation;
 }
 function summarizeWorkers(run) {
     const workers = listWorkerScopes(run);

package/docs/agent-delegation-drive.7.md

@@ -27,6 +27,52 @@ HTTP API. Any API key comes from the agent's *own* inherited env; CW never reads
 or keeps a record of it. Adding a provider SDK to `package.json` would lose the
 neutral-audit moat and is the red line.
 
+## Architecture — the boundary (core ↔ agent backend ↔ wrappers)
+
+The core gives only an INTERFACE: the `agent` execution backend plus a small
+text/process contract. The four vendors (claude / codex / gemini / deepseek)
+live OUTSIDE the core as out-of-process wrapper scripts in `scripts/agents/` —
+pure config, never imported by `src/`, behind the same seam.
+
+```text
+                       user
+                       │  cw -q "…" -codex   (headline shortcut; also -claude/-gemini/-deepseek)
+                       ▼
+┌──────────── CW core  (src/ — zero runtime deps, imports NO model SDK, holds NO key) ───────────┐
+│                                                                                                │
+│  command-surface.ts        agent-config.ts                 execution-backend  ("agent" driver) │
+│  -codex → builtin:codex ─► builtin:<name> ─►               runAgentProcess:                     │
+│                            node <dir>/<name>-agent.js       spawnSync(binary, args, shell:false)│
+│                            {{input}} {{result}}            · inherits env  · captures stdout    │
+│                            (builtin-templates.json: DATA)  · records handle{process}+attestation│
+└───────────────────────────────────────┬───────────────────────────────────────────────────────┘
+     THE SEAM  (text / process contract) │
+       in : argv  {{input}}=worker input.md   {{result}}=worker result.md
+       out: wrapper writes result.md + ONE stdout JSON line {model,usage,result} → parseAgentReport
+                                         │
+   ── red line ──  core never reads a key; each wrapper resolves its OWN key from inherited env
+                                         │
+┌──────── external wrappers  (scripts/agents/*.js — "CONFIG, not a CW runtime dependency") ───────┐
+│   claude-p-agent.js     codex-agent.js      gemini-opencode-agent.js    deepseek-agent.js       │
+│        │                     │                        └──────────┬──────────────┘              │
+│        ▼                     ▼                                   ▼  (3-line shims)              │
+│   claude -p            codex exec                          opencode-agent.js                    │
+│   (Anthropic CLI)      (-c effort, sandbox)               opencode run --model …                │
+│                                                           (deepseek + gemini keys live here)    │
+└─────────────────────────────────────────────────────────────────────────────────────────────────┘
+   Add a vendor = drop a wrapper script + one line in builtin-templates.json — NO core edit.
+```
+
+Each box maps to one source seam: the flag map lives in `command-surface.ts`
+(`-codex` → `builtin:codex`); `agent-config.ts` expands `builtin:<name>` into
+`node <dir>/<name>-agent.js {{input}} {{result}}` by reading
+`builtin-templates.json` (the registry is DATA, not a kernel literal); the
+`agent` driver's `runAgentProcess` does the `spawnSync` and reads back the one
+stdout JSON line via `parseAgentReport`. So the four vendors are **delegated
+agent wrappers, not an event-"hook" system**. The seam is generic: any
+`CW_AGENT_COMMAND="node my-agent.js {{input}} {{result}}"` or a configured HTTP
+endpoint plugs in the same way — the four builtins are just bundled examples.
+
 ## Operator-chosen model is policy; agent-reported model is the attestation
 
 Any model id CW passes **into** the agent invocation (`CW_AGENT_MODEL`
@@ -250,7 +296,22 @@ The built-in templates are:
 claude and codex run their own CLIs; gemini and deepseek route through opencode
 (where their keys live), each proven by a local, deterministic wrapper smoke
 (override the model with CW_GEMINI_MODEL / CW_DEEPSEEK_MODEL). GLM stays an
-external agent command or HTTP endpoint. CW still imports no model SDK.
+external agent command or HTTP endpoint. CW still imports no model SDK. The same
+headline shortcuts pick these builtins on the top-level CLI: `cw -q "..."
+-claude` / `-codex` / `-gemini` / `-deepseek`.
+
+The codex wrapper caps codex's reasoning effort for CW runs so a heavy
+`model_reasoning_effort = "high"` in the user's `~/.codex/config.toml` does not
+make every read/grep turn slow. It passes `codex exec -c
+model_reasoning_effort=<effort>` (default `low`) for THAT run only — the user's
+interactive codex is untouched. Raise it with `CW_CODEX_REASONING_EFFORT`
+(`low` | `medium` | `high`).
+
+When an agent hop fails, CW core keeps only the child's stdout + exit code, so a
+bare `failed (exit 1)` hid the real cause (a relay 5xx, an auth error, a killed
+run). Each wrapper now also drops the failed child's stderr to
+`<run>/workers/<worker>/logs/agent-stderr.log`, so the reason is readable after
+the fact without changing the recorded, byte-stable evidence.
 
 ## Compatibility
 
@@ -346,3 +407,7 @@ The one-command `cw -q` headline now routes the question and defaults the repo t
 0.1.94
 
 0.1.95
+
+0.1.96
+
+0.1.97

package/docs/cli-mcp-parity.7.md

@@ -549,3 +549,7 @@ CLI golden-path fixes: `cw -q "…"` routes the question (was read as an app id
 0.1.94
 
 0.1.95
+
+0.1.96
+
+0.1.97

package/docs/contract-migration-tooling.7.md

@@ -167,3 +167,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.94
 
 0.1.95
+
+0.1.96
+
+0.1.97

package/docs/control-plane-scheduling.7.md

@@ -151,3 +151,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.94
 
 0.1.95
+
+0.1.96
+
+0.1.97

package/docs/demo.7.md

@@ -0,0 +1,80 @@
+# DEMO(7)
+
+## NAME
+
+`cw demo` — prove CW trust guarantees with one command
+
+## SYNOPSIS
+
+```text
+node dist/cli.js demo tamper [--json]
+node dist/cli.js demo bundle [--json]
+```
+
+## DESCRIPTION
+
+`cw demo` is a self-contained proof of CW's central trust claims. It works
+without an agent and without a network connection. Every run is hermetic
+(fully self-contained) — it builds its own state, tampers with it in known
+ways, and checks that the tampering is caught. Nothing is read from or
+written to the real file system outside a short-term temp directory.
+
+No agent is needed; both demos work when the setup has no agent at all.
+
+## DEMO TAMPER
+
+`cw demo tamper` proves that CW catches forged records offline — with only a
+public key, no server. It:
+
+1. Builds a signed telemetry ledger with three hops.
+2. Tampers with it in three layers:
+   - **Hashes**: Changes a record's data and recomputes the record hash to hide
+     it. The hash chain breaks — the next record's `previousHash` does not
+     match, so the chain is no longer valid.
+   - **Signatures**: Inflates token counts and keeps the old signature. The
+     signature does not match the new data — the verifier catches it.
+   - **Findings**: Edits a signed finding (severity HIGH → LOW) after it was
+     signed by the agent. The signature check on the ed25519 envelope fails
+     because the signed bytes changed.
+3. Verifies each tampered ledger with only the public key.
+
+If all three forgeries are caught, the proof holds and the demo exits 0.
+If any tamper goes undetected, the demo exits 1 — this is a regression in
+the integrity guarantee.
+
+## DEMO BUNDLE
+
+`cw demo bundle` proves that exported report bundles are verifiable offline. It:
+
+1. Builds a full telemetry chain, signs it, and exports a sealed portable
+   bundle (archive bytes + telemetry chain + trust-audit chain + embedded
+   public key).
+2. Tampers with the bundle in two ways:
+   - **Telemetry chain**: Forges a record in the chain. The archive's file
+     digests stay valid (the archive was built from the tampered bytes), but
+     `report verify-bundle` re-checks the chain and catches it.
+   - **Signature + usage**: Inflates token counts and reseals. The signature
+     check and hash chain both break.
+3. Verifies each tampered bundle with `report verify-bundle`.
+
+If all forgeries are caught with only the bundle's own public key, the proof
+holds. No repo, no server, no key handed over.
+
+## EXIT CODES
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | All tampering was caught — trust guarantees hold |
+| 1 | A tamper went undetected — integrity guarantee regression |
+
+## FILES
+
+```text
+src/telemetry-demo.ts
+```
+
+## SEE ALSO
+
+report-verifiable-bundle.7.md — offline bundle verification in detail
+trust-model.md — the trust model and its limits
+security-trust-hardening.7.md — security and trust hardening

package/docs/doctor.7.md

@@ -0,0 +1,97 @@
+# DOCTOR(7)
+
+## NAME
+
+`cw doctor` — check the setup and name all problems with their fixes
+
+## SYNOPSIS
+
+```text
+node dist/cli.js doctor
+node dist/cli.js doctor --json
+node dist/cli.js doctor --fix
+node dist/cli.js doctor --onramp
+node dist/cli.js doctor --onramp --changed-from origin/main
+```
+
+## DESCRIPTION
+
+`cw doctor` is a read-only check of your CW setup, based on `brew doctor`. It
+probes your machine and says what is wrong and what to do about it — before a
+run fails with a strange error.
+
+The command never makes any file; it only reads. Running it changes nothing on
+disk.
+
+It gives back a report with one line for every check. Each check has a status
+(`ok`, `warn`, or `fail`) and a clear note. Checks that are not `ok` carry a
+`fix` line with the right command or step to put things right.
+
+If any check has status `fail`, the command exits with code 1 (non-zero). A
+`warn` (for example, no agent yet — demos and previews still work) does not
+make the exit fail.
+
+## CHECKS
+
+The command runs six checks in order:
+
+**node**
+: The Node.js version. CW needs v18 or higher. A `fail` here stops everything.
+
+**agent**
+: The AI agent backend. CW can auto-detect agents (Claude, Codex, Gemini,
+OpenCode) or take one from `CW_AGENT_COMMAND` / `--agent-command`. Without one,
+real runs report `status: blocked`, but `demo` and `--preview` still work.
+
+**agent-binary**
+: When the agent is set by a command name (not auto or HTTP), this check sees if
+the binary is on `$PATH`. Missing here gives a `warn` — the run will get a clear
+error later, but CW will not guess at a different agent.
+
+**git**
+: The `git` command. CW uses it for commit place of origin. A `warn` here means
+commit roots will be recorded as absent; no other part of a run needs git.
+
+**home-registry**
+: The cross-repo run index at `$CW_HOME` (default `$HOME/.local/state/cool-workflow`).
+This location must be writable. A `fail` here blocks discovery across repos.
+
+**repo-state**
+: The per-repo run store under `<cwd>/.cw`. Must be writable. A `warn` here
+means runs stay in-memory only — you can use `--cwd PATH` to point at another
+writable root.
+
+## OPTIONS
+
+`--json`
+: Give back the full report as a stable JSON object. Good for scripts.
+
+`--fix`
+: Give back only the fix commands for every non-ok check. Same as running `cw fix`
+by itself.
+
+`--onramp`
+: Add a quick-start guide to the human output, with recommended checks and a
+three-step path to your first report.
+
+`--changed-from <ref>`
+: When used with `--onramp`, make the quick-start checks cover only files changed
+since `<ref>` (a Git branch, tag, or commit). Good for CI and code reading.
+
+## FILES
+
+```text
+src/doctor.ts
+dist/doctor.js
+```
+
+## EXIT CODES
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | All checks ok (may have warnings) |
+| 1 | One or more checks have status `fail` |
+
+## SEE ALSO
+
+cw fix — the same checks, but gives back only the fix commands

package/docs/durable-state-and-locking.7.md

@@ -150,3 +150,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.94
 
 0.1.95
+
+0.1.96
+
+0.1.97

package/docs/evidence-adoption-reasoning-chain.7.md

@@ -311,3 +311,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.94
 
 0.1.95
+
+0.1.96
+
+0.1.97

package/docs/execution-backends.7.md

@@ -341,3 +341,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.94
 
 0.1.95
+
+0.1.96
+
+0.1.97

package/docs/fix.7.md

@@ -0,0 +1,44 @@
+# FIX(7)
+
+## NAME
+
+`cw fix` — give back the fix commands for all setup problems
+
+## SYNOPSIS
+
+```text
+node dist/cli.js fix
+node dist/cli.js fix --json
+```
+
+## DESCRIPTION
+
+`cw fix` runs the same setup checks as `cw doctor`, but gives back only the
+fix commands — one numbered step for every check that has a problem. No
+running check detail, no status glyphs; just the directions you need to put
+things right.
+
+When the output is empty ("No fixes needed."), the setup is clean and nothing
+needs doing.
+
+Like `cw doctor`, the command only reads — it never makes a file or does a
+fix on its own. You are meant to run the fix commands yourself.
+
+If any check has status `fail`, the command exits with code 1.
+
+## OPTIONS
+
+`--json`
+: Give back the full doctor report as a stable JSON object, with the same shape
+as `cw doctor --json`. The `checks` array carries every fix string.
+
+## EXIT CODES
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | No fixes needed — all checks ok or only warnings |
+| 1 | One or more checks have status `fail` |
+
+## SEE ALSO
+
+cw doctor — the full setup check with detail for every check

package/docs/init.7.md

@@ -0,0 +1,62 @@
+# INIT(7)
+
+## NAME
+
+`cw init` — scaffold a new workflow definition from nothing
+
+## SYNOPSIS
+
+```text
+node dist/cli.js init <workflow-id> [--title TITLE] [--output PATH] [--force]
+```
+
+## DESCRIPTION
+
+`cw init` makes a new workflow definition file — a `.workflow.js` file filled
+with a simple template. The template has a basic run shape: one step with a
+sandbox profile, one evidence gate, and the hooks you need to add your own
+steps.
+
+This is how you start a new workflow app from zero. After `init`, you have a
+real file you can edit to make your own run shape.
+
+The workflow id you give is turned into a safe file name (spaces become dashes,
+special signs are taken out). By default, the file is written to the current
+working directory, but you can point it somewhere else with `--output`.
+
+If a file of that name is already there, the command refuses to overwrite it
+unless you pass `--force`.
+
+## OPTIONS
+
+`--title TITLE`
+: A human name for the workflow. If not given, a title is made from the id.
+
+`--output PATH`
+: Where to write the workflow file. Default is `<id>.workflow.js` in the
+current directory.
+
+`--force`
+: Overwrite an existing file. Without this flag, the command fails if the
+file already exists.
+
+## EXIT CODES
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | Workflow file written |
+| 1 | Missing workflow id, invalid id, or file exists without `--force` |
+
+## FILES
+
+```text
+src/orchestrator.ts (init method)
+src/workflow-app-framework.ts (template renderer)
+```
+
+## SEE ALSO
+
+cw list — see all workflow apps you have
+cw info <id> — read the shape of a workflow app
+workflow-app-framework.7.md — the full framework for writing workflow apps
+pipeline-verbs.7.md — plan, dispatch, result (the pipeline engine)

package/docs/multi-agent-cli-mcp-surface.7.md

@@ -317,3 +317,7 @@ The host-facing surface tracks the CLI golden-path fixes (`cw -q` routing + repo
 0.1.94
 
 0.1.95
+
+0.1.96
+
+0.1.97

package/docs/multi-agent-eval-replay-harness.7.md

@@ -343,3 +343,7 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 0.1.94
 
 0.1.95
+
+0.1.96
+
+0.1.97