cool-workflow 0.1.87 → 0.1.89

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cool-workflow",
   "description": "A workflow control plane and run-time you are able to check: it sends out jobs in TypeScript, makes certain of work against facts before it goes through, puts state into fixed records, orders jobs by time, runs jobs again and again, gets a group of agents to do their parts together, and talks MCP. It gives the doing of the work to outside agents — it never runs the models itself.",
-  "version": "0.1.87",
+  "version": "0.1.89",
   "author": {
     "name": "COOLWHITE LLC"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.1.87",
+  "version": "0.1.89",
   "description": "A workflow control plane and run-time you are able to check: it sends out jobs in TypeScript, makes certain of work against facts before it goes through, puts state into fixed records, orders jobs by time, runs jobs again and again, gets a group of agents to do their parts together, and talks MCP. It gives the doing of the work to outside agents — it never runs the models itself.",
   "author": {
     "name": "COOLWHITE LLC"

package/README.md

@@ -1,122 +1,139 @@
+<div align="center">
+
 # Cool Workflow
 
-```text
-══════════════════════════════════════════════════════════════════════
-  auditable agent-workflow control-plane — delegate, don't execute
-  plan → dispatch → record → verify → commit → report
-══════════════════════════════════════════════════════════════════════
-```
+**Get a saved, cited report from your AI agent — not a chat message you lose.**
 
 [![CI](https://img.shields.io/github/actions/workflow/status/coo1white/cool-workflow/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/coo1white/cool-workflow/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/cool-workflow?style=flat-square&label=npm&color=cb3837)](https://www.npmjs.com/package/cool-workflow)
 [![downloads](https://img.shields.io/npm/dm/cool-workflow?style=flat-square&label=downloads)](https://www.npmjs.com/package/cool-workflow)
+[![provenance](https://img.shields.io/badge/npm-provenance-3178C6?style=flat-square)](https://www.npmjs.com/package/cool-workflow)
 [![release](https://img.shields.io/github/v/tag/coo1white/cool-workflow?style=flat-square&label=release&color=brightgreen&sort=semver)](https://github.com/coo1white/cool-workflow/tags)
-[![license](https://img.shields.io/badge/license-BSD--2--Clause-blue?style=flat-square)](../../LICENSE)
+[![license](https://img.shields.io/badge/license-BSD--2--Clause-blue?style=flat-square)](https://github.com/coo1white/cool-workflow/blob/main/LICENSE)
 ![MCP](https://img.shields.io/badge/MCP-native-8A2BE2?style=flat-square)
 ![runtime](https://img.shields.io/badge/runtime-TypeScript%20%C2%B7%20Node-3178C6?style=flat-square)
 
-**[Start Here](#start-here)** · [Quickstart](#quickstart) · [Developer Loop](#developer-loop) · [Commands](#commands) · [Release History](docs/release-history.md)
+<img src="https://raw.githubusercontent.com/coo1white/cool-workflow/main/docs/assets/cool-workflow-readme-promo.png" alt="Cool Workflow turns AI agent repo questions into saved, cited, tamper-evident reports." width="100%">
 
-Cool Workflow, or CW, is a free-standing agent workflow control-plane put up as a
-TypeScript runtime. It gives a COL-Architecture: Router / Orchestrator,
-Subagent Dispatch, Deterministic Harness, Adversarial Verifier, Git/State
-Commit, and MCP JSON-RPC 2.0 bridge.
+</div>
 
-The way to see it is a base system plus userland apps: CW gives the runtime and
-contracts, while makers write apps they can use again in
-`apps/<app-id>/app.json`. Old `workflows/*.workflow.js` files still
-load as fit-together wrappers.
+> An auditable agent-workflow control-plane — **delegate, don't execute**.
+> `plan → dispatch → record → verify → commit → report`
 
-CW writes down the model workflow loop in a clear way:
+## Install
 
-```text
-interpret -> act -> observe -> adjust -> checkpoint
+```bash
+npm install -g cool-workflow
 ```
 
-These loop stages are kept in `state.json`, task records, reports, and state
-commit snapshots.
-
-CW keeps orchestration state and task queues in files. An agent host does
-the tasks and gives results back to the workflow.
-
-CW keeps to a small set of Unix-based workflow rules: small kernel,
-clear state, pipes that join, workers kept apart, and verifier-gated commits.
-See [docs/unix-principles.md](docs/unix-principles.md).
+What you need: **Node.js v18+** (`node --version`) and one AI agent CLI on your machine
+(`claude`, `codex`, `gemini`, or `opencode`). No agent? `cw demo` still works — CW never runs a model itself.
 
-## Start Here
+## Quick Start (3 steps)
 
-Use the short path first. The long notes below are history and deep reference,
-not the first run.
+### 1. Prove it works (30 seconds, no agent needed)
 
 ```bash
 cw demo tamper
-cw doctor --onramp
-cw quickstart architecture-review --check --repo /path/to/repo \
-  --question "What are the main risks?" --agent-command builtin:claude
-cw quickstart architecture-review --repo /path/to/repo \
-  --question "What are the main risks?" --agent-command builtin:claude --bundle
-cw report verify-bundle report.cwrun.json
+# → VERDICT: tamper-evidence holds ✓
 ```
 
-For source work, keep the loop small:
+### 2. Run a review on your code — one command
 
 ```bash
-npm run build
-node test/<nearest-smoke>.js
-npm run test:fast
+cw -q "What are the main risks here?"
 ```
 
-Run `npm run release:check` only when the batch is ready for the full gate. Start
-with `quickstart` and `report` before the multi-agent pages.
+CW auto-detects the repo (current folder) and your agent (first found on PATH).
+Pick a specific agent with a flag:
 
-For the full capability and release history, see [docs/release-history.md](docs/release-history.md).
-This README tracks CW v0.1.85.
+```bash
+cw -q "What are the security risks?" -claude
+cw -q "What are the security risks?" -codex
+cw -q "What are the security risks?" -deepseek
+```
 
-## Quickstart
+You will see live streaming output as the agent works — no env vars needed.
 
-**30-second proof, no install** — see that a recorded telemetry verdict can't be faked:
+### 3. Open the report
 
 ```bash
-npx cool-workflow demo tamper
-# builds a signed ed25519 ledger, forges it 2 ways, both caught offline
-# -> VERDICT: tamper-evidence holds ✓
+cat .cw/runs/<run-id>/report.md
+# → findings with clickable file.ts:42 pointers for every claim
 ```
 
-**Try a real run** — no clone needed; drive an architecture review with your own agent:
+## What Else Can It Do?
 
 ```bash
-npx cool-workflow quickstart architecture-review --repo /path/to/repo \
-  --question "Is this architecture sound?" --agent-command builtin:claude
+cw version                        # show version
+cw update                         # update to latest release
+cw doctor                         # check your setup
+cw fix                            # show fix commands for setup issues
 ```
 
-Add `--bundle` when the report has to go to someone else; then check the file
-offline with `cw report verify-bundle report.cwrun.json`.
+| Workflow | Does |
+|---|---|
+| `architecture-review` | Map a repo, rank risks, back every claim with evidence |
+| `pr-review-fix-ci` | Review a pull request, suggest fixes, verify CI |
+| `research-synthesis` | Answer a question with fact-backed research |
+| `release-cut` | Run a gated, reviewed release |
+
+**Multi-agent, when you need it.** Fan work out across agents with built-in topologies,
+compose flows (a task can run a whole child workflow with `subWorkflow`, or a `loop()` phase
+can keep iterating until a predicate or a token budget says stop) — and re-run fast:
+`cw run <app> --drive --incremental` reuses every step whose inputs didn't change.
 
-CW DELEGATES worker execution to your own agent. With no `--agent-command` (or
-`CW_AGENT_COMMAND`) the drive fails closed (status `blocked`) — it never makes up a
-result. `--agent-command builtin:claude` points to a bundled read-only `claude -p`
-wrapper (needs `claude` on your PATH). `--agent-command builtin:codex` points to
-the bundled read-only Codex wrapper (needs `codex` on your PATH). With
-`CW_AGENT_STREAM=1`, both wrappers can show a live stderr trace while stdout stays
-the kept data channel.
+CW also has an **MCP** surface — **Claude Desktop, Cursor, and VS Code call CW as a tool**, so
+your agent can plan a run, drive it, and verify a report without leaving the editor.
 
-**Re-prove a finished run, offline** (`cw` is the installed bin; or `npx cool-workflow <cmd>`):
+## Can I Trust the Report?
+
+CW does not run the AI model — it keeps the books. The agent signs its findings (ed25519), and
+`cw report verify-bundle` checks — offline, with nothing but the public key — that every signed
+finding is in the report **unaltered**: edit a finding, in the report or in the agent's own result,
+and the check fails. CW holds no private key — the agent signs, CW only verifies.
 
 ```bash
-cw telemetry verify <run-id>                  # re-checks the hash-chained ledger
-cw telemetry verify <run-id> --pubkey pub.pem # also re-runs ed25519 signature checks
-cw audit verify <run-id>                      # re-proves the trust-audit hash chain
+cw demo tamper                              # proves it in 30s — edits a signed result, watch it fail
+cw telemetry verify <run-id>                # checks a real run
+cw audit verify <run-id>                    # re-proves the trust-audit hash chain
 ```
 
-More: `cw quickstart <app> --preview` (read-only dry run), `cw run resume <run-id> --drive`
-(go on with a run that was stopped), `cw run inspect-archive <archive>` (integrity-check a
-portable run archive without bringing it in).
+Give the report to another person — they need nothing but the file:
+
+```bash
+cw -q "…" --bundle                              # seal into one portable file
+cw report verify-bundle report.cwrun.json       # they check it offline
+cw report verify-bundle report.cwrun.json \
+  --require-signatures                          # …and insist the findings are signed
+```
+
+This attests the agent's **signed findings** — not that the report holds nothing else, and not that
+none were left out. CW has no key to sign the rendered report, and a determined re-chainer can drop a
+signed finding entirely — so check the findings you act on against the signed results. For exactly
+what is and is not proven, see the [Trust Model](docs/trust-model.md).
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| No agent found | Run `cw doctor` — it shows which agents are on your machine |
+| `status: blocked` | CW failing closed (it never makes up a result). Set `CW_AGENT_COMMAND=builtin:claude` or pass `-claude`; `cw doctor` names the exact reason |
+| `claude: command not found` | Install Claude Code (`npm install -g @anthropic-ai/claude-code`) and run again |
+| Where is my report? | `<repo>/.cw/runs/<id>/report.md` |
+| Preflight before a spawn | `cw quickstart --check` — a zero-write check |
+
+---
+
+The rest of this README is the **developer / operator reference**: the build loop, repo
+structure, the full command surface, scheduling, and the result-envelope contract.
 
 ## Developer Loop
 
-Use the shortest check that fits the change:
+Use the shortest check that fits the change (from `plugins/cool-workflow/`):
 
 ```bash
+cd plugins/cool-workflow
 npm run build
 node test/<nearest-smoke>.js
 npm run test:fast
@@ -189,6 +206,22 @@ node scripts/cw.js app package architecture-review
 node scripts/cw.js app init my-app --title "My App"
 ```
 
+Compose flows from smaller verified ones (app-authoring surface, `workflow-api.ts`):
+
+- **Sub-workflow nesting** — a task can run a whole child app instead of one agent:
+  `subWorkflow(id, appId, { inputs?, bindResult? })`. The drive plans and drives the
+  child, then binds its report (or verdict result) back as the task's result, so the
+  parent's verifier/schema gate consumes it like any other. Leaf work stays external-agent
+  delegation at every depth; recursion is depth- and cycle-bounded, fail-closed.
+- **Bounded dynamic loops** — converge without unbounded recursion:
+  `loop(name, tasks, { maxRounds, until })` is a per-round template. After each round a
+  named, registered pure predicate (`until: { kind: "predicate", ref }`) decides whether to
+  append another round or stop, hard-capped at `maxRounds`; built-ins `no-new-findings` and
+  `single-round`. Or scale by budget — `until: { kind: "budget-target", target }` keeps
+  going while recorded (attested-only) usage stays under `target`, with the fail-closed
+  `limits.tokenBudget` cap as the absolute backstop. Predicates are registry refs (not
+  closures), so runs replay byte-identically; an unregistered predicate stops fail-closed.
+
 Create a reusable workflow script:
 
 ```bash
@@ -325,6 +358,7 @@ node scripts/cw.js registry refresh --scope home
 node scripts/cw.js run search --app architecture-review --status failed
 node scripts/cw.js run show <run-id>
 node scripts/cw.js run resume <run-id>
+node scripts/cw.js run resume <run-id> --drive --incremental   # re-drive, reusing every step whose inputs are unchanged
 node scripts/cw.js run rerun <failed-run-id> --reason "retry"
 node scripts/cw.js run archive <run-id> --reason "old"
 node scripts/cw.js queue add --app release-cut --priority 10
@@ -428,7 +462,13 @@ Verification and synthesis tasks need a structured result block:
 ```
 ````
 
-v0.1.86
+## 0.1.89 (v0.1.89)
+
+Headline golden-path fixes: `cw -q "question"` asks the question (was read as an app id), auto-detects the cwd as the repo (run anywhere, no `--repo`/`cd`), and `cw help` renders a clean wrapped command list with a trailing newline; plus a vendor-agnostic UI/UX prevention gate (a headline-command smoke + a real `npm install -g` run-from-anywhere smoke) so a CLI-surface regression can't ship invisibly again.
+
+## 0.1.88 (v0.1.88)
+
+Orchestration-parity for the agent drive — inline `subWorkflow()` nesting, bounded dynamic `loop()` phases (a `predicate` or a `budget-target` token `until`), and `cw run --drive --incremental` step-level resume; the agent now signs its findings (result-bound ed25519) and `cw report verify-bundle --require-signatures` proves offline that every signed finding is in the report unaltered; CLI simplified to 6 commands with agent streaming on by default; path-traversal run ids refused on archive import.
 
 ## 0.1.87 (v0.1.87)
 

package/apps/architecture-review/app.json

@@ -3,7 +3,7 @@
   "id": "architecture-review",
   "title": "Architecture Review",
   "summary": "Map a repository architecture, assess risks, verify important findings, and synthesize an evidence-backed verdict.",
-  "version": "0.1.87",
+  "version": "0.1.89",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/architecture-review-fast/app.json

@@ -3,7 +3,7 @@
   "id": "architecture-review-fast",
   "title": "Architecture Review Fast",
   "summary": "Run a shorter architecture review with parallel map and assess phases for faster first results.",
-  "version": "0.1.87",
+  "version": "0.1.89",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/end-to-end-golden-path/app.json

@@ -3,7 +3,7 @@
   "id": "end-to-end-golden-path",
   "title": "End-to-End Golden Path",
   "summary": "Deterministic one-worker workflow app for proving the CW integration chain.",
-  "version": "0.1.87",
+  "version": "0.1.89",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/pr-review-fix-ci/app.json

@@ -3,7 +3,7 @@
   "id": "pr-review-fix-ci",
   "title": "PR Review Fix CI",
   "summary": "Review a pull request or branch, inspect CI failures, diagnose actionable issues, optionally patch, verify, and summarize with evidence.",
-  "version": "0.1.87",
+  "version": "0.1.89",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/release-cut/app.json

@@ -3,7 +3,7 @@
   "id": "release-cut",
   "title": "Release Cut",
   "summary": "Prepare a release with checklist discipline: version checks, changelog, tests, packaging, release notes, and final verification.",
-  "version": "0.1.87",
+  "version": "0.1.89",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/research-synthesis/app.json

@@ -3,7 +3,7 @@
   "id": "research-synthesis",
   "title": "Research Synthesis",
   "summary": "Split a research question into claims, investigate sources, cross-check evidence, verify claims, and synthesize a concise answer.",
-  "version": "0.1.87",
+  "version": "0.1.89",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/dist/agent-config.js

@@ -146,6 +146,31 @@ function agentConfigFromArgs(args) {
 // in scripts/agents/builtin-templates.json (vendor name -> wrapper script name).
 // Adding a vendor is a content/distribution step (drop a wrapper + a JSON line),
 // not a kernel edit — keeping CW vendor-agnostic at the source level.
+/** Detect which known agent CLIs are on PATH. Returns the first found, or undefined.
+ *  Skipped when CW_NO_AUTO_AGENT=1 (test sandboxes, CI without real agents). */
+function detectAgentFromPath(env = process.env) {
+    if (env.CW_NO_AUTO_AGENT === "1")
+        return undefined;
+    const known = ["claude", "codex", "gemini", "opencode"];
+    const dirs = (env.PATH || "").split(node_path_1.default.delimiter).filter(Boolean);
+    const exts = process.platform === "win32" ? (env.PATHEXT || ".EXE;.CMD;.BAT").split(";") : [""];
+    for (const name of known) {
+        // Also check if the builtin template exists (so we don't suggest an unsupported agent).
+        const templates = builtinAgentTemplates();
+        if (!templates[name])
+            continue;
+        for (const dir of dirs) {
+            for (const ext of exts) {
+                try {
+                    if (node_fs_1.default.statSync(node_path_1.default.join(dir, name + ext)).isFile())
+                        return name;
+                }
+                catch { /* keep looking */ }
+            }
+        }
+    }
+    return undefined;
+}
 function builtinAgentTemplates() {
     const agentsDir = node_path_1.default.join(__dirname, "..", "scripts", "agents");
     const manifest = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(agentsDir, "builtin-templates.json"), "utf8"));
@@ -186,7 +211,23 @@ function resolveAgentConfig(args = {}, env = process.env) {
             : fileCfg && (fileCfg.command || fileCfg.endpoint)
                 ? "file"
                 : "none";
-    return { schemaVersion: 1, command, args: cfgArgs, endpoint, model, timeoutMs, attestPublicKey, requireAttestedTelemetry, source };
+    // Auto-detect: if no agent is configured, check PATH for known agent CLIs and
+    // resolve via builtin:<name>. This makes `cw quickstart` work without
+    // --agent-command on machines where claude/codex/gemini/opencode are installed.
+    let finalCommand = command;
+    let finalSource = source;
+    let finalModel = model;
+    if (!finalCommand && !endpoint) {
+        const detected = detectAgentFromPath(env);
+        if (detected) {
+            finalCommand = expandBuiltinAgentCommand(`builtin:${detected}`);
+            finalSource = "auto";
+            // Store the detected vendor name as the model hint so doctor can show it.
+            if (!finalModel)
+                finalModel = `builtin:${detected}`;
+        }
+    }
+    return { schemaVersion: 1, command: finalCommand, args: cfgArgs, endpoint, model: finalModel, timeoutMs, attestPublicKey, requireAttestedTelemetry, source: finalSource };
 }
 /** True iff a command-template OR endpoint is configured (after resolution). */
 function agentConfigured(args = {}, env = process.env) {

package/dist/capability-core.js

@@ -324,7 +324,8 @@ function reportBundle(runner, runId, args) {
     const verification = (0, run_export_1.verifyReportBundle)(exported.path, {
         pubkey: optionalString(args.pubkey || args.pubKey || args.publicKey),
         extractReportTo: extractReportTo ? node_path_1.default.resolve(base, extractReportTo) : undefined,
-        strictSignatures: Boolean(args["strict-signatures"] || args.strictSignatures || args.strictSigs)
+        strictSignatures: Boolean(args["strict-signatures"] || args.strictSignatures || args.strictSigs),
+        requireSignatures: Boolean(args["require-signatures"] || args.requireSignatures || args.requireSigs)
     });
     return {
         schemaVersion: 1,
@@ -349,7 +350,8 @@ function runVerifyReportBundle(_runner, args) {
     return (0, run_export_1.verifyReportBundle)(node_path_1.default.resolve(base, archive), {
         pubkey: optionalString(args.pubkey || args.pubKey || args.publicKey),
         extractReportTo: extractReportTo ? node_path_1.default.resolve(base, extractReportTo) : undefined,
-        strictSignatures: Boolean(args["strict-signatures"] || args.strictSignatures || args.strictSigs)
+        strictSignatures: Boolean(args["strict-signatures"] || args.strictSignatures || args.strictSigs),
+        requireSignatures: Boolean(args["require-signatures"] || args.requireSignatures || args.requireSigs)
     });
 }
 function queueAdd(reg, args) {
@@ -494,7 +496,8 @@ const DRIVE_RUNTIME_KEYS = [
     "agent-model",
     "agentTimeoutMs",
     "agent-timeout-ms",
-    "resume"
+    "resume",
+    "incremental"
 ];
 function planInputsFor(args) {
     const copy = withoutRuntimeKeys(args);
@@ -527,6 +530,7 @@ function runDrive(runner, args) {
     return (0, drive_1.drive)(runner.withBaseDir(target), driveRunId, {
         once: isTrue(args.once),
         now: optionalString(args.now),
+        incremental: isTrue(args.incremental),
         args
     });
 }
@@ -544,6 +548,13 @@ exports.QUICKSTART_DEFAULT_APP = "architecture-review";
  *  the drive fails closed (status=blocked) and we never fabricate a completion. */
 function quickstart(runner, args) {
     const appId = String(args.appId || args.app || args.workflowId || exports.QUICKSTART_DEFAULT_APP);
+    // Run anywhere (like brew): default the repo-under-review to the caller's cwd when no
+    // --repo/--cwd is given, mirroring quickstartCheck — so `cw -q "…"` works from any
+    // project directory without a flag, instead of failing validateInputs with "Missing
+    // required input --repo".
+    if (!optionalString(args.repo) && !optionalString(args.cwd)) {
+        args.repo = invocationCwd(args);
+    }
     const agentConfigured = Boolean((0, agent_config_1.resolveAgentConfig)(args).command || (0, agent_config_1.resolveAgentConfig)(args).endpoint);
     if (isTrue(args.check))
         return quickstartCheck(runner, appId, args, agentConfigured);
@@ -970,7 +981,8 @@ function auditVerify(runner, args) {
 }
 // ---- demo: tamper-evidence (the one-command proof) -------------------------
 // Hermetic, deterministic-shape: builds a real ed25519-signed telemetry ledger,
-// then forges it two ways and shows both tamper-evidence layers catch it. CLI-only
+// then forges it three ways and shows all three tamper-evidence layers (ledger,
+// signature, result) catch it. CLI-only
 // (a human-facing demonstration; the underlying verify is the telemetry.verify verb).
 function demoTamper(_runner, _args = {}) {
     return (0, telemetry_demo_1.runTamperDemo)();

package/dist/capability-registry.js

@@ -53,6 +53,30 @@ const BUILTIN_CAPABILITIES = [
         cli: { path: ["help"], jsonMode: "human" },
         reason: "Human help text. MCP hosts enumerate capabilities via tools/list, not a help command."
     },
+    {
+        capability: "version",
+        summary: "Print the current cool-workflow version.",
+        entry: "CURRENT_COOL_WORKFLOW_VERSION",
+        surface: "cli-only",
+        cli: { path: ["version"], jsonMode: "human" },
+        reason: "Version string — no structured data contract."
+    },
+    {
+        capability: "update",
+        summary: "Update cool-workflow to the latest release via npm.",
+        entry: "npmUpdate",
+        surface: "cli-only",
+        cli: { path: ["update"], jsonMode: "human" },
+        reason: "Self-update via npm — inherently local shell operation, no MCP surface."
+    },
+    {
+        capability: "fix",
+        summary: "Print consolidated fix commands for CW setup issues.",
+        entry: "runDoctor",
+        surface: "cli-only",
+        cli: { path: ["fix"], jsonMode: "human" },
+        reason: "Environment fix commands are local diagnostics, same reasoning as doctor."
+    },
     {
         capability: "list",
         summary: "List bundled CW workflows.",

package/dist/cli/command-surface.js

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -6,6 +39,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.runCli = runCli;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const readline = __importStar(require("node:readline"));
 const orchestrator_1 = require("../orchestrator");
 const capability_core_1 = require("../capability-core");
 const observability_1 = require("../observability");
@@ -24,8 +59,38 @@ const evidence_reasoning_1 = require("../evidence-reasoning");
 const doctor_1 = require("../doctor");
 const orchestrator_2 = require("../orchestrator");
 const term_1 = require("../term");
+const version_1 = require("../version");
 async function runCli(argv = process.argv.slice(2)) {
     const args = (0, orchestrator_1.parseArgv)(argv);
+    // Top-level flags: accept --version / -v / --help / -h before command lookup.
+    if (args.command?.startsWith("-") || !args.command) {
+        if (args.command === "--version" || args.command === "-v" || args.options.v || args.options.version) {
+            process.stdout.write(`${version_1.CURRENT_COOL_WORKFLOW_VERSION}\n`);
+            return;
+        }
+        if (!args.command || args.command === "--help" || args.command === "-h" || args.options.h || args.options.help) {
+            process.stdout.write((0, orchestrator_1.formatHelp)() + "\n");
+            return;
+        }
+    }
+    // Map vendor shorthand flags (-claude, -codex, -deepseek) to --agent-command.
+    if (args.options.claude)
+        args.options["agent-command"] = "builtin:claude";
+    if (args.options.codex)
+        args.options["agent-command"] = "builtin:codex";
+    if (args.options.deepseek)
+        args.options["agent-command"] = "builtin:deepseek";
+    // Bare -q / --question -> redirect to quickstart (auto-detect repo/agent/app).
+    // CONSUME the positional (shift) so the question never survives as positionals[0]
+    // — otherwise the quickstart handler reads it as the app id ("Workflow app not found").
+    if (args.command === "-q" || args.command === "--question") {
+        if (!args.options.question && args.positionals[0])
+            args.options.question = args.positionals.shift();
+        args.command = "quickstart";
+    }
+    else if (!args.command && typeof args.options.question === "string") {
+        args.command = "quickstart";
+    }
     const runner = new orchestrator_1.CoolWorkflowRunner({
         pluginRoot: node_path_1.default.resolve(__dirname, "../..")
     });
@@ -34,8 +99,31 @@ async function runCli(argv = process.argv.slice(2)) {
     switch (args.command) {
         case "help":
         case undefined:
-            process.stdout.write((0, orchestrator_1.formatHelp)());
+            process.stdout.write((0, orchestrator_1.formatHelp)() + "\n");
+            return;
+        case "version":
+            process.stdout.write(`${version_1.CURRENT_COOL_WORKFLOW_VERSION}\n`);
             return;
+        case "update": {
+            process.stderr.write("Updating cool-workflow...\n");
+            const npm = (0, node_child_process_1.spawnSync)("npm", ["update", "-g", "cool-workflow"], { encoding: "utf8", stdio: "inherit" });
+            if (npm.status !== 0) {
+                process.stderr.write("Update failed, trying install...\n");
+                const install = (0, node_child_process_1.spawnSync)("npm", ["install", "-g", "cool-workflow@latest"], { encoding: "utf8", stdio: "inherit" });
+                if (install.status !== 0) {
+                    process.stderr.write("Install failed. Check npm and try again.\n");
+                    process.exitCode = 1;
+                }
+            }
+            return;
+        }
+        case "fix": {
+            const report = (0, doctor_1.runDoctor)(args.options, process.env, String(args.options.cwd || process.cwd()));
+            process.stdout.write(`${(0, doctor_1.formatDoctorFixes)(report)}\n`);
+            if (!report.ok)
+                process.exitCode = 1;
+            return;
+        }
         case "list":
             printJson(runner.listWorkflows());
             return;
@@ -144,6 +232,7 @@ async function runCli(argv = process.argv.slice(2)) {
             // fails closed (status=blocked) when none is set. No new executor/scheduler.
             const [appId] = args.positionals;
             const runId = optionalArg(args.options.run) || optionalArg(args.options.runId);
+            await promptQuestion(args.options);
             const qs = (0, capability_core_1.quickstart)(runner, { ...args.options, ...(appId ? { appId } : {}), ...(runId ? { runId } : {}) });
             printJson(qs);
             const qr = qs;
@@ -1202,7 +1291,7 @@ async function runCli(argv = process.argv.slice(2)) {
                     return;
                 }
                 default:
-                    throw new Error("Usage: cw.js run search|list|show|resume|archive|rerun|drive|export|import|verify-import|inspect-archive [run-id|archive] [--scope repo|home] [--json]  |  cw.js run <app> --drive [--once] [--repo R --question Q]");
+                    throw new Error("Usage: cw.js run search|list|show|resume|archive|rerun|drive|export|import|verify-import|inspect-archive [run-id|archive] [--scope repo|home] [--json]  |  cw.js run <app> --drive [--once] [--incremental] [--repo R --question Q]");
             }
         }
         case "queue": {
@@ -1419,6 +1508,20 @@ function printJson(value) {
 function wantsJson(options) {
     return Boolean(options.json || options.format === "json");
 }
+/** Prompt the user for a question interactively when --question is missing on a TTY. */
+async function promptQuestion(options) {
+    if (options.question || !process.stdin.isTTY)
+        return;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => {
+        rl.question("Question: ", (answer) => {
+            rl.close();
+            if (answer.trim())
+                options.question = answer.trim();
+            resolve();
+        });
+    });
+}
 function formatWorkbenchView(view) {
     const lines = [
         `Workbench view ${view.runId} (${view.resolved ? "resolved" : "UNRESOLVED"})`,