cool-workflow 0.1.90 → 0.1.92

package/dist/capability-core.js

@@ -56,6 +56,7 @@ exports.schedPolicyShow = schedPolicyShow;
 exports.schedPolicySet = schedPolicySet;
 exports.runDrivePreview = runDrivePreview;
 exports.runDrive = runDrive;
+exports.collectRunFindings = collectRunFindings;
 exports.quickstart = quickstart;
 exports.backendAgentConfigShow = backendAgentConfigShow;
 exports.backendAgentConfigSet = backendAgentConfigSet;
@@ -83,6 +84,7 @@ const remote_source_1 = require("./remote-source");
 const telemetry_demo_1 = require("./telemetry-demo");
 const state_1 = require("./state");
 const run_export_1 = require("./run-export");
+const result_normalize_1 = require("./result-normalize");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const scheduling_1 = require("./scheduling");
@@ -553,6 +555,35 @@ exports.QUICKSTART_DEFAULT_APP = "architecture-review";
  *  RED LINE (DIRECTION.md): worker execution still DELEGATES to the operator's own
  *  agent backend (claude -p / codex exec / HTTP endpoint). With no agent configured
  *  the drive fails closed (status=blocked) and we never fabricate a completion. */
+/** Collect a COMPACT findings list for the end-of-run summary by re-parsing each completed
+ *  worker's `result.md` `cw:result` block (the schema source of truth — `normalizeResultEnvelope`).
+ *  Stderr/human-side ONLY: this NEVER touches the byte-exact stdout payload, so it cannot perturb
+ *  `--json` or the `cw:result` fence. `baseDir` anchors to the run's OWN repo (quickstart may run
+ *  cross-directory). Best-effort: a missing/garbled result.md or an unloadable run is skipped, not
+ *  fatal — the full prose still lives in report.md + each worker transcript. */
+function collectRunFindings(runner, runId, baseDir) {
+    const rows = [];
+    try {
+        const run = runner.withBaseDir(baseDir).loadRun(runId);
+        for (const task of run.tasks) {
+            if (task.status !== "completed" || !task.resultPath || !node_fs_1.default.existsSync(task.resultPath))
+                continue;
+            try {
+                const envelope = (0, result_normalize_1.normalizeResultEnvelope)(node_fs_1.default.readFileSync(task.resultPath, "utf8"));
+                for (const f of envelope.findings) {
+                    rows.push({ id: f.id, severity: f.severity || "none", classification: f.classification || "unknown" });
+                }
+            }
+            catch {
+                /* skip a garbled result.md — the transcript still holds the full record */
+            }
+        }
+    }
+    catch {
+        /* run not loadable on this host — the summary degrades to no findings table */
+    }
+    return rows;
+}
 function quickstart(runner, args) {
     const appId = String(args.appId || args.app || args.workflowId || exports.QUICKSTART_DEFAULT_APP);
     // Remote source (v0.1.91): a `--link <url>` — or a URL passed to `--repo`/`-dir` — is

package/dist/cli/command-surface.js

@@ -58,7 +58,7 @@ const state_explosion_1 = require("../state-explosion");
 const evidence_reasoning_1 = require("../evidence-reasoning");
 const doctor_1 = require("../doctor");
 const orchestrator_2 = require("../orchestrator");
-const term_1 = require("../term");
+const reporter_1 = require("../reporter");
 const version_1 = require("../version");
 async function runCli(argv = process.argv.slice(2)) {
     const args = (0, orchestrator_1.parseArgv)(argv);
@@ -84,6 +84,18 @@ async function runCli(argv = process.argv.slice(2)) {
     // so `cw -q "…" -dir /path` works from any directory (no cd). Explicit --repo wins.
     if (!args.options.repo && args.options.dir)
         args.options.repo = args.options.dir;
+    // Presentation flags — set BEFORE any drive spawn so the out-of-process agent wrapper
+    // inherits them via process.env (presentation-only; stdout/the cw:result fence are untouched):
+    //   --verbose   full agent narration inline (default is compact: current action + summary)
+    //   --no-color  disable ANSI everywhere (CW_NO_COLOR is honored by term.colorEnabled AND the
+    //               wrapper); complements NO_COLOR/FORCE_COLOR
+    //   --full      also stream full narration AND print the report inline at run end
+    if (args.options.verbose)
+        process.env.CW_VERBOSE = "1";
+    if (args.options["no-color"])
+        process.env.CW_NO_COLOR = "1";
+    if (args.options.full)
+        process.env.CW_OUTPUT = "full";
     // 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").
@@ -240,15 +252,17 @@ async function runCli(argv = process.argv.slice(2)) {
             const qs = (0, capability_core_1.quickstart)(runner, { ...args.options, ...(appId ? { appId } : {}), ...(runId ? { runId } : {}) });
             printJson(qs);
             const qr = qs;
-            // Clean human summary on stderr (TTY-gated). Suppressed under --json so machine
-            // mode emits ONLY the stdout payload — no stderr chrome to parse around. The
-            // type guard also skips --check/--preview results (no reportPath of their own).
+            // Clean human summary on stderr (TTY-gated, inside the reporter). Suppressed under --json so
+            // machine mode emits ONLY the stdout payload — no stderr chrome to parse around. The type
+            // guard also skips --check/--preview results (no reportPath of their own). The summary is the
+            // COMPACT findings table (re-parsed from each completed worker's cw:result), the report path,
+            // and where the per-worker transcripts live — NOT the full prose (that's report.md/--full).
             if (!wantsJson(args.options) && typeof qr.runId === "string" && typeof qr.reportPath === "string") {
-                (0, term_1.printSuccessSummary)({
+                emitRunSummary(runner, args.options, {
                     runId: qr.runId,
                     reportPath: qr.reportPath,
                     status: String(qr.status || ""),
-                    bundle: Boolean(args.options.bundle),
+                    statePath: typeof qr.statePath === "string" ? qr.statePath : undefined,
                     completedWorkers: typeof qr.completedWorkers === "number" ? qr.completedWorkers : undefined,
                     plannedWorkers: typeof qr.plannedWorkers === "number" ? qr.plannedWorkers : undefined,
                     agentConfigured: typeof qr.agentConfigured === "boolean" ? qr.agentConfigured : undefined
@@ -1218,10 +1232,11 @@ async function runCli(argv = process.argv.slice(2)) {
                 const dr = (0, capability_core_1.runDrive)(runner, driveArgs);
                 printJson(dr);
                 if (!wantsJson(args.options)) {
-                    (0, term_1.printSuccessSummary)({
+                    emitRunSummary(runner, args.options, {
                         runId: dr.runId,
                         reportPath: dr.reportPath,
                         status: dr.status,
+                        statePath: dr.statePath,
                         completedWorkers: dr.completedWorkers,
                         plannedWorkers: dr.plannedWorkers,
                         agentConfigured: dr.agentConfigured
@@ -1241,10 +1256,11 @@ async function runCli(argv = process.argv.slice(2)) {
                         const dr = (0, capability_core_1.runDrive)(runner, driveArgs);
                         printJson(dr);
                         if (!wantsJson(args.options)) {
-                            (0, term_1.printSuccessSummary)({
+                            emitRunSummary(runner, args.options, {
                                 runId: dr.runId,
                                 reportPath: dr.reportPath,
                                 status: dr.status,
+                                statePath: dr.statePath,
                                 completedWorkers: dr.completedWorkers,
                                 plannedWorkers: dr.plannedWorkers,
                                 agentConfigured: dr.agentConfigured
@@ -1556,6 +1572,37 @@ function required(value, label) {
 function optionalArg(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }
+/** Emit the calm end-of-run summary (stderr, TTY-gated inside the reporter): the COMPACT findings
+ *  table re-parsed from each completed worker's `cw:result`, the report path, where the per-worker
+ *  transcripts live, and — under `--full` — the report inline. Stderr/human-side ONLY: stdout (the
+ *  `--json` payload printed just before this) stays byte-exact. Shared by the quickstart and the
+ *  two `run --drive` paths so all three render an identical summary. */
+function emitRunSummary(runner, options, fields) {
+    // Anchor run reads to the run's OWN repo (a drive/quickstart may run cross-directory): the run
+    // dir is <repo>/.cw/runs/<id>/, holding each worker's transcript.md next to its result.md.
+    const runDir = typeof fields.statePath === "string" ? node_path_1.default.dirname(fields.statePath) : undefined;
+    const baseDir = runDir ? node_path_1.default.resolve(runDir, "..", "..", "..") : undefined;
+    const findings = (0, capability_core_1.collectRunFindings)(runner, fields.runId, baseDir);
+    // --full ALSO prints the report inline at run end (the compact table stays the default summary).
+    let fullReport;
+    if (options.full && fields.reportPath && node_fs_1.default.existsSync(fields.reportPath)) {
+        try {
+            fullReport = node_fs_1.default.readFileSync(fields.reportPath, "utf8");
+        }
+        catch { /* best-effort inline */ }
+    }
+    reporter_1.reporter.runSummary({
+        runId: fields.runId,
+        reportPath: fields.reportPath,
+        status: fields.status,
+        completedWorkers: fields.completedWorkers,
+        plannedWorkers: fields.plannedWorkers,
+        agentConfigured: fields.agentConfigured,
+        findings,
+        runDir,
+        fullReport
+    });
+}
 function printJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }

package/dist/doctor.js

@@ -174,6 +174,7 @@ function formatDoctorReport(report) {
         lines.push("  1. cw demo tamper        — prove trust checks work (30s)");
         lines.push("  2. cw demo bundle         — prove portable bundles (30s)");
         lines.push('  3. cw -q "what risks?"     — your first real report (needs an agent)');
+        lines.push('     cw quickstart research-synthesis --repo <folder> --question "..."  — cited report over a docs/papers folder, not only code');
         lines.push("");
         lines.push("Onramp");
         lines.push(`  ${report.onramp.summary}`);

package/dist/drive.js

@@ -33,6 +33,7 @@ exports.drivePreview = drivePreview;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const term_1 = require("./term");
+const reporter_1 = require("./reporter");
 const dispatch_1 = require("./dispatch");
 const execution_backend_1 = require("./execution-backend");
 const worker_isolation_1 = require("./worker-isolation");
@@ -83,7 +84,7 @@ function emitProgress(message) {
     const forcedOff = process.env.CW_DRIVE_PROGRESS === "0";
     const forcedOn = process.env.CW_DRIVE_PROGRESS === "1";
     if ((Boolean(process.stderr.isTTY) && !forcedOff) || forcedOn)
-        process.stderr.write(`[drive] ${message}\n`);
+        reporter_1.reporter.progress(`[drive] ${message}`);
 }
 /** Advance exactly ONE deterministic step. Pure-ish: all mutation is through the
  *  existing runner verbs + runBackend. */

package/dist/orchestrator/report.js

@@ -25,6 +25,11 @@ function writeReport(run) {
     (0, dispatch_1.updatePhaseStatuses)(run);
     const workerSummary = (0, worker_isolation_1.summarizeWorkers)(run);
     const candidateSummary = (0, candidate_scoring_1.summarizeCandidates)(run);
+    // A research run reads a local folder of files, not a code repo — label its source line
+    // "Source". Skip the relabel when the run ALSO carries a remote-provenance "- Source: <url>"
+    // line below (run.inputs.sourceUrl set by a --link/URL), so a report never shows two
+    // "- Source:" lines. Every other app keeps the byte-identical "Repository:" (POLA).
+    const sourceLabel = run.workflow.app?.metadata?.domain === "research" && !run.inputs.sourceUrl ? "Source" : "Repository";
     const report = [
         `# ${run.workflow.title}`,
         "",
@@ -38,7 +43,7 @@ function writeReport(run) {
             : []),
         `- Created: ${run.createdAt}`,
         `- Updated: ${run.updatedAt}`,
-        `- Repository: ${String(run.inputs.repo || run.cwd)}`,
+        `- ${sourceLabel}: ${String(run.inputs.repo || run.cwd)}`,
         // Remote provenance (v0.1.91): when the repo was materialized from a --link/URL, record
         // the sanitized origin + resolved commit so the report itself says where the code came
         // from. Conditional — absent for a local-repo run, so existing reports stay byte-identical.

package/dist/orchestrator.js

@@ -968,6 +968,9 @@ function formatHelp() {
         "  -claude                Use Claude agent",
         "  -codex                 Use Codex agent",
         "  -deepseek              Use DeepSeek (via opencode)",
+        "  --verbose              Show full agent narration live (default: compact)",
+        "  --full                 Verbose, plus the report printed inline at the end",
+        "  --no-color             Disable ANSI color (also honors NO_COLOR / FORCE_COLOR)",
         "",
         (0, term_1.bold)("More commands", out),
         ...wrapped

package/dist/reporter.js

@@ -0,0 +1,67 @@
+"use strict";
+// src/reporter.ts — the cw-side run reporter.
+//
+// Rendering lives behind a small interface so the drive/command-surface stay logic-only: the
+// orchestrator emits events (progress lines, the end-of-run summary) and the Reporter decides how
+// to draw them. The live AGENT view (spinner / streamed tokens / folding tool lines) is rendered
+// by the async agent wrapper — cw is blocked in spawnSync during a run, so cw only renders the
+// calm orchestration BETWEEN agents plus the final summary. Everything here goes to STDERR; the
+// MACHINE payloads on stdout (the cw:result fence + cw's --json via printJson) carry NO term
+// styling, so they stay byte-exact under any color env. Color is TTY-gated and honors
+// NO_COLOR/CW_NO_COLOR(--no-color)/FORCE_COLOR via term — FORCE_COLOR may color human-readable
+// output (its purpose) but never the machine payloads, which use no styling at all.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reporter = void 0;
+exports.createReporter = createReporter;
+const term_1 = require("./term");
+function isTTY(stream) {
+    return Boolean(stream.isTTY);
+}
+class StderrReporter {
+    s;
+    constructor(s) {
+        this.s = s;
+    }
+    progress(line) {
+        // The caller already decided WHETHER to emit (drive's CW_DRIVE_PROGRESS/TTY gate) and has
+        // already styled the line (phaseProgressLine etc.) — the reporter just centralizes the write
+        // so all orchestration output flows through one interface. No extra styling (avoids ANSI nesting).
+        this.s.write(`${line}\n`);
+    }
+    runSummary(f) {
+        if (!isTTY(this.s))
+            return; // summary is human chrome; piped/--json stdout already carries the data
+        const s = this.s;
+        const counts = (typeof f.completedWorkers === "number" && typeof f.plannedWorkers === "number")
+            ? ` — ${f.completedWorkers}/${f.plannedWorkers}` : "";
+        s.write("\n");
+        if (f.findings && f.findings.length)
+            s.write(`${(0, term_1.formatFindingsSummary)(f.findings, s)}\n\n`);
+        s.write(`${(0, term_1.green)("✓", s)} Report: ${f.reportPath}\n`);
+        if (f.status === "complete") {
+            s.write(`  ${(0, term_1.green)("✓", s)} Status: complete${counts}\n`);
+            if (f.runDir)
+                s.write(`  ${(0, term_1.dim)(`Transcript: ${f.runDir}`, s)}\n`);
+            s.write(`  ${(0, term_1.nextHint)(`cw report ${f.runId} --show`, s)}\n`);
+        }
+        else {
+            s.write(`  ${(0, term_1.yellow)("!", s)} Status: ${f.status}${counts}\n`);
+            if (f.agentConfigured === false)
+                s.write(`  ${(0, term_1.tryHint)("cw doctor", s)}\n`);
+            else
+                s.write(`  ${(0, term_1.nextHint)(`cw status ${f.runId}`, s)}\n`);
+        }
+        if (typeof f.fullReport === "string" && f.fullReport.trim()) {
+            s.write(`\n${(0, term_1.dim)("──── full report ────", s)}\n${f.fullReport.trim()}\n`);
+        }
+    }
+}
+/** Build a reporter over an explicit stream. Used by the default singleton and by tests, which
+ *  drive a fake `{ isTTY, write }` stream to assert the TTY path renders (findings table + report
+ *  path + hints) and the non-TTY path stays silent. */
+function createReporter(stream) {
+    return new StderrReporter(stream);
+}
+/** The default reporter writes the orchestration view to stderr. (A future non-TTY-specific
+ *  reporter could differ; today the single impl gates internally on isTTY, matching emitProgress.) */
+exports.reporter = createReporter(process.stderr);

package/dist/term.js

@@ -22,9 +22,23 @@ exports.sectionHeader = sectionHeader;
 exports.phaseProgressLine = phaseProgressLine;
 exports.formatDuration = formatDuration;
 exports.printSuccessSummary = printSuccessSummary;
+exports.stripAnsi = stripAnsi;
+exports.visibleWidth = visibleWidth;
+exports.truncate = truncate;
+exports.formatFindingsSummary = formatFindingsSummary;
 function isTTY(stream = process.stderr) {
     return Boolean(stream.isTTY);
 }
+/** Whether to emit ANSI color on a stream, honoring the de-facto env standards:
+ *  NO_COLOR / CW_NO_COLOR (any non-empty value) disable; FORCE_COLOR (non-"0") forces on
+ *  even when piped; otherwise fall back to isTTY. The `--no-color` flag sets CW_NO_COLOR. */
+function colorEnabled(stream, env = process.env) {
+    if ((env.NO_COLOR ?? "") !== "" || (env.CW_NO_COLOR ?? "") !== "")
+        return false;
+    if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "" && env.FORCE_COLOR !== "0")
+        return true;
+    return isTTY(stream);
+}
 // ---- ansi codes ----
 const ansi = {
     reset: "\x1b[0m",
@@ -37,7 +51,7 @@ const ansi = {
 };
 // ---- styled text ----
 function style(code, text, stream) {
-    if (!isTTY(stream))
+    if (!colorEnabled(stream))
         return text;
     return `${code}${text}${ansi.reset}`;
 }
@@ -137,3 +151,61 @@ function printSuccessSummary(fields, stream) {
             s.write(`  ${nextHint(`cw status ${fields.runId}`, s)}\n`);
     }
 }
+// ---- width-aware truncation (zero-dep) ----
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+/** Strip ANSI SGR codes (for measuring visible width). */
+function stripAnsi(text) {
+    return text.replace(ANSI_RE, "");
+}
+/** Visible width of a string, ignoring ANSI. Counts each code point as width 1 — a known
+ *  minor caveat for wide (CJK/emoji) glyphs, acceptable for one-line status truncation. */
+function visibleWidth(text) {
+    return [...stripAnsi(text)].length;
+}
+/** Truncate a (possibly styled) string to `maxWidth` visible columns, appending `…` when cut.
+ *  Operates on the PLAIN text (callers truncate before styling), so no ANSI is split. */
+function truncate(text, maxWidth) {
+    if (maxWidth <= 0)
+        return "";
+    const chars = [...stripAnsi(text)];
+    if (chars.length <= maxWidth)
+        return text;
+    if (maxWidth === 1)
+        return "…";
+    return `${chars.slice(0, maxWidth - 1).join("")}…`;
+}
+// ---- findings summary table (end-of-run, compact) ----
+/** Severity order for sorting + counting (most severe first). */
+const SEVERITY_ORDER = ["P0", "P1", "P2", "P3", "none"];
+/** Render a compact findings summary assembled from the run's `cw:result` blocks: a one-line
+ *  count headline (e.g. `Findings: 3 — 2×P1, 1×P2`) plus a small id/severity/class table. This
+ *  is the end-of-run summary — NOT the full prose (that stays in report.md + the transcript).
+ *  Returns "" when there are no findings (caller prints nothing). */
+function formatFindingsSummary(findings, stream) {
+    if (!findings.length)
+        return "";
+    const bySev = new Map();
+    for (const f of findings)
+        bySev.set(f.severity || "none", (bySev.get(f.severity || "none") || 0) + 1);
+    const order = (s) => {
+        const i = SEVERITY_ORDER.indexOf(s);
+        return i === -1 ? SEVERITY_ORDER.length : i;
+    };
+    const counts = [...bySev.entries()]
+        .sort((a, b) => order(a[0]) - order(b[0]))
+        .map(([sev, n]) => `${n}×${sev}`)
+        .join(", ");
+    const rows = [...findings].sort((a, b) => order(a.severity) - order(b.severity));
+    const sevW = Math.max(8, ...rows.map((r) => (r.severity || "none").length));
+    const clsW = Math.max(5, ...rows.map((r) => (r.classification || "unknown").length));
+    const lines = [
+        `${bold("Findings:", stream)} ${findings.length} — ${counts}`,
+        dim(`  ${"SEVERITY".padEnd(sevW)}  ${"CLASS".padEnd(clsW)}  ID`, stream)
+    ];
+    for (const r of rows) {
+        const sev = (r.severity || "none").padEnd(sevW);
+        const cls = (r.classification || "unknown").padEnd(clsW);
+        lines.push(`  ${sev}  ${cls}  ${truncate(r.id || "(unnamed)", 60)}`);
+    }
+    return lines.join("\n");
+}

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.90";
+exports.CURRENT_COOL_WORKFLOW_VERSION = "0.1.92";
 exports.WORKFLOW_APP_SCHEMA_VERSION = 1;
 exports.CURRENT_RUN_STATE_SCHEMA_VERSION = 1;
 exports.LEGACY_RUN_STATE_SCHEMA_VERSION = 0;

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

@@ -198,28 +198,43 @@ string). Each verb is declared once in `capability-registry.ts`, so `cw <cmd>
 --json` is byte-identical to the matching `cw_<tool>` MCP tool for the read-only
 preview/config-show verbs.
 
-## Live output — opt-in stderr passthrough (Unix-clean)
-
-A drive can show the agent's activity live, without touching the evidence
-contract, when the operator opts in with `CW_AGENT_STREAM=1`:
-
-- **Default stays buffered.** Without `CW_AGENT_STREAM=1`, the bundled wrapper
-  keeps the buffered path and writes one JSON report to stdout after writing
-  `result.md`.
-- **The opt-in wrapper renders; stderr only.** With `CW_AGENT_STREAM=1`, the
-  bundled Claude wrapper runs claude in `--output-format stream-json`, and the
-  bundled Codex wrapper runs `codex exec --json --output-last-message`.
-  Each wrapper renders a short human trace (tool uses, assistant text, per-turn
-  summaries where present) to its **stderr** — diagnostics, never data. It builds
-  the single `{model, usage, result}` object for stdout after the final answer is
-  captured.
-- **Core forwards, never parses.** `runAgentProcess` passes the agent child's
-  stderr straight through to the operator's terminal (`stdio` inherit) only when
-  `CW_AGENT_STREAM=1`, CW's own stderr is a TTY, and `CW_NO_STREAM` is not set.
-  Piped / CI runs stay quiet (the Rule of Silence). Vendor-specific rendering
-  lives in the wrapper (policy), not the kernel (mechanism).
-- **Determinism intact.** The backend evidence triple hashes stdout only, so
-  the live stderr stream never changes recorded evidence or replay.
+## Live output — a calm live view, on stderr, Unix-clean
+
+A drive shows the agent's activity live without ever touching the evidence
+contract. The async per-vendor wrapper owns the live region (it parses
+`--output-format stream-json` and its event loop is free); cw renders the calm
+orchestration between agents plus the end-of-run summary. **Everything goes to
+stderr — stdout stays the byte-exact data channel** (the `cw:result` fence, the
+wrapper's `{model, usage, result}` JSON, cw's `--json` payload), so a pipe is
+never polluted.
+
+- **Interactive (TTY).** The wrapper renders ONE in-place status line: a Braille
+  spinner + the current action + elapsed (e.g. `⠹ Read app.js 1.2s`). Tool calls
+  fold to a single line each — spinning while running, then resolving to
+  `✓ Read app.js (0.3s)` / `✗ Bash (1.1s)` (dimmed, args width-truncated). The
+  cursor is hidden while the spinner runs and **ALWAYS restored** on exit /
+  Ctrl-C / SIGTERM (Ctrl-C exits non-zero, leaving a clean terminal).
+- **Non-TTY stays SILENT by default** (the Rule of Silence). `CW_AGENT_STREAM=1`
+  opts a CI/piped run into a **plain append-only** trace (`→ …` / `✓ … (Xs)`
+  lines, zero ANSI/cursor bytes) for debuggability — mirroring `CW_DRIVE_PROGRESS=1`.
+- **Verbosity.** Default is compact: the current action + folded tool lines, with
+  the model's narration/reasoning HIDDEN. `--verbose` (sets `CW_VERBOSE=1`)
+  surfaces the full narration inline; `--full` (sets `CW_OUTPUT=full`) implies
+  verbose AND prints the report inline at run end.
+- **Transcript always on disk.** Regardless of verbosity — even when the screen
+  view is silent or compact — the wrapper writes the COMPLETE narration + tool I/O
+  to `transcript.md` next to that worker's `result.md`. The end-of-run summary
+  prints the run dir where the transcripts live, so nothing is ever lost to a
+  compact view.
+- **Color control.** `NO_COLOR` / `CW_NO_COLOR` (the `--no-color` flag sets the
+  latter) disable ANSI; `FORCE_COLOR` forces it even when piped; otherwise color
+  follows isTTY. Honored identically by cw (`term.ts`) and every wrapper.
+- **End-of-run summary (cw side).** A COMPACT findings table — id / severity /
+  classification + counts, re-parsed from each completed worker's `cw:result` —
+  plus the report path, status, and run dir. NOT the full prose (that stays in
+  `report.md` + the transcript); `--full` also prints the report inline.
+- **Determinism intact.** The backend evidence triple hashes stdout only, so the
+  live stderr view never changes recorded evidence or replay.
 
 The built-in templates are:
 
@@ -319,3 +334,7 @@ Orchestration-parity for the agent drive: `run --drive --incremental` step-level
 The one-command `cw -q` headline now routes the question and defaults the repo to the caller cwd before driving the agent; the delegation contract, drive, and accept path are unchanged.
 
 0.1.90
+
+0.1.91
+
+0.1.92

package/docs/canonical-workflow-apps.7.md

@@ -98,6 +98,11 @@ node scripts/cw.js plan release-cut \
 Break a research question into claims, look into sources, cross-check
 the evidence, check the claims, and put together a short answer.
 
+When you point it at a folder, it reads the local files there as primary
+sources. So this app works over any corpus — your own docs, notes, or
+papers — not only a git code repo. The working directory is the corpus,
+so the agent can back its answer with your own files.
+
 ```bash
 node scripts/cw.js plan research-synthesis \
   --cwd /tmp/research-run \
@@ -107,6 +112,13 @@ node scripts/cw.js plan research-synthesis \
   --freshness "as of today"
 ```
 
+Over a local corpus folder, point `--repo` at it:
+
+```bash
+cw quickstart research-synthesis --repo /path/to/papers \
+  --question "What do these papers conclude?"
+```
+
 ## Validation Matrix
 
 Run the canonical app matrix from the plugin root directory:

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

@@ -526,3 +526,7 @@ CLI surface simplified to 6 commands with agent stderr streaming on by default a
 CLI golden-path fixes: `cw -q "…"` routes the question (was read as an app id → "Workflow app not found"), auto-detects the cwd as the repo (run anywhere, no `--repo`), and `cw help` wraps its command list with a trailing newline; the CLI↔MCP parity contract and the help-token parser are unchanged.
 
 0.1.90
+
+0.1.91
+
+0.1.92

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

@@ -159,3 +159,7 @@ _No behavioral change in v0.1.88 (no schema-migration edge was added; the increm
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
 
 0.1.90
+
+0.1.91
+
+0.1.92

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

@@ -143,3 +143,7 @@ _No behavioral change in v0.1.88 (the `sched` priority/readiness selection, conc
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
 
 0.1.90
+
+0.1.91
+
+0.1.92

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

@@ -142,3 +142,7 @@ _No behavioral change in v0.1.88 (atomic writes, fsync-durability for audit-esse
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
 
 0.1.90
+
+0.1.91
+
+0.1.92

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

@@ -303,3 +303,7 @@ _No behavioral change in v0.1.88 (the evidence adoption reasoning chain and its
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
 
 0.1.90
+
+0.1.91
+
+0.1.92

package/docs/execution-backends.7.md

@@ -333,3 +333,7 @@ Agent stderr live-streaming is now on by default when stderr is a TTY (CW_AGENT_
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
 
 0.1.90
+
+0.1.91
+
+0.1.92

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

@@ -301,3 +301,7 @@ The host-facing surface tracks the CLI simplification to 6 commands (streaming o
 The host-facing surface tracks the CLI golden-path fixes (`cw -q` routing + repo auto-detect + clean help); the multi-agent verbs and their MCP-tool mirrors are unchanged.
 
 0.1.90
+
+0.1.91
+
+0.1.92

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

@@ -335,3 +335,7 @@ _No change in behavior in v0.1.88 (no harness code changed; the new `loop-contro
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
 
 0.1.90
+
+0.1.91
+
+0.1.92

package/docs/multi-agent-operator-ux.7.md

@@ -347,3 +347,7 @@ _No behavioral change in v0.1.88 (no operator-view code changed; the new sub-wor
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
 
 0.1.90
+
+0.1.91
+
+0.1.92

package/docs/node-snapshot-diff-replay.7.md

@@ -168,3 +168,7 @@ A new `loop-control` StateNodeKind now flows through per-node snapshot/diff/repl
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
 
 0.1.90
+
+0.1.91
+
+0.1.92

package/docs/observability-cost-accounting.7.md

@@ -227,3 +227,7 @@ Attestation now signs the agent's RESULT, not just its usage: `TelemetryAttestat
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
 
 0.1.90
+
+0.1.91
+
+0.1.92