copperhead 0.7.0 → 0.8.0

package/src/agent/providers/tool-protocol.ts

@@ -0,0 +1,212 @@
+import type { Msg, ToolCall, ToolSchema } from '../types.js';
+
+export function renderToolProtocol(tools: ToolSchema[]): string {
+  if (!tools.length) return '';
+  const lines = [
+    '# Tool protocol',
+    '',
+    'You are the reasoning half of a tool-driven workflow; you cannot run anything yourself.',
+    'To take an action, reply with EXACTLY ONE JSON object and nothing else, wrapped in a',
+    '```json fenced code block:',
+    '',
+    '```json',
+    '{"tool": "<tool_name>", "args": { ... }}',
+    '```',
+    '',
+    'Use only the tools listed below, with `args` matching the tool\'s JSON Schema. If you have',
+    'no tool to call and only want to say something, reply with plain prose and no JSON block.',
+    '',
+    '## Available tools',
+  ];
+  for (const t of tools) {
+    lines.push(
+      '',
+      `### ${t.name}`,
+      t.description,
+      `Parameters (JSON Schema): ${JSON.stringify(t.parameters)}`,
+    );
+  }
+  return lines.join('\n');
+}
+
+/** Delta prompt for a resumed CLI session: new user lines and tool results only. */
+export function renderDelta(messages: Msg[], from: number): string {
+  const idToName = new Map<string, string>();
+  for (const m of messages) {
+    if (m.role === 'assistant') for (const call of m.toolCalls ?? []) idToName.set(call.id, call.name);
+  }
+  const parts: string[] = [];
+  for (const m of messages.slice(Math.max(0, from))) {
+    if (m.role === 'user') {
+      parts.push(`[user]\n${m.content}`);
+    } else if (m.role === 'tool') {
+      const name = idToName.get(m.toolCallId) ?? m.toolCallId;
+      parts.push(`[result of ${name}]\n${m.content}`);
+    }
+  }
+  return parts.join('\n\n');
+}
+
+export function renderConversation(messages: Msg[]): string {
+  const idToName = new Map<string, string>();
+  const parts: string[] = [];
+  for (const m of messages) {
+    if (m.role === 'system') continue;
+    if (m.role === 'user') {
+      parts.push(`[user]\n${m.content}`);
+    } else if (m.role === 'assistant') {
+      if (m.content) parts.push(`[assistant]\n${m.content}`);
+      for (const call of m.toolCalls ?? []) {
+        idToName.set(call.id, call.name);
+        parts.push(
+          `[assistant tool call]\n\`\`\`json\n${JSON.stringify({ tool: call.name, args: call.args })}\n\`\`\``,
+        );
+      }
+    } else {
+      const name = idToName.get(m.toolCallId) ?? m.toolCallId;
+      parts.push(`[result of ${name}]\n${m.content}`);
+    }
+  }
+  return parts.join('\n\n');
+}
+
+export interface ParsedToolTurn {
+  text: string | null;
+  toolCalls: ToolCall[];
+  nudge?: string;
+}
+
+/**
+ * Detect a malformed-but-intended tool call in a turn that dispatched none
+ * (#I10). The signature is machine-recognizable: the text contains
+ * `"tool":"<name>"` naming a tool in the current catalog, yet nothing parsed.
+ * That is the exact case where the tolerant extractor's silence misleads the
+ * model — the JSON was near-miss malformed (a brace short, or the outer object
+ * split so only an inner `{args}` with no `tool` key balanced), not the tool
+ * being broken. Returns a one-line steer to re-emit it, or undefined when the
+ * absence of a call is genuine (plain prose, no tool named).
+ */
+function detectMalformedCall(text: string, catalog: Set<string>): string | undefined {
+  const re = /"tool"\s*:\s*"([^"]+)"/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text)) !== null) {
+    const name = m[1]!;
+    if (catalog.has(name)) {
+      return (
+        `A tool call for "${name}" looks malformed — it named the tool but did not parse as ` +
+        'valid JSON (likely unbalanced braces or a missing closing brace), so no call ran. ' +
+        'Re-emit it as exactly one complete JSON object: {"tool": "...", "args": { ... }}.'
+      );
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Extract tool-call JSON from the model's reply. Tolerant by design (D1):
+ * unparseable output is returned as plain text with no tool calls rather than
+ * throwing, so a non-conforming turn degrades to the loop's stall/nudge path.
+ * A parsed block only counts as a tool call when its name is in the current
+ * turn's catalog (`availableTools(ctx)`): a hallucinated or locked tool name is
+ * left as prose so the loop nudges, rather than dispatching a bogus call.
+ */
+export function parseToolCalls(
+  text: string | null,
+  nextId: () => string,
+  catalog: Set<string>,
+): ParsedToolTurn {
+  if (!text) return { text: null, toolCalls: [] };
+  const toolCalls: ToolCall[] = [];
+  const matched: Array<[number, number]> = [];
+
+  // Extract tool calls by scanning for complete JSON objects, NOT by matching
+  // ``` fences. A tool call's `content`/`args` can hold a full markdown doc that
+  // itself contains ``` code fences; a fence regex truncates the JSON at the
+  // first inner fence, JSON.parse fails, and the call is silently dropped (the
+  // model then assumes it wrote a file it never did). The brace scan is
+  // string-aware, so braces and backticks inside JSON string values are ignored.
+  let searchFrom = 0;
+  while (searchFrom < text.length) {
+    const braceAt = text.indexOf('{', searchFrom);
+    if (braceAt < 0) break;
+    const span = scanJsonObject(text, braceAt);
+    if (!span) {
+      // Unbalanced '{' (stray brace in prose): retry from the next candidate so
+      // one bad brace can't hide a well-formed call later in the reply.
+      searchFrom = braceAt + 1;
+      continue;
+    }
+    const call = toToolCall(text.slice(span.start, span.end), nextId, catalog);
+    if (call) {
+      toolCalls.push(call);
+      matched.push([span.start, span.end]);
+    }
+    searchFrom = span.end;
+  }
+
+  if (!toolCalls.length) {
+    // No call dispatched — but did the model clearly *intend* one? A fenced
+    // ```json block that names a catalog tool yet produced zero calls is a
+    // malformed near-miss (unbalanced braces, a missing `}`, or an inner object
+    // with no `tool` key). Silently dropping it gives the model no signal, so it
+    // misreads "no result" as "this tool is broken" and can bake that false
+    // conclusion into a committed summary (#I10). Surface a nudge instead.
+    return { text: text.trim() ? text : null, toolCalls, nudge: detectMalformedCall(text, catalog) };
+  }
+
+  // Prose is whatever survives once the tool-call objects (and any now-empty
+  // ```json fences around them) are removed.
+  let prose = '';
+  let cursor = 0;
+  for (const [start, end] of matched) {
+    prose += text.slice(cursor, start);
+    cursor = end;
+  }
+  prose += text.slice(cursor);
+  prose = prose.replace(/```(?:json)?\s*```/gi, '').replace(/```(?:json)?\s*$/gi, '').trim();
+  return { text: prose.length ? prose : null, toolCalls };
+}
+
+/**
+ * Find the first complete, brace-balanced JSON object at or after `from`,
+ * respecting JSON string quoting/escaping so braces or backticks inside string
+ * values do not end the scan. Returns its `[start, end)` bounds or null.
+ */
+function scanJsonObject(text: string, from: number): { start: number; end: number } | null {
+  const start = text.indexOf('{', from);
+  if (start < 0) return null;
+  let depth = 0;
+  let inStr = false;
+  let esc = false;
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i];
+    if (inStr) {
+      if (esc) esc = false;
+      else if (ch === '\\') esc = true;
+      else if (ch === '"') inStr = false;
+      continue;
+    }
+    if (ch === '"') inStr = true;
+    else if (ch === '{') depth++;
+    else if (ch === '}' && --depth === 0) return { start, end: i + 1 };
+  }
+  return null;
+}
+
+function toToolCall(raw: string | undefined, nextId: () => string, catalog: Set<string>): ToolCall | null {
+  if (!raw) return null;
+  let obj: unknown;
+  try {
+    obj = JSON.parse(raw.trim());
+  } catch {
+    return null;
+  }
+  if (!obj || typeof obj !== 'object') return null;
+  const rec = obj as Record<string, unknown>;
+  if (typeof rec.tool !== 'string') return null;
+  // Only accept names the turn actually advertised. An empty catalog means the
+  // turn offered no tools, so nothing parses as a call.
+  if (!catalog.has(rec.tool)) return null;
+  const args = rec.args && typeof rec.args === 'object' ? (rec.args as Record<string, unknown>) : {};
+  return { id: nextId(), name: rec.tool, args };
+}

package/src/agent/render.ts

@@ -3,8 +3,13 @@
  * once at startup: interactive (TTY, no --json/--plain) pins a status line to
  * the bottom of the terminal and redraws it in place; plain emits line-oriented
  * output with zero ANSI escapes — the mode CI, pipes, and tests see.
+ *
+ * Interactive mode adds subtle SGR chrome (copper accent, dim secondary text).
+ * Plain mode never emits color (AC-8.9).
  */
 
+import { copper, dim, setColorEnabled, styleOutcome, toolLine, warn } from './theme.js';
+
 export interface ProgressRenderer {
   log(line: string): void;
   /** Called at the start of each turn with cumulative token totals so far. */
@@ -106,20 +111,29 @@ export class InteractiveRenderer implements ProgressRenderer {
   }
 
   private statusText(): string {
-    const parts = [
-      `turn ${this.turn}/${this.maxTurns}`,
-      `${fmtTokens(this.tokensIn)} in / ${fmtTokens(this.tokensOut)} out`,
-      fmtDuration(Date.now() - this.startMs),
-    ];
-    if (this.busy) {
-      // Fold streamed-output volume into the busy segment so a large turn's
-      // status line visibly grows — a hung one stays frozen (5.1).
-      parts.push(this.streamedChars ? `${this.busy} ~${fmtTokens(this.streamedChars)} ch` : this.busy);
-    }
-    const spinner = this.busy ? FRAMES[this.frame % FRAMES.length] : '·';
-    const line = `${spinner} ${parts.join(' · ')}`;
+    // Raw (uncolored) segments once; both the colored line and the
+    // narrow-terminal fallback are assembled from these.
+    const spinner = this.busy ? FRAMES[this.frame % FRAMES.length]! : '·';
+    const turn = `turn ${this.turn}/${this.maxTurns}`;
+    const tokens = `${fmtTokens(this.tokensIn)} in / ${fmtTokens(this.tokensOut)} out`;
+    const elapsed = fmtDuration(Date.now() - this.startMs);
+    // Fold streamed-output volume into the busy segment so a large turn's
+    // status line visibly grows — a hung one stays frozen (5.1).
+    const busy = this.busy
+      ? this.streamedChars
+        ? `${this.busy} ~${fmtTokens(this.streamedChars)} ch`
+        : this.busy
+      : undefined;
+    const parts = [turn, dim(tokens), dim(elapsed), ...(busy ? [warn(busy)] : [])];
+    const line = `${this.busy ? copper(spinner) : dim(spinner)} ${parts.join(dim(' · '))}`;
+    // Truncate by visible length roughly: strip SGR when measuring so color
+    // codes don't eat the column budget and clip the readable text early.
     const width = this.out.columns ?? 80;
-    return line.length > width ? line.slice(0, width - 1) : line;
+    const visible = line.replace(/\x1b\[[0-9;]*m/g, '');
+    if (visible.length <= width) return line;
+    // Fall back to an uncolored truncated line when the terminal is too narrow.
+    const plain = [spinner, turn, tokens, elapsed, ...(busy ? [busy] : [])].join(' · ');
+    return plain.length > width ? plain.slice(0, width - 1) : plain;
   }
 
   private redraw(): void {
@@ -162,7 +176,7 @@ export class InteractiveRenderer implements ProgressRenderer {
   }
 
   toolResult(name: string, firstLine: string): void {
-    this.log(`  [${name}] ${firstLine}`);
+    this.log(toolLine(name, firstLine));
   }
 
   status(text: string | null): void {
@@ -181,7 +195,7 @@ export class InteractiveRenderer implements ProgressRenderer {
 
   finish(line: string): void {
     if (this.statusShown) this.out.write(CLEAR_LINE);
-    this.out.write(line + '\n');
+    this.out.write(styleOutcome(line) + '\n');
     this.suspend();
   }
 
@@ -215,7 +229,10 @@ export class InteractiveRenderer implements ProgressRenderer {
  * (AC-2.4): the only thing a --json invocation writes to stdout is its JSON.
  */
 export function makeRenderer(opts: { json: boolean; plain: boolean }): ProgressRenderer {
+  const interactive = !opts.json && !opts.plain && Boolean(process.stdout.isTTY);
+  // Color tracks the interactive path so --plain / pipes stay zero-ANSI (AC-8.9).
+  setColorEnabled(interactive && !process.env.NO_COLOR);
   if (opts.json) return plainRenderer((line) => console.error(line));
-  if (!opts.plain && process.stdout.isTTY) return new InteractiveRenderer();
+  if (interactive) return new InteractiveRenderer();
   return plainRenderer((line) => console.log(line));
 }

package/src/agent/runmeta.ts

@@ -9,7 +9,7 @@ import type { CopperheadConfig, ModelSource } from '../config.js';
 
 /** Caller-supplied run identity: facts the loop cannot probe for itself. */
 export interface RunMetaInput {
-  command?: 'do' | 'create' | 'sync';
+  command?: 'do' | 'create' | 'sync' | 'repl';
   modelSource?: ModelSource;
   version?: string;
   kicadCliVersion?: string;
@@ -29,7 +29,7 @@ export interface RunMeta {
   modelSource: ModelSource | null;
   runId: string;
   startedAt: string;
-  command: 'do' | 'create' | 'sync' | null;
+  command: 'do' | 'create' | 'sync' | 'repl' | null;
   interactive: boolean;
   stage: { name: string; index: number; total: number } | null;
   brief: { path: string; sha256: string } | null;
@@ -150,14 +150,14 @@ export async function collectRunMeta(opts: CollectRunMetaOptions): Promise<RunMe
 
 const unk = (v: string | null | undefined): string => v ?? 'unknown';
 
-/** ≤ 2 lines, printed before the first turn (AC-8.4). */
+/** ≤ 2 lines, printed before the first turn (AC-8.4).
+ *  Live header stays compact: install path / platform live in summary.md only. */
 export function renderCliHeader(meta: RunMeta): string[] {
   const v = meta.versions;
   const line1 = [
-    `copperhead v${unk(v.copperhead)}${v.installPath ? ` (${v.installPath})` : ''}`,
+    `copperhead v${unk(v.copperhead)}`,
     `kicad-cli ${unk(v.kicadCli)}`,
     `node ${v.node}`,
-    v.platform,
   ].join(' · ');
 
   const repoState =
@@ -167,12 +167,11 @@ export function renderCliHeader(meta: RunMeta): string[] {
         ? `dirty(${meta.git.uncommittedFiles})`
         : 'clean';
   const line2 = [
-    `run ${meta.runId}`,
     unk(meta.command),
     ...(meta.stage ? [`stage ${meta.stage.name} (${meta.stage.index}/${meta.stage.total})`] : []),
     `model ${meta.model} (${meta.provider}, via ${unk(meta.modelSource)})`,
     `turns ≤${meta.config.maxTurns}`,
-    `repo ${unk(meta.git.branch)}@${meta.git.commit?.slice(0, 7) ?? 'unknown'} ${repoState}`,
+    `${unk(meta.git.branch)}@${meta.git.commit?.slice(0, 7) ?? 'unknown'} ${repoState}`,
   ].join(' · ');
   return [line1, line2];
 }

package/src/agent/theme.ts

@@ -0,0 +1,91 @@
+/**
+ * Subtle interactive-TTY chrome: muted hierarchy with a copper accent.
+ * Plain / --json / piped output must stay free of SGR (AC-8.9), so helpers
+ * no-op unless color has been explicitly enabled for this process.
+ */
+
+const ESC = '\x1b[';
+const RESET = `${ESC}0m`;
+
+/** True after makeRenderer selects the interactive path. */
+let colorEnabled = false;
+
+export function setColorEnabled(on: boolean): void {
+  colorEnabled = on;
+}
+
+export function isColorEnabled(): boolean {
+  return colorEnabled;
+}
+
+function paint(code: string, s: string): string {
+  if (!colorEnabled || s === '') return s;
+  return `${ESC}${code}m${s}${RESET}`;
+}
+
+const TRUECOLOR = /truecolor|24bit/i.test(process.env.COLORTERM ?? '');
+
+/** Secondary metadata — soft gray #999999 (truecolor), SGR 90 fallback. */
+export const dim = (s: string): string => paint(TRUECOLOR ? '38;2;153;153;153' : '90', s);
+/** Rules/separators — one step darker than dim: #888888. */
+export const ruleDim = (s: string): string => paint(TRUECOLOR ? '38;2;136;136;136' : '90', s);
+/** Primary content — bright white (typed input, key values). */
+export const bright = (s: string): string => paint('97', s);
+
+/** Exact brand copper #b87333 where truecolor is available; warm 256 fallback. */
+const COPPER_SGR = TRUECOLOR ? '38;2;184;115;51' : '38;5;173';
+/** Light copper tint (brand accent-high #eec9a5) — menu hover. */
+export const copperLight = (s: string): string =>
+  paint(TRUECOLOR ? '38;2;238;201;165' : '38;5;223', s);
+/** Title emphasis — bold in the terminal's default foreground (theme-adaptive). */
+export const bold = (s: string): string => paint('1', s);
+/** Brand / active accent — exact copper #b87333 (truecolor), 256-color 173 fallback. */
+export const copper = (s: string): string => paint(COPPER_SGR, s);
+/** Success — PCB green. */
+export const ok = (s: string): string => paint('32', s);
+/** Busy / caution — amber. */
+export const warn = (s: string): string => paint('33', s);
+/** Failure. */
+export const err = (s: string): string => paint('31', s);
+
+/**
+ * Style a create-pipeline stage line. Keeps the `stage <name>:` prefix so
+ * existing log greps and operator muscle memory still work.
+ */
+export function stageLine(name: string, detail: string, kind: 'info' | 'ok' | 'warn' | 'err' = 'info'): string {
+  const label = dim(`stage ${name}:`);
+  const body =
+    kind === 'ok' ? ok(detail) : kind === 'warn' ? warn(detail) : kind === 'err' ? err(detail) : detail;
+  return `${label} ${body}`;
+}
+
+/** Tool-result scrollback line: short glyph + name + first line of result. */
+export function toolLine(name: string, firstLine: string): string {
+  const clean = /\b(clean|ok|pass(?:ed)?|success|done)\b/i.test(firstLine) && !/\b(fail|error|violat)/i.test(firstLine);
+  const glyph = clean ? ok('✓') : copper('▸');
+  return `  ${glyph} ${dim(name)}  ${firstLine}`;
+}
+
+/** Color the final outcome line from its exit-path token. */
+export function styleOutcome(line: string): string {
+  if (!colorEnabled) return line;
+  const head = line.split(' · ')[0] ?? line;
+  const rest = line.slice(head.length);
+  if (head === 'done') return ok(head) + dim(rest);
+  if (/refus|fail|error|exhaust|stall/i.test(head)) return err(head) + dim(rest);
+  return copper(head) + dim(rest);
+}
+
+/** Dim secondary segments of the two-line CLI header (brand stays copper). */
+export function styleHeaderLines(lines: string[]): string[] {
+  if (!colorEnabled) return lines;
+  return lines.map((line, i) => {
+    if (i === 0) {
+      // copperhead vX · rest…
+      const m = line.match(/^(copperhead v\S+)(.*)$/);
+      if (!m) return dim(line);
+      return copper(m[1]!) + dim(m[2]!);
+    }
+    return dim(line);
+  });
+}

package/src/cli.ts

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-import path from 'node:path';
 import { createRequire } from 'node:module';
 import { createInterface } from 'node:readline/promises';
-import { loadConfig, resolveModel } from './config.js';
+import { loadConfig, resolveModel, type ModelSource } from './config.js';
+import { pickModel } from './util/select.js';
 import { runInit, InitError } from './memory/scaffold.js';
 import { runCheck } from './commands/check.js';
+import { runDoctor, formatDoctor } from './commands/doctor.js';
 import { syncVerify, syncResolve, formatSyncReport } from './commands/sync.js';
 import { runCreate } from './commands/create.js';
+import { runDemo, demoTourText } from './commands/demo.js';
+import { runRepl } from './commands/repl.js';
 import {
   runExportBom,
   parseSupplier,
@@ -20,6 +23,7 @@ import { runAgentLoop, type BudgetExhaustedStats } from './agent/loop.js';
 import { makeRenderer } from './agent/render.js';
 import { kicadCliVersion } from './kicad/cli.js';
 import { loadEnvFile } from './util/env.js';
+import { budgetExtraTurns, budgetPromptText, parseMaxTurns, repoOf } from './util/cli-args.js';
 
 // Read .env from the working directory before any command resolves a model or a
 // provider. Loaded here rather than per-command so `check` behaves identically,
@@ -35,8 +39,6 @@ const { version } = createRequire(import.meta.url)('../package.json') as { versi
 
 const program = new Command();
 
-const repoOf = (opts: { repo?: string }): string => path.resolve(opts.repo ?? process.cwd());
-
 async function confirmTty(question: string): Promise<boolean> {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   const answer = await rl.question(`${question} [y/N] `);
@@ -50,14 +52,8 @@ async function confirmTty(question: string): Promise<boolean> {
  */
 function budgetContinuePrompt(): ((stats: BudgetExhaustedStats) => Promise<number>) | undefined {
   if (!process.stdin.isTTY || !process.stdout.isTTY) return undefined;
-  return async (stats) => {
-    // ceil of the ORIGINAL budget (design D1), so repeat extensions offer the
-    // same increment instead of escalating with the extended turn count.
-    const extra = Math.ceil(stats.maxTurns / 2);
-    const k = (n: number) => `${(n / 1000).toFixed(1)}k`;
-    const q = `Turn budget exhausted (${stats.turnsUsed} turns, ${k(stats.tokensIn)} in / ${k(stats.tokensOut)} out, ${stats.filesTouched.length} file(s) touched, ${stats.openObligations} open obligation(s)). Continue with ${extra} more turns?`;
-    return (await confirmTty(q)) ? extra : 0;
-  };
+  return async (stats) =>
+    (await confirmTty(budgetPromptText(stats))) ? budgetExtraTurns(stats) : 0;
 }
 
 program
@@ -71,6 +67,68 @@ program
 const rendererOf = () =>
   makeRenderer({ json: Boolean(program.opts().json), plain: Boolean(program.opts().plain) });
 
+program
+  .command('repl', { isDefault: true })
+  .description('interactive agent shell (default when no command is given)')
+  .argument('[request...]', 'optional first change request before the prompt loop')
+  .option('--model <model>', 'codex | cursor | gpt-5 | claude | claude-code (or a provider-specific model id)')
+  .option('--max-turns <n>', 'turn budget per request')
+  .option('--allow-dirty', 'let turns run on a dirty working tree')
+  .option('--interactive', 'pause for approval after each proposal validates')
+  .action(
+    async (
+      requestParts: string[],
+      opts: { model?: string; maxTurns?: string; allowDirty?: boolean; interactive?: boolean },
+    ) => {
+      const repo = repoOf(program.opts());
+      if (program.opts().json) {
+        console.error(
+          'copperhead: --json is not supported with the interactive shell. Use `copperhead do "<request>" --json`.',
+        );
+        process.exit(1);
+      }
+      try {
+        const kicadVer = await kicadCliVersion();
+        const config = await loadConfig(repo);
+        const renderer = rendererOf();
+        let model: string;
+        let source: ModelSource;
+        try {
+          ({ model, source } = resolveModel(opts.model, config));
+        } catch (err) {
+          // No model anywhere (flag, COPPERHEAD_MODEL, config, .env keys):
+          // on a TTY, offer an interactive pick instead of refusing to start.
+          if (!process.stdin.isTTY || !process.stdout.isTTY) throw err;
+          console.log('No model configured for this session, pick one:');
+          const chosen = await pickModel();
+          if (!chosen) throw err;
+          model = chosen;
+          source = 'picker';
+        }
+        const continuePrompt = budgetContinuePrompt();
+        const seed = requestParts.length ? requestParts.join(' ') : undefined;
+        const res = await runRepl({
+          repoRoot: repo,
+          model,
+          modelSource: source,
+          version,
+          kicadCliVersion: kicadVer,
+          ...(opts.maxTurns ? { maxTurns: parseMaxTurns(opts.maxTurns) } : {}),
+          allowDirty: opts.allowDirty ?? false,
+          interactive: opts.interactive ?? false,
+          ...(seed ? { seed } : {}),
+          confirm: confirmTty,
+          ...(continuePrompt ? { onBudgetExhausted: continuePrompt } : {}),
+          renderer,
+        });
+        process.exit(res.ok ? 0 : 1);
+      } catch (err) {
+        console.error((err as Error).message);
+        process.exit(1);
+      }
+    },
+  );
+
 program
   .command('init')
   .description('scaffold docs/ from an existing schematic; idempotent')
@@ -121,11 +179,30 @@ program
   .description('ERC + DRC + doc-drift + spec validation; no LLM calls; CI-safe')
   .action(checkAction);
 
+program
+  .command('doctor')
+  .description('env preflight: kicad-cli, git, node, and the model provider credential; no LLM, no network')
+  .option('--model <model>', 'model to check the provider credential for (default: resolved like a run)')
+  .action(async (opts: { model?: string }) => {
+    const repo = repoOf(program.opts());
+    // Unlike other commands, doctor never gates on kicad-cli being present:
+    // runDoctor probes it and reports a failure instead of throwing, so a user
+    // with a missing tool still gets the full report.
+    const report = await runDoctor({ repoRoot: repo, model: opts.model });
+    if (program.opts().json) console.log(JSON.stringify(report, null, 2));
+    else {
+      const color = process.stdout.isTTY === true && !process.env.NO_COLOR;
+      // || not ??: some non-interactive ptys report columns as 0.
+      for (const line of formatDoctor(report, process.stdout.columns || 80, color)) console.log(line);
+    }
+    process.exit(report.ok ? 0 : 1);
+  });
+
 program
   .command('do')
   .description('the core loop: propose, edit, verify, propagate, commit')
   .argument('<request>', 'the change request in natural language')
-  .option('--model <model>', 'codex | gpt-5 | claude | claude-code (or a provider-specific model id)')
+  .option('--model <model>', 'codex | cursor | gpt-5 | claude | claude-code (or a provider-specific model id)')
   .option('--max-turns <n>', 'turn budget for this run')
   .option('--allow-dirty', 'allow a dirty tree (snapshot via git stash create)')
   .option('--dry-run', 'propose the diff, write nothing')
@@ -145,7 +222,7 @@ program
           repoRoot: repo,
           request,
           model,
-          ...(opts.maxTurns ? { maxTurns: parseInt(opts.maxTurns, 10) } : {}),
+          ...(opts.maxTurns ? { maxTurns: parseMaxTurns(opts.maxTurns) } : {}),
           allowDirty: opts.allowDirty ?? false,
           dryRun: opts.dryRun ?? false,
           interactive: opts.interactive ?? false,
@@ -199,11 +276,58 @@ program
     }
   });
 
+program
+  .command('demo')
+  .description('tour of what copperhead does, or run the USB-C breakout create pipeline')
+  .option('--model <model>', 'codex | cursor | gpt-5 | claude | claude-code (or a provider-specific model id)')
+  .option('--interactive', 're-enable the human gates (spec approval, pre-export)')
+  .option('--dir <path>', 'demo repo directory (default: demo-runs/usb-c-breakout)')
+  .option('--tour', 'print the overview only; do not run the pipeline')
+  .action(async (opts: { model?: string; interactive?: boolean; dir?: string; tour?: boolean }) => {
+    if (opts.tour) {
+      const { setColorEnabled } = await import('./agent/theme.js');
+      if (program.opts().json) {
+        // --json is a contract, not a suggestion: a script that passes it
+        // unconditionally must never get prose back. Plain lines, no SGR.
+        setColorEnabled(false);
+        console.log(JSON.stringify({ tour: demoTourText().split('\n') }, null, 2));
+        process.exit(0);
+      }
+      // Color on for attended TTY tours even without a renderer.
+      setColorEnabled(Boolean(process.stdout.isTTY) && !program.opts().plain && !process.env.NO_COLOR);
+      console.log(demoTourText());
+      process.exit(0);
+    }
+    try {
+      const kicadVer = await kicadCliVersion();
+      // Resolve model from the caller's cwd config / env / flag; the demo repo
+      // is scaffolded next and typically has no model of its own yet.
+      const config = await loadConfig(repoOf(program.opts()));
+      const { model, source } = resolveModel(opts.model, config);
+      const continuePrompt = budgetContinuePrompt();
+      const res = await runDemo({
+        model,
+        modelSource: source,
+        version,
+        kicadCliVersion: kicadVer,
+        interactive: opts.interactive ?? false,
+        ...(opts.dir ? { demoDir: opts.dir } : {}),
+        ...(continuePrompt ? { onBudgetExhausted: continuePrompt } : {}),
+        log: (s) => console.log(s),
+        renderer: rendererOf(),
+      });
+      process.exit(res.ok ? 0 : 1);
+    } catch (err) {
+      console.error((err as Error).message);
+      process.exit(1);
+    }
+  });
+
 program
   .command('create')
   .description('Mode A: full pipeline from a product brief to the output package')
   .requiredOption('--brief <file>', 'product brief (markdown)')
-  .option('--model <model>', 'codex | gpt-5 | claude | claude-code (or a provider-specific model id)')
+  .option('--model <model>', 'codex | cursor | gpt-5 | claude | claude-code (or a provider-specific model id)')
   .option('--interactive', 're-enable the human gates (spec approval, pre-export)')
   .action(async (opts: { brief: string; model?: string; interactive?: boolean }) => {
     const repo = repoOf(program.opts());