@0xtiby/toby 1.0.1 → 1.2.0

package/dist/cli.js

@@ -2,7 +2,7 @@
 
 // src/cli.tsx
 import meow from "meow";
-import { render, Text as Text13 } from "ink";
+import { render } from "ink";
 
 // src/commands/plan.tsx
 import { useState as useState3, useEffect as useEffect2, useMemo as useMemo2 } from "react";
@@ -80,6 +80,7 @@ var LOCAL_TOBY_DIR = ".toby";
 var DEFAULT_SPECS_DIR = "specs";
 var STATUS_FILE = "status.json";
 var CONFIG_FILE = "config.json";
+var TRANSCRIPTS_DIR = "transcripts";
 function getGlobalDir() {
   return path.join(os.homedir(), GLOBAL_TOBY_DIR);
 }
@@ -111,6 +112,220 @@ function ensureLocalDir(cwd) {
   return dir;
 }
 
+// src/lib/help.ts
+var SPEC_FLAGS = [
+  { name: "--spec=<query>", description: "Target spec(s) by name, slug, number, or list" },
+  { name: "--specs=<names>", description: "Alias for --spec" },
+  { name: "--all", description: "Process all matching specs" },
+  { name: "--iterations=<n>", description: "Override iteration count" },
+  { name: "--verbose", description: "Show full CLI output" },
+  { name: "--transcript", description: "Save session transcript to file" },
+  { name: "--cli=<name>", description: "Override AI CLI (claude, codex, opencode)" },
+  { name: "--session=<name>", description: "Name the session for branch/PR naming" }
+];
+var commandHelp = {
+  plan: {
+    summary: "Plan specs with AI loop engine",
+    usage: ["$ toby plan [options]"],
+    flags: SPEC_FLAGS,
+    examples: [
+      {
+        command: "toby plan --spec=auth --cli=claude --session=auth-feature",
+        description: 'Plan the auth spec using Claude, naming the session "auth-feature"'
+      },
+      {
+        command: "toby plan --spec=auth,payments --iterations=3 --verbose",
+        description: "Plan auth and payments specs with 3 iterations, showing full output"
+      },
+      {
+        command: "toby plan --all --transcript",
+        description: "Plan all pending specs and save a transcript of the session"
+      }
+    ]
+  },
+  build: {
+    summary: "Build tasks one-per-spawn with AI",
+    usage: ["$ toby build [options]"],
+    flags: SPEC_FLAGS,
+    examples: [
+      {
+        command: "toby build --spec=auth --cli=claude --session=auth-feature",
+        description: 'Build the auth spec using Claude, resuming "auth-feature"'
+      },
+      {
+        command: "toby build --all --iterations=5 --transcript",
+        description: "Build all planned specs with up to 5 iterations, saving transcripts"
+      },
+      {
+        command: "toby build --spec=2 --verbose",
+        description: "Build spec #2 with full CLI output visible"
+      }
+    ]
+  },
+  init: {
+    summary: "Initialize toby in current project",
+    usage: ["$ toby init [options]"],
+    flags: [
+      {
+        name: "--plan-cli=<name>",
+        description: "Set plan CLI (claude, codex, opencode)"
+      },
+      { name: "--plan-model=<id>", description: "Set plan model" },
+      {
+        name: "--build-cli=<name>",
+        description: "Set build CLI (claude, codex, opencode)"
+      },
+      { name: "--build-model=<id>", description: "Set build model" },
+      { name: "--specs-dir=<path>", description: "Set specs directory" },
+      {
+        name: "--verbose",
+        description: "Enable verbose output in config"
+      }
+    ],
+    examples: [
+      {
+        command: "toby init",
+        description: "Launch the interactive setup wizard"
+      },
+      {
+        command: "toby init --plan-cli=claude --build-cli=claude --specs-dir=specs",
+        description: "Non-interactive init with required flags (for CI/agents)"
+      },
+      {
+        command: "toby init --plan-cli=codex --build-cli=codex --specs-dir=specs --verbose",
+        description: "Initialize with Codex for both phases, verbose enabled"
+      }
+    ]
+  },
+  status: {
+    summary: "Show project status",
+    usage: ["$ toby status [options]"],
+    flags: [
+      {
+        name: "--spec=<query>",
+        description: "Show status for a specific spec by name, slug, or number"
+      }
+    ],
+    examples: [
+      {
+        command: "toby status",
+        description: "Show status overview for all specs in the project"
+      },
+      {
+        command: "toby status --spec=auth",
+        description: "Show detailed status for the auth spec"
+      }
+    ]
+  },
+  config: {
+    summary: "Manage configuration",
+    usage: [
+      "$ toby config                           Interactive config editor",
+      "$ toby config get <key>                 Show a config value (dot-notation)",
+      "$ toby config set <key> <value>         Set a config value",
+      "$ toby config set <k>=<v> [<k>=<v>...]  Batch set values"
+    ],
+    flags: [],
+    examples: [
+      {
+        command: "toby config",
+        description: "Open the interactive config editor"
+      },
+      {
+        command: "toby config get plan.cli",
+        description: "Show the configured plan CLI"
+      },
+      {
+        command: "toby config set plan.cli=claude build.iterations=5",
+        description: "Batch set plan CLI to claude and build iterations to 5"
+      }
+    ]
+  },
+  clean: {
+    summary: "Delete session transcripts",
+    usage: ["$ toby clean [options]"],
+    flags: [
+      {
+        name: "--force",
+        description: "Skip confirmation prompt (required in non-TTY)"
+      }
+    ],
+    examples: [
+      {
+        command: "toby clean",
+        description: "Delete all transcripts with confirmation prompt"
+      },
+      {
+        command: "toby clean --force",
+        description: "Delete all transcripts without confirmation (for CI/agents)"
+      }
+    ]
+  }
+};
+function formatCommandHelp(command2, help) {
+  const lines = [];
+  lines.push(`toby ${command2} \u2014 ${help.summary}`);
+  lines.push("");
+  lines.push("Usage");
+  for (const usage of help.usage) {
+    lines.push(`  ${usage}`);
+  }
+  if (help.flags.length > 0) {
+    lines.push("");
+    lines.push("Options");
+    const maxName = Math.max(...help.flags.map((f) => f.name.length));
+    for (const flag of help.flags) {
+      lines.push(`  ${flag.name.padEnd(maxName)}   ${flag.description}`);
+    }
+  }
+  lines.push("");
+  lines.push("Examples");
+  const exampleBlocks = help.examples.map(
+    (ex) => `  $ ${ex.command}
+    ${ex.description}`
+  );
+  lines.push(exampleBlocks.join("\n\n"));
+  lines.push("");
+  return lines.join("\n");
+}
+function formatErrorWithHint(message, validValues, example) {
+  const lines = [];
+  if (validValues) {
+    lines.push(`\u2717 ${message}. Valid options: ${validValues.join(", ")}`);
+  } else {
+    lines.push(`\u2717 ${message}`);
+  }
+  if (example) {
+    lines.push("");
+    lines.push("Example:");
+    lines.push(`  $ ${example}`);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function formatGlobalHelp(version2) {
+  const maxCmd = Math.max(
+    ...Object.keys(commandHelp).map((c) => c.length)
+  );
+  const cmdLines = Object.entries(commandHelp).map(([name, h]) => `  ${name.padEnd(maxCmd)}   ${h.summary}`).join("\n");
+  return [
+    `toby v${version2} \u2014 AI-assisted development loop engine`,
+    "",
+    "Usage",
+    "  $ toby <command> [options]",
+    "",
+    "Commands",
+    cmdLines,
+    "",
+    "Options",
+    "  --help       Show help (use with a command for details)",
+    "  --version    Show version",
+    "",
+    "Run toby <command> --help for command-specific options and examples.",
+    ""
+  ].join("\n");
+}
+
 // src/lib/config.ts
 function readConfigFile(filePath) {
   try {
@@ -153,7 +368,13 @@ function writeConfig(config, filePath) {
 }
 function validateCliName(cli2) {
   if (cli2 && !CLI_NAMES.includes(cli2)) {
-    throw new Error(`Unknown CLI: ${cli2}. Must be one of: ${CLI_NAMES.join(", ")}`);
+    throw new Error(
+      formatErrorWithHint(
+        `Unknown CLI: ${cli2}`,
+        [...CLI_NAMES],
+        "toby plan --cli=claude --spec=auth"
+      )
+    );
   }
 }
 function resolveCommandConfig(config, command2, flags2 = {}) {
@@ -567,7 +788,6 @@ var AbortError = class extends Error {
 // src/lib/transcript.ts
 import fs6 from "fs";
 import path6 from "path";
-var TRANSCRIPTS_DIR = "transcripts";
 function formatTimestamp() {
   const now = /* @__PURE__ */ new Date();
   const pad2 = (n, len = 2) => String(n).padStart(len, "0");
@@ -2582,13 +2802,127 @@ Usage: toby config set <key> <value>` });
   ] });
 }
 
+// src/commands/clean.tsx
+import { useState as useState8, useEffect as useEffect7, useMemo as useMemo4 } from "react";
+import { Text as Text9, useApp as useApp4, useInput as useInput2 } from "ink";
+
+// src/lib/clean.ts
+import path9 from "path";
+import fs10 from "fs";
+function listTranscripts(cwd) {
+  const dir = path9.join(getLocalDir(cwd), TRANSCRIPTS_DIR);
+  let entries;
+  try {
+    entries = fs10.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries.filter((e) => e.isFile()).map((e) => path9.join(dir, e.name));
+}
+function deleteTranscripts(files) {
+  let deleted = 0;
+  for (const file of files) {
+    try {
+      fs10.unlinkSync(file);
+      deleted++;
+    } catch {
+    }
+  }
+  return deleted;
+}
+function executeClean(cwd) {
+  const files = listTranscripts(cwd);
+  if (files.length === 0) {
+    return { deleted: 0, failed: 0, total: 0 };
+  }
+  const deleted = deleteTranscripts(files);
+  return { deleted, failed: files.length - deleted, total: files.length };
+}
+
+// src/commands/clean.tsx
+import { jsx as jsx9, jsxs as jsxs8 } from "react/jsx-runtime";
+function computeInitial(force) {
+  const files = listTranscripts();
+  if (files.length === 0) {
+    return { phase: "empty", fileCount: 0, result: null };
+  }
+  if (!process.stdin.isTTY && !force) {
+    return { phase: "error", fileCount: files.length, result: null };
+  }
+  if (force) {
+    const r = executeClean();
+    return { phase: "done", fileCount: files.length, result: r };
+  }
+  return { phase: "confirming", fileCount: files.length, result: null };
+}
+function Clean({ force }) {
+  const { exit } = useApp4();
+  const initial = useMemo4(() => computeInitial(force), [force]);
+  useEffect7(() => {
+    if (initial.phase === "error") {
+      process.exitCode = 1;
+    }
+  }, [initial.phase]);
+  const [phase, setPhase] = useState8(initial.phase);
+  const [result, setResult] = useState8(initial.result);
+  useEffect7(() => {
+    if (phase === "empty" || phase === "done" || phase === "cancelled" || phase === "error") {
+      const timer = setTimeout(() => exit(), 100);
+      return () => clearTimeout(timer);
+    }
+  }, [phase, exit]);
+  useInput2((input, key) => {
+    if (phase !== "confirming") return;
+    if (input === "y" || key.return) {
+      const r = executeClean();
+      setResult(r);
+      setPhase("done");
+    } else if (input === "n" || key.escape) {
+      setPhase("cancelled");
+    }
+  });
+  if (phase === "error") {
+    return /* @__PURE__ */ jsx9(Text9, { color: "red", children: "Error: Use --force to clean transcripts in non-interactive mode." });
+  }
+  if (phase === "empty") {
+    return /* @__PURE__ */ jsx9(Text9, { children: "No transcripts to clean." });
+  }
+  if (phase === "confirming") {
+    return /* @__PURE__ */ jsxs8(Text9, { children: [
+      "Found ",
+      initial.fileCount,
+      " transcript files. Delete all? [Y/n]"
+    ] });
+  }
+  if (phase === "done" && result) {
+    if (result.failed > 0) {
+      return /* @__PURE__ */ jsxs8(Text9, { children: [
+        "Deleted ",
+        result.deleted,
+        " transcript files. Failed to delete ",
+        result.failed,
+        " files."
+      ] });
+    }
+    return /* @__PURE__ */ jsxs8(Text9, { children: [
+      "Deleted ",
+      result.deleted,
+      " transcript files."
+    ] });
+  }
+  if (phase === "cancelled") {
+    return /* @__PURE__ */ jsx9(Text9, { children: "Clean cancelled." });
+  }
+  return null;
+}
+
 // src/components/Welcome.tsx
-import { useState as useState9, useEffect as useEffect8, useMemo as useMemo5 } from "react";
-import { Box as Box12, Text as Text12, useApp as useApp4, useStdout as useStdout2 } from "ink";
+import { useState as useState10, useEffect as useEffect9, useMemo as useMemo6 } from "react";
+import { Box as Box12, Text as Text13, useApp as useApp5, useStdout as useStdout2 } from "ink";
 
 // src/components/hamster/HamsterWheel.tsx
-import { useState as useState8, useEffect as useEffect7, useMemo as useMemo4 } from "react";
-import { Box as Box9, Text as Text9, useStdout } from "ink";
+import { useState as useState9, useEffect as useEffect8, useMemo as useMemo5 } from "react";
+import { Box as Box9, Text as Text10, useStdout } from "ink";
 
 // src/components/hamster/palette.ts
 var PALETTE = {
@@ -2747,7 +3081,7 @@ function generateWheelPixels(cx, cy, outerRadius, innerRadius, spokeAngle, aspec
 }
 
 // src/components/hamster/HamsterWheel.tsx
-import { jsx as jsx9 } from "react/jsx-runtime";
+import { jsx as jsx10 } from "react/jsx-runtime";
 function buildGrid(width, height) {
   return Array.from(
     { length: height },
@@ -2830,9 +3164,9 @@ function HamsterWheel({
     heightProp,
     columns
   );
-  const [frame, setFrame] = useState8(0);
-  const [spokeAngle, setSpokeAngle] = useState8(0);
-  useEffect7(() => {
+  const [frame, setFrame] = useState9(0);
+  const [spokeAngle, setSpokeAngle] = useState9(0);
+  useEffect8(() => {
     if (speed === 0 || isStatic) return;
     const interval = computeInterval(HAMSTER_BASE_INTERVAL, speed);
     const id = setInterval(() => {
@@ -2840,7 +3174,7 @@ function HamsterWheel({
     }, interval);
     return () => clearInterval(id);
   }, [speed, isStatic]);
-  useEffect7(() => {
+  useEffect8(() => {
     if (speed === 0 || isStatic) return;
     const interval = computeInterval(WHEEL_BASE_INTERVAL, speed);
     const id = setInterval(() => {
@@ -2848,7 +3182,7 @@ function HamsterWheel({
     }, interval);
     return () => clearInterval(id);
   }, [speed, isStatic]);
-  const renderedRows = useMemo4(() => {
+  const renderedRows = useMemo5(() => {
     if (isStatic) return [];
     const grid = buildGrid(resolvedWidth, resolvedHeight);
     const { cx, cy, outerRadius, innerRadius } = computeWheelGeometry(
@@ -2880,43 +3214,43 @@ function HamsterWheel({
     return buildColorRuns(grid, resolvedWidth, resolvedHeight);
   }, [resolvedWidth, resolvedHeight, frame, spokeAngle, isStatic]);
   if (isStatic) {
-    return /* @__PURE__ */ jsx9(Text9, { children: "  \u{1F439} toby" });
+    return /* @__PURE__ */ jsx10(Text10, { children: "  \u{1F439} toby" });
   }
-  return /* @__PURE__ */ jsx9(Box9, { flexDirection: "column", children: renderedRows.map((runs, y) => /* @__PURE__ */ jsx9(Text9, { children: runs.map((run, i) => /* @__PURE__ */ jsx9(Text9, { color: run.fg, backgroundColor: run.bg, children: run.char.repeat(run.length) }, i)) }, y)) });
+  return /* @__PURE__ */ jsx10(Box9, { flexDirection: "column", children: renderedRows.map((runs, y) => /* @__PURE__ */ jsx10(Text10, { children: runs.map((run, i) => /* @__PURE__ */ jsx10(Text10, { color: run.fg, backgroundColor: run.bg, children: run.char.repeat(run.length) }, i)) }, y)) });
 }
 
 // src/components/InfoPanel.tsx
-import { Box as Box10, Text as Text10 } from "ink";
-import { jsx as jsx10, jsxs as jsxs8 } from "react/jsx-runtime";
+import { Box as Box10, Text as Text11 } from "ink";
+import { jsx as jsx11, jsxs as jsxs9 } from "react/jsx-runtime";
 var formatTokens = (n) => new Intl.NumberFormat().format(n);
 function StatRow({ label, value }) {
-  return /* @__PURE__ */ jsxs8(Box10, { children: [
-    /* @__PURE__ */ jsxs8(Text10, { dimColor: true, children: [
+  return /* @__PURE__ */ jsxs9(Box10, { children: [
+    /* @__PURE__ */ jsxs9(Text11, { dimColor: true, children: [
       String(label).padStart(9),
       "  "
     ] }),
-    /* @__PURE__ */ jsx10(Text10, { children: value })
+    /* @__PURE__ */ jsx11(Text11, { children: value })
   ] });
 }
 function InfoPanel({ version: version2, stats }) {
-  return /* @__PURE__ */ jsxs8(Box10, { flexDirection: "column", children: [
-    /* @__PURE__ */ jsxs8(Text10, { bold: true, color: "#f0a030", children: [
+  return /* @__PURE__ */ jsxs9(Box10, { flexDirection: "column", children: [
+    /* @__PURE__ */ jsxs9(Text11, { bold: true, color: "#f0a030", children: [
       "toby v",
       version2
     ] }),
-    stats !== null && /* @__PURE__ */ jsxs8(Box10, { flexDirection: "column", marginTop: 1, children: [
-      /* @__PURE__ */ jsx10(StatRow, { label: "Specs", value: stats.totalSpecs }),
-      /* @__PURE__ */ jsx10(StatRow, { label: "Planned", value: stats.planned }),
-      /* @__PURE__ */ jsx10(StatRow, { label: "Done", value: stats.done }),
-      /* @__PURE__ */ jsx10(StatRow, { label: "Tokens", value: formatTokens(stats.totalTokens) })
+    stats !== null && /* @__PURE__ */ jsxs9(Box10, { flexDirection: "column", marginTop: 1, children: [
+      /* @__PURE__ */ jsx11(StatRow, { label: "Specs", value: stats.totalSpecs }),
+      /* @__PURE__ */ jsx11(StatRow, { label: "Planned", value: stats.planned }),
+      /* @__PURE__ */ jsx11(StatRow, { label: "Done", value: stats.done }),
+      /* @__PURE__ */ jsx11(StatRow, { label: "Tokens", value: formatTokens(stats.totalTokens) })
     ] })
   ] });
 }
 
 // src/components/MainMenu.tsx
-import { Text as Text11, Box as Box11 } from "ink";
+import { Text as Text12, Box as Box11 } from "ink";
 import SelectInput3 from "ink-select-input";
-import { jsx as jsx11, jsxs as jsxs9 } from "react/jsx-runtime";
+import { jsx as jsx12, jsxs as jsxs10 } from "react/jsx-runtime";
 var MENU_ITEMS = [
   { label: "plan", value: "plan", description: "Plan specs with AI loop engine" },
   { label: "build", value: "build", description: "Build tasks one-per-spawn with AI" },
@@ -2924,16 +3258,16 @@ var MENU_ITEMS = [
   { label: "config", value: "config", description: "Manage configuration" }
 ];
 function MenuItem({ isSelected = false, label, description }) {
-  return /* @__PURE__ */ jsxs9(Box11, { children: [
-    /* @__PURE__ */ jsx11(Text11, { color: isSelected ? "blue" : void 0, children: label.padEnd(10) }),
-    description && /* @__PURE__ */ jsxs9(Text11, { dimColor: true, children: [
+  return /* @__PURE__ */ jsxs10(Box11, { children: [
+    /* @__PURE__ */ jsx12(Text12, { color: isSelected ? "blue" : void 0, children: label.padEnd(10) }),
+    description && /* @__PURE__ */ jsxs10(Text12, { dimColor: true, children: [
       "\u2014 ",
       description
     ] })
   ] });
 }
 function MainMenu({ onSelect }) {
-  return /* @__PURE__ */ jsx11(Box11, { flexDirection: "column", children: /* @__PURE__ */ jsx11(
+  return /* @__PURE__ */ jsx12(Box11, { flexDirection: "column", children: /* @__PURE__ */ jsx12(
     SelectInput3,
     {
       items: MENU_ITEMS,
@@ -2944,9 +3278,9 @@ function MainMenu({ onSelect }) {
 }
 
 // src/lib/stats.ts
-import fs10 from "fs";
+import fs11 from "fs";
 function computeProjectStats(cwd) {
-  if (!fs10.existsSync(getLocalDir(cwd))) {
+  if (!fs11.existsSync(getLocalDir(cwd))) {
     return null;
   }
   let statusData;
@@ -2988,157 +3322,99 @@ function computeProjectStats(cwd) {
 }
 
 // src/components/Welcome.tsx
-import { jsx as jsx12, jsxs as jsxs10 } from "react/jsx-runtime";
+import { jsx as jsx13, jsxs as jsxs11 } from "react/jsx-runtime";
 var NARROW_THRESHOLD = 60;
 function Welcome({ version: version2 }) {
-  const { exit } = useApp4();
+  const { exit } = useApp5();
   const { stdout } = useStdout2();
-  const [selectedCommand, setSelectedCommand] = useState9(null);
-  const stats = useMemo5(() => computeProjectStats(), []);
+  const [selectedCommand, setSelectedCommand] = useState10(null);
+  const stats = useMemo6(() => computeProjectStats(), []);
   const isNarrow = (stdout.columns ?? 80) < NARROW_THRESHOLD;
-  useEffect8(() => {
+  useEffect9(() => {
     if (selectedCommand === "status") {
       const timer = setTimeout(() => exit(), 0);
       return () => clearTimeout(timer);
     }
   }, [selectedCommand, exit]);
   if (selectedCommand === "plan") {
-    return /* @__PURE__ */ jsx12(Plan, {});
+    return /* @__PURE__ */ jsx13(Plan, {});
   }
   if (selectedCommand === "build") {
-    return /* @__PURE__ */ jsx12(Build, {});
+    return /* @__PURE__ */ jsx13(Build, {});
   }
   if (selectedCommand === "status") {
-    return /* @__PURE__ */ jsx12(Status, { version: version2 });
+    return /* @__PURE__ */ jsx13(Status, { version: version2 });
   }
   if (selectedCommand === "config") {
-    return /* @__PURE__ */ jsx12(ConfigEditor, { version: version2 });
+    return /* @__PURE__ */ jsx13(ConfigEditor, { version: version2 });
   }
-  return /* @__PURE__ */ jsxs10(Box12, { flexDirection: "column", gap: 1, children: [
-    isNarrow ? /* @__PURE__ */ jsxs10(Box12, { flexDirection: "column", children: [
-      /* @__PURE__ */ jsxs10(Text12, { bold: true, color: "#f0a030", children: [
+  return /* @__PURE__ */ jsxs11(Box12, { flexDirection: "column", gap: 1, children: [
+    isNarrow ? /* @__PURE__ */ jsxs11(Box12, { flexDirection: "column", children: [
+      /* @__PURE__ */ jsxs11(Text13, { bold: true, color: "#f0a030", children: [
         "\u{1F439} toby v",
         version2
       ] }),
-      stats !== null && /* @__PURE__ */ jsxs10(Text12, { children: [
-        /* @__PURE__ */ jsx12(Text12, { dimColor: true, children: "Specs: " }),
-        /* @__PURE__ */ jsx12(Text12, { children: stats.totalSpecs }),
-        /* @__PURE__ */ jsx12(Text12, { dimColor: true, children: " \xB7 Planned: " }),
-        /* @__PURE__ */ jsx12(Text12, { children: stats.planned }),
-        /* @__PURE__ */ jsx12(Text12, { dimColor: true, children: " \xB7 Done: " }),
-        /* @__PURE__ */ jsx12(Text12, { children: stats.done }),
-        /* @__PURE__ */ jsx12(Text12, { dimColor: true, children: " \xB7 Tokens: " }),
-        /* @__PURE__ */ jsx12(Text12, { children: formatTokens(stats.totalTokens) })
+      stats !== null && /* @__PURE__ */ jsxs11(Text13, { children: [
+        /* @__PURE__ */ jsx13(Text13, { dimColor: true, children: "Specs: " }),
+        /* @__PURE__ */ jsx13(Text13, { children: stats.totalSpecs }),
+        /* @__PURE__ */ jsx13(Text13, { dimColor: true, children: " \xB7 Planned: " }),
+        /* @__PURE__ */ jsx13(Text13, { children: stats.planned }),
+        /* @__PURE__ */ jsx13(Text13, { dimColor: true, children: " \xB7 Done: " }),
+        /* @__PURE__ */ jsx13(Text13, { children: stats.done }),
+        /* @__PURE__ */ jsx13(Text13, { dimColor: true, children: " \xB7 Tokens: " }),
+        /* @__PURE__ */ jsx13(Text13, { children: formatTokens(stats.totalTokens) })
       ] })
-    ] }) : /* @__PURE__ */ jsxs10(Box12, { flexDirection: "row", gap: 2, children: [
-      /* @__PURE__ */ jsx12(HamsterWheel, {}),
-      /* @__PURE__ */ jsx12(InfoPanel, { version: version2, stats })
+    ] }) : /* @__PURE__ */ jsxs11(Box12, { flexDirection: "row", gap: 2, children: [
+      /* @__PURE__ */ jsx13(HamsterWheel, {}),
+      /* @__PURE__ */ jsx13(InfoPanel, { version: version2, stats })
     ] }),
-    /* @__PURE__ */ jsx12(MainMenu, { onSelect: setSelectedCommand })
+    /* @__PURE__ */ jsx13(MainMenu, { onSelect: setSelectedCommand })
   ] });
 }
 
-// src/cli.tsx
-import { jsx as jsx13 } from "react/jsx-runtime";
-function Help({ version: version2 }) {
-  return /* @__PURE__ */ jsx13(Text13, { children: `toby v${version2} \u2014 AI-assisted development loop engine
-
-Usage
-  $ toby <command> [options]
-
-Commands
-  plan     Plan specs with AI loop engine
-  build    Build tasks one-per-spawn with AI
-  init     Initialize toby in current project
-  status   Show project status
-  config   Manage configuration
-
-Options
-  --help       Show this help
-  --version    Show version
-
-Spec Selection
-  --spec=<name>       Single spec or comma-separated (e.g. --spec=auth,payments)
-  --specs=<names>     Alias for --spec` });
-}
-function UnknownCommand({ command: command2 }) {
-  return /* @__PURE__ */ jsx13(Text13, { color: "red", children: `Unknown command: ${command2}
-Run "toby --help" for available commands.` });
-}
-var cli = meow(
-  `
-Usage
-  $ toby <command> [options]
-
-Commands
-  plan     Plan specs with AI loop engine
-  build    Build tasks one-per-spawn with AI
-  init     Initialize toby in current project
-  status   Show project status
-  config   Manage configuration
-
-Plan Options
-  --spec=<query>     Target spec(s) by name, slug, number, or comma-separated list
-  --specs=<names>    Alias for --spec with comma-separated specs
-  --all              Plan all pending specs
-  --iterations=<n>   Override iteration count
-  --verbose          Show full CLI output
-  --transcript       Save session transcript to file
-  --cli=<name>       Override AI CLI (claude, codex, opencode)
-  --session=<name>   Name the session for branch/PR naming
-
-Build Options
-  --spec=<query>     Target spec(s) by name, slug, number, or comma-separated list
-  --specs=<names>    Alias for --spec with comma-separated specs
-  --all              Build all planned specs in order
-  --iterations=<n>   Override max iteration count
-  --verbose          Show full CLI output
-  --transcript       Save session transcript to file
-  --cli=<name>       Override AI CLI (claude, codex, opencode)
-  --session=<name>   Name the session for branch/PR naming
-
-Status Options
-  --spec=<query>     Show status for a spec by name, slug, or number
-
-Init Options
-  --plan-cli=<name>    Set plan CLI (claude, codex, opencode)
-  --plan-model=<id>    Set plan model
-  --build-cli=<name>   Set build CLI (claude, codex, opencode)
-  --build-model=<id>   Set build model
-  --specs-dir=<path>   Set specs directory
-  --verbose            Enable verbose output in config
+// src/lib/cli-meta.ts
+var COMMAND_NAMES = Object.keys(commandHelp);
+var MEOW_FLAGS = {
+  help: { type: "boolean", default: false },
+  spec: { type: "string" },
+  specs: { type: "string" },
+  all: { type: "boolean", default: false },
+  iterations: { type: "number" },
+  verbose: { type: "boolean", default: false },
+  transcript: { type: "boolean" },
+  cli: { type: "string" },
+  planCli: { type: "string" },
+  planModel: { type: "string" },
+  buildCli: { type: "string" },
+  buildModel: { type: "string" },
+  specsDir: { type: "string" },
+  session: { type: "string" },
+  force: { type: "boolean", default: false }
+};
+var MEOW_FLAG_NAMES = Object.keys(MEOW_FLAGS);
 
-Config Subcommands
-  config             Interactive config editor
-  config get <key>   Show a config value (dot-notation)
-  config set <key> <value>  Set a config value
-  config set <k>=<v> [<k>=<v>...]  Batch set config values
-`,
-  {
-    importMeta: import.meta,
-    flags: {
-      spec: { type: "string" },
-      specs: { type: "string" },
-      all: { type: "boolean", default: false },
-      iterations: { type: "number" },
-      verbose: { type: "boolean", default: false },
-      transcript: { type: "boolean" },
-      cli: { type: "string" },
-      planCli: { type: "string" },
-      planModel: { type: "string" },
-      buildCli: { type: "string" },
-      buildModel: { type: "string" },
-      specsDir: { type: "string" },
-      session: { type: "string" }
-    }
-  }
-);
+// src/cli.tsx
+import { jsx as jsx14 } from "react/jsx-runtime";
+function writeUnknownCommandError(command2) {
+  process.stderr.write(
+    formatErrorWithHint(
+      `Unknown command: ${command2}`,
+      COMMAND_NAMES,
+      "toby --help"
+    )
+  );
+}
+var cli = meow("", {
+  importMeta: import.meta,
+  autoHelp: false,
+  flags: MEOW_FLAGS
+});
 ensureGlobalDir();
 var resolvedSpec = cli.flags.specs ?? cli.flags.spec;
 var flags = { ...cli.flags, spec: resolvedSpec };
 var commands = {
   plan: {
-    render: (flags2) => /* @__PURE__ */ jsx13(
+    render: (flags2) => /* @__PURE__ */ jsx14(
       Plan,
       {
         spec: flags2.spec,
@@ -3153,7 +3429,7 @@ var commands = {
     waitForExit: true
   },
   build: {
-    render: (flags2) => /* @__PURE__ */ jsx13(
+    render: (flags2) => /* @__PURE__ */ jsx14(
       Build,
       {
         spec: flags2.spec,
@@ -3168,7 +3444,7 @@ var commands = {
     waitForExit: true
   },
   init: {
-    render: (flags2, _input, version2) => /* @__PURE__ */ jsx13(
+    render: (flags2, _input, version2) => /* @__PURE__ */ jsx14(
       Init,
       {
         version: version2,
@@ -3183,17 +3459,21 @@ var commands = {
     waitForExit: true
   },
   status: {
-    render: (flags2, _input, version2) => /* @__PURE__ */ jsx13(Status, { spec: flags2.spec, version: version2 })
+    render: (flags2, _input, version2) => /* @__PURE__ */ jsx14(Status, { spec: flags2.spec, version: version2 })
+  },
+  clean: {
+    render: (flags2) => /* @__PURE__ */ jsx14(Clean, { force: flags2.force }),
+    waitForExit: true
   },
   config: {
     render: (_flags, input, version2) => {
       const [, subcommand, ...rest] = input;
-      if (!subcommand) return /* @__PURE__ */ jsx13(ConfigEditor, { version: version2 });
+      if (!subcommand) return /* @__PURE__ */ jsx14(ConfigEditor, { version: version2 });
       if (subcommand === "set" && rest.some((arg) => arg.includes("="))) {
-        return /* @__PURE__ */ jsx13(ConfigSetBatch, { pairs: rest.filter((arg) => arg.includes("=")) });
+        return /* @__PURE__ */ jsx14(ConfigSetBatch, { pairs: rest.filter((arg) => arg.includes("=")) });
       }
       const [configKey, value] = rest;
-      return /* @__PURE__ */ jsx13(
+      return /* @__PURE__ */ jsx14(
         Config,
         {
           subcommand,
@@ -3208,12 +3488,24 @@ var commands = {
 };
 var version = cli.pkg.version ?? "0.0.0";
 var [command] = cli.input;
-if (!command) {
+if (cli.flags.help) {
+  if (!command || command in commands) {
+    if (command && command in commandHelp) {
+      process.stdout.write(formatCommandHelp(command, commandHelp[command]));
+    } else {
+      process.stdout.write(formatGlobalHelp(version));
+    }
+    process.exitCode = 0;
+  } else {
+    writeUnknownCommandError(command);
+    process.exitCode = 1;
+  }
+} else if (!command) {
   if (process.stdin.isTTY) {
-    const app = render(/* @__PURE__ */ jsx13(Welcome, { version }));
+    const app = render(/* @__PURE__ */ jsx14(Welcome, { version }));
     await app.waitUntilExit();
   } else {
-    render(/* @__PURE__ */ jsx13(Help, { version })).unmount();
+    process.stdout.write(formatGlobalHelp(version));
   }
 } else if (command in commands) {
   const entry = commands[command];
@@ -3224,6 +3516,6 @@ if (!command) {
     app.unmount();
   }
 } else {
-  render(/* @__PURE__ */ jsx13(UnknownCommand, { command })).unmount();
+  writeUnknownCommandError(command);
   process.exitCode = 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@0xtiby/toby",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "AI-assisted development loop engine CLI",
   "repository": {
     "type": "git",