@iamu-dev/iamu 0.2.0-beta.11 → 0.2.0-beta.13

package/dist/index.js

@@ -12184,15 +12184,15 @@ function resolveApiUrl(configured) {
   assertSecureApiUrl(url, configured ? "API URL" : "IAMU_API_URL");
   return url;
 }
-function parseStore(raw, path31) {
+function parseStore(raw, path32) {
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch (err) {
-    throw new CredentialsFileError(path31, "not valid JSON", err);
+    throw new CredentialsFileError(path32, "not valid JSON", err);
   }
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    throw new CredentialsFileError(path31, "expected a JSON object");
+    throw new CredentialsFileError(path32, "expected a JSON object");
   }
   return parsed;
 }
@@ -12200,26 +12200,26 @@ function isNotFound(err) {
   return typeof err === "object" && err !== null && err.code === "ENOENT";
 }
 async function readCredentialsStore() {
-  const path31 = getCredentialsPath();
+  const path32 = getCredentialsPath();
   let raw;
   try {
-    raw = await readFile(path31, "utf-8");
+    raw = await readFile(path32, "utf-8");
   } catch (err) {
     if (isNotFound(err)) return {};
     warnUnreadableStoreOnce(err);
     throw err;
   }
   try {
-    return parseStore(raw, path31);
+    return parseStore(raw, path32);
   } catch (err) {
     warnUnreadableStoreOnce(err);
     throw err;
   }
 }
 async function writeCredentialsStore(store) {
-  const path31 = getCredentialsPath();
-  await mkdir(dirname(path31), { recursive: true, mode: 448 });
-  await atomicWriteFile(path31, `${JSON.stringify(store, null, 2)}
+  const path32 = getCredentialsPath();
+  await mkdir(dirname(path32), { recursive: true, mode: 448 });
+  await atomicWriteFile(path32, `${JSON.stringify(store, null, 2)}
 `, {
     mode: 384
   });
@@ -12239,16 +12239,16 @@ function resolveApiKey(apiUrl) {
   } catch {
     return null;
   }
-  const path31 = getCredentialsPath();
+  const path32 = getCredentialsPath();
   let raw;
   try {
-    raw = readFileSync(path31, "utf-8");
+    raw = readFileSync(path32, "utf-8");
   } catch (err) {
     if (!isNotFound(err)) warnUnreadableStoreOnce(err);
     return null;
   }
   try {
-    const entry = parseStore(raw, path31)[url];
+    const entry = parseStore(raw, path32)[url];
     if (typeof entry !== "object" || entry === null) return null;
     const token = entry.token;
     return typeof token === "string" && token ? token : null;
@@ -12287,12 +12287,12 @@ var init_credentials = __esm({
        * @param reason - What is wrong with it.
        * @param cause - Underlying parse error, if any.
        */
-      constructor(path31, reason, cause) {
+      constructor(path32, reason, cause) {
         super(
-          `Credentials file ${path31} is corrupt (${reason}). Fix it by hand, or delete it and run \`iamu auth login\` again.`,
+          `Credentials file ${path32} is corrupt (${reason}). Fix it by hand, or delete it and run \`iamu auth login\` again.`,
           {
             cause,
-            suggestedAction: `Delete ${path31} and run \`iamu auth login\`, or set IAMU_TOKEN.`
+            suggestedAction: `Delete ${path32} and run \`iamu auth login\`, or set IAMU_TOKEN.`
           }
         );
       }
@@ -13066,16 +13066,16 @@ async function needsWrite(filePath, content) {
     return true;
   }
 }
-function isCliWrittenSkill(path31) {
+function isCliWrittenSkill(path32) {
   try {
-    return /^generatedBy:/m.test(readFileSync3(path31, "utf-8"));
+    return /^generatedBy:/m.test(readFileSync3(path32, "utf-8"));
   } catch {
     return false;
   }
 }
-function isCliWrittenPrompt(path31) {
+function isCliWrittenPrompt(path32) {
   try {
-    const content = readFileSync3(path31, "utf-8");
+    const content = readFileSync3(path32, "utf-8");
     return content.includes("iamu") || /^generatedBy:/m.test(content);
   } catch {
     return false;
@@ -13087,8 +13087,8 @@ function planSkillFiles(hosts, projectRoot, version) {
   for (const host of hosts) {
     if (pluginProvidesSkills(host, projectRoot)) {
       for (const name of skillTemplates.keys()) {
-        const path31 = join4(host.getSkillsDir(projectRoot), name, "SKILL.md");
-        if (isCliWrittenSkill(path31)) files.push({ host, path: path31, content: null });
+        const path32 = join4(host.getSkillsDir(projectRoot), name, "SKILL.md");
+        if (isCliWrittenSkill(path32)) files.push({ host, path: path32, content: null });
       }
     } else if (host.supportsSkills) {
       const skillsDir = host.getSkillsDir(projectRoot);
@@ -19737,7 +19737,7 @@ async function crawlFrom(page, opts, origin, takeBlocked) {
   const byKey = /* @__PURE__ */ new Map();
   const byPlaceView = /* @__PURE__ */ new Map();
   const signatureOf = (s) => exploreSignature(s.headings, s.title);
-  function addSurface(state, place, view, path31, depth) {
+  function addSurface(state, place, view, path32, depth) {
     const key = exploreSurfaceKey(place, view);
     const surface = {
       key,
@@ -19749,7 +19749,7 @@ async function crawlFrom(page, opts, origin, takeBlocked) {
       headings: state.headings,
       fields: state.fields,
       depth,
-      path: path31,
+      path: path32,
       actions: []
     };
     surfaces.push(surface);
@@ -19767,9 +19767,9 @@ ${surface.signature}`, key);
     });
     await settle(page, settleMs);
   }
-  async function replay(path31) {
-    if (!("goto" in (path31[0] ?? {}))) await goto(opts.startUrl);
-    for (const step of path31) {
+  async function replay(path32) {
+    if (!("goto" in (path32[0] ?? {}))) await goto(opts.startUrl);
+    for (const step of path32) {
       if ("goto" in step) {
         await goto(step.goto);
       } else {
@@ -19893,8 +19893,8 @@ ${sig}`, key);
               if (stats.surfaces >= budget.max_surfaces) {
                 stats.truncated = true;
               } else {
-                const path31 = !sameDoc && view === null ? [{ goto: after.url }] : [...surface.path, ...via, click];
-                addSurface(after, place, view, path31, surface.depth + 1);
+                const path32 = !sameDoc && view === null ? [{ goto: after.url }] : [...surface.path, ...via, click];
+                addSurface(after, place, view, path32, surface.depth + 1);
               }
             }
           }
@@ -20769,15 +20769,15 @@ function composeWalkerPrompt(p) {
     "",
     `Run \`iamu\` as: ${iamu}   (from ${p.projectRoot})`,
     `Run directory: ${rd}`,
-    `Record steps atomically:`,
+    `Record steps atomically via CLI (do not hand-craft step JSON files or use host Write tools):`,
     `  \u2022 For iamu browse: ${iamu} browse step --run ${p.runId} --action "<action>" --note "<monologue>" <command> [args...]`,
     `  \u2022 For other surfaces: ${iamu} step --run ${p.runId} --action "<action>" --note "<monologue>" [--shot <path>]`,
-    `Record steps to: ${rd}/steps/NNN.json (one file per step, 001.json upward): step_number, timestamp (ISO), action, note (first-person, in the persona's language), screenshot ("screenshots/step-N.png"), url (the page you are on when the step ends, copied from the driving surface), surface (optional short screen name, e.g. "search results").`,
-    "Never hand-craft raw JSON step files with custom scripts; the CLI handles step numbering, screenshots, and telemetry automatically.",
+    "The CLI handles step numbering, timestamps, screenshot capture/linking, and telemetry automatically.",
     `Screenshots to: ${rd}/screenshots/step-N.png \u2014 absolute paths.`,
-    `Record findings with: ${iamu} new-finding --scenario ${p.scenarioSlug} --run ${p.runId} --step <N> --title "..." --type <helps|hinders|missing|irrelevant|incorrect> --severity <critical|major|minor|observation> --ui-fact "..." --consequence "..." --task-impact <blocks|impairs|slows|neutral|accelerates|enables> --confidence <high|medium|low> --json \u2014 then add the body (description + "## Recommendation") below the frontmatter of the file it returns.`,
+    `Record findings with: ${iamu} new-finding --scenario ${p.scenarioSlug} --run ${p.runId} --step <N> --title "..." --type <helps|hinders|missing|irrelevant|incorrect> --severity <critical|major|minor|observation> --ui-fact "..." --consequence "..." --task-impact <blocks|impairs|slows|neutral|accelerates|enables> --confidence <high|medium|low> --description "..." --recommendation "..." --json`,
     "`--step <N>` is the step whose screenshot shows the problem (or strength): it is the evidence people see next to the finding, so record that step and its screenshot first, and pick the screenshot where the thing is actually visible.",
-    `Before you finish, write ${rd}/summary.json: {"what_worked": [...], "open_questions": [...], "model": "<your model identifier if known, e.g. claude-3-5-haiku, gemini-3.8-flash, or unspecified>"} \u2014 one sentence each, in the persona's language.`,
+    `Before you finish, record synthesis with: ${iamu} summary ${p.runId} --worked "..." --worked "..." --question "..."`,
+    "Execute everything via CLI commands in the shell. Never invoke host Edit or Write tools on files in the workspace.",
     "",
     "Do not read the product's source code, other iamu/ entity files, or earlier runs: you know only what the persona knows.",
     "",
@@ -21188,11 +21188,14 @@ async function newFinding(opts) {
   if (opts.taskImpact) frontmatter.task_impact = opts.taskImpact;
   if (opts.confidence) frontmatter.confidence = opts.confidence;
   if (stepId) frontmatter.walkthrough_step_id = stepId;
-  const body = [
+  const desc = opts.description?.trim();
+  const rec = opts.recommendation?.trim();
+  const body = opts.body ?? [
+    desc ?? "",
     "",
     "## Recommendation",
     "",
-    "<!-- How should this be fixed? -->",
+    rec ?? "<!-- How should this be fixed? -->",
     ""
   ].join("\n");
   try {
@@ -21248,6 +21251,122 @@ var init_new_finding = __esm({
   }
 });
 
+// src/commands/summary.ts
+var summary_exports = {};
+__export(summary_exports, {
+  summaryCommand: () => summaryCommand
+});
+import { promises as fs29 } from "fs";
+import path28 from "path";
+import chalk30 from "chalk";
+async function summaryCommand(runIdArg, opts) {
+  const ctx = await resolveProject(opts);
+  if (!ctx) return;
+  const { projectRoot } = ctx;
+  const runId = runIdArg ?? opts.run;
+  if (!runId) {
+    commandError("Run ID is required. Pass as argument or via --run.", opts);
+    return;
+  }
+  const runDirPath = resolveRunDir(projectRoot, runId, opts);
+  if (!runDirPath) return;
+  let whatWorked = [];
+  let openQuestions = [];
+  let model = opts.model?.trim() || void 0;
+  if (opts.file) {
+    try {
+      let raw;
+      if (opts.file === "-") {
+        const chunks = [];
+        for await (const chunk of process.stdin) {
+          chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+        }
+        raw = Buffer.concat(chunks).toString("utf8");
+      } else {
+        raw = await fs29.readFile(path28.resolve(projectRoot, opts.file), "utf8");
+      }
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed.what_worked)) {
+        whatWorked = parsed.what_worked.filter(
+          (x) => typeof x === "string" && x.trim() !== ""
+        );
+      }
+      if (Array.isArray(parsed.open_questions)) {
+        openQuestions = parsed.open_questions.filter(
+          (x) => typeof x === "string" && x.trim() !== ""
+        );
+      }
+      if (typeof parsed.model === "string" && parsed.model.trim()) {
+        model = parsed.model.trim();
+      }
+    } catch (err) {
+      commandError(
+        `Failed to parse summary file: ${err instanceof Error ? err.message : String(err)}`,
+        opts
+      );
+      return;
+    }
+  }
+  const toList = (v) => {
+    if (!v) return [];
+    const arr = Array.isArray(v) ? v : [v];
+    return arr.map((s) => s.trim()).filter(Boolean);
+  };
+  const cliWorked = toList(opts.worked);
+  if (cliWorked.length > 0) {
+    whatWorked = [...whatWorked, ...cliWorked];
+  }
+  const cliQuestions = toList(opts.question);
+  if (cliQuestions.length > 0) {
+    openQuestions = [...openQuestions, ...cliQuestions];
+  }
+  const data = {
+    what_worked: whatWorked,
+    open_questions: openQuestions,
+    ...model ? { model } : {}
+  };
+  const summaryPath = path28.join(runDirPath, "summary.json");
+  await atomicWriteFile(summaryPath, `${JSON.stringify(data, null, 2)}
+`);
+  if (opts.json) {
+    console.log(
+      JSON.stringify(
+        {
+          run_id: runId,
+          path: path28.relative(projectRoot, summaryPath),
+          summary: data
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  console.log();
+  console.log(
+    `  ${symbols.success} Summary recorded for run ${chalk30.cyan(runId)}`
+  );
+  if (data.what_worked.length > 0) {
+    console.log(
+      `    ${chalk30.dim("what worked:")}   ${data.what_worked.length} item(s)`
+    );
+  }
+  if (data.open_questions.length > 0) {
+    console.log(
+      `    ${chalk30.dim("open questions:")} ${data.open_questions.length} item(s)`
+    );
+  }
+  console.log();
+}
+var init_summary = __esm({
+  "src/commands/summary.ts"() {
+    "use strict";
+    init_dist2();
+    init_symbols();
+    init_context4();
+  }
+});
+
 // src/commands/view-results.ts
 var view_results_exports = {};
 __export(view_results_exports, {
@@ -21255,7 +21374,7 @@ __export(view_results_exports, {
   promptViewResults: () => promptViewResults
 });
 import { isCancel as isCancel4, select as select4 } from "@clack/prompts";
-import chalk30 from "chalk";
+import chalk31 from "chalk";
 function launchCloudDashboard(config, runId) {
   const cloudRunId = runId ? toCloudRunUuid(runId) : void 0;
   const url = getCloudDashboardUrl(
@@ -21264,7 +21383,7 @@ function launchCloudDashboard(config, runId) {
     cloudRunId
   );
   console.log();
-  console.log(`  ${symbols.success} Opening Iamu Cloud: ${chalk30.cyan(url)}
+  console.log(`  ${symbols.success} Opening Iamu Cloud: ${chalk31.cyan(url)}
 `);
   openBrowser(url);
 }
@@ -21332,9 +21451,9 @@ __export(evaluate_exports, {
   evaluate: () => evaluate,
   evaluateRecord: () => evaluateRecord
 });
-import { promises as fs29 } from "fs";
-import path28 from "path";
-import chalk31 from "chalk";
+import { promises as fs30 } from "fs";
+import path29 from "path";
+import chalk32 from "chalk";
 import { z as z25 } from "zod";
 function formatIssues(error) {
   return error.issues.map(
@@ -21364,10 +21483,10 @@ async function evaluate(runId, opts) {
   const resolved = await resolveProjectAndRunDir(runId, opts);
   if (!resolved) return;
   const { projectRoot, runDirPath } = resolved;
-  const canonicalPath = path28.join(runDirPath, "canonical.json");
+  const canonicalPath = path29.join(runDirPath, "canonical.json");
   let canonical;
   try {
-    const raw = await fs29.readFile(canonicalPath, "utf8");
+    const raw = await fs30.readFile(canonicalPath, "utf8");
     canonical = JSON.parse(raw);
   } catch {
     commandError(
@@ -21423,15 +21542,15 @@ async function evaluate(runId, opts) {
     )
   };
   const prompt = composeJudgePrompt(input);
-  const promptFilePath = opts?.promptFile ?? path28.join(runDirPath, "judge_prompt.md");
-  await fs29.writeFile(promptFilePath, prompt, "utf8");
+  const promptFilePath = opts?.promptFile ?? path29.join(runDirPath, "judge_prompt.md");
+  await fs30.writeFile(promptFilePath, prompt, "utf8");
   if (opts?.json) {
     console.log(
       JSON.stringify(
         {
           ...input,
-          prompt_file: path28.relative(projectRoot, promptFilePath),
-          prompt_file_abs: path28.resolve(promptFilePath),
+          prompt_file: path29.relative(projectRoot, promptFilePath),
+          prompt_file_abs: path29.resolve(promptFilePath),
           judge_prompt: prompt
         },
         null,
@@ -21448,21 +21567,39 @@ async function evaluateRecord(runId, opts) {
   const { projectRoot, runDirPath } = resolved;
   sendLivePhase(projectRoot, runId, "judging").catch(() => {
   });
-  const canonicalPath = path28.join(runDirPath, "canonical.json");
+  const canonicalPath = path29.join(runDirPath, "canonical.json");
   let canonical;
   try {
-    const raw = await fs29.readFile(canonicalPath, "utf8");
+    const raw = await fs30.readFile(canonicalPath, "utf8");
     canonical = JSON.parse(raw);
   } catch {
     commandError(`No canonical.json for run: ${runId}`, opts);
     return;
   }
+  if (!opts.file && !opts.data) {
+    commandError("Either --file <path> or --data <json> is required", opts);
+    return;
+  }
   let parsedFile;
   try {
-    const raw = await fs29.readFile(opts.file, "utf8");
+    let raw;
+    if (opts.data) {
+      raw = opts.data;
+    } else if (opts.file === "-") {
+      const chunks = [];
+      for await (const chunk of process.stdin) {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+      }
+      raw = Buffer.concat(chunks).toString("utf8");
+    } else {
+      raw = await fs30.readFile(opts.file, "utf8");
+    }
     parsedFile = JSON.parse(raw);
-  } catch {
-    commandError(`Cannot read verdicts file: ${opts.file}`, opts);
+  } catch (err) {
+    commandError(
+      `Cannot read verdicts: ${err instanceof Error ? err.message : String(err)}`,
+      opts
+    );
     return;
   }
   const fileResult = verdictsFileSchema.safeParse(parsedFile);
@@ -21516,8 +21653,8 @@ ${formatIssues(fileResult.error)}`,
     overall: inputVerdicts.overall
   });
   const reportContent = renderCanonicalMarkdown(canonicalForReport);
-  const verdictsPath = path28.join(runDirPath, "verdicts.json");
-  const reportPath = path28.join(runDirPath, "report.md");
+  const verdictsPath = path29.join(runDirPath, "verdicts.json");
+  const reportPath = path29.join(runDirPath, "report.md");
   await Promise.all([
     atomicWriteFile(
       verdictsPath,
@@ -21537,8 +21674,8 @@ ${formatIssues(fileResult.error)}`,
       JSON.stringify(
         {
           runId,
-          verdictsPath: path28.relative(projectRoot, verdictsPath),
-          reportPath: path28.relative(projectRoot, reportPath),
+          verdictsPath: path29.relative(projectRoot, verdictsPath),
+          reportPath: path29.relative(projectRoot, reportPath),
           verdictsCount: validatedVerdicts.length,
           linkedCount: linked.length,
           ...cloudInfo ? { cloud: cloudInfo } : {}
@@ -21551,18 +21688,18 @@ ${formatIssues(fileResult.error)}`,
   }
   console.log();
   console.log(
-    `  ${symbols.success} Recorded ${validatedVerdicts.length} verdicts for run ${chalk31.cyan(runId)}`
+    `  ${symbols.success} Recorded ${validatedVerdicts.length} verdicts for run ${chalk32.cyan(runId)}`
   );
   if (linked.length > 0) {
     console.log(
-      `  ${chalk31.dim("linked:")}  ${linked.length} finding${linked.length === 1 ? "" : "s"} to the human test${linked.length === 1 ? "" : "s"} citing ${linked.length === 1 ? "it" : "them"}`
+      `  ${chalk32.dim("linked:")}  ${linked.length} finding${linked.length === 1 ? "" : "s"} to the human test${linked.length === 1 ? "" : "s"} citing ${linked.length === 1 ? "it" : "them"}`
     );
   }
   console.log(
-    `  ${chalk31.dim("verdicts:")} ${path28.relative(projectRoot, verdictsPath)}`
+    `  ${chalk32.dim("verdicts:")} ${path29.relative(projectRoot, verdictsPath)}`
   );
   console.log(
-    `  ${chalk31.dim("report:")}  ${path28.relative(projectRoot, reportPath)}`
+    `  ${chalk32.dim("report:")}  ${path29.relative(projectRoot, reportPath)}`
   );
   printCloudRunInfo(cloudInfo);
   await promptViewResults(projectRoot, { ...opts, runId });
@@ -21627,9 +21764,9 @@ __export(complete_exports, {
   screenshotSizeWarning: () => screenshotSizeWarning,
   validateCanonicalWalkthrough: () => validateCanonicalWalkthrough
 });
-import { promises as fs30 } from "fs";
-import path29 from "path";
-import chalk32 from "chalk";
+import { promises as fs31 } from "fs";
+import path30 from "path";
+import chalk33 from "chalk";
 async function complete(runId, opts) {
   const run = await loadRun(runId, opts);
   if (!run) return;
@@ -21641,7 +21778,7 @@ async function complete(runId, opts) {
   }
   if (!opts?.json) {
     console.log();
-    console.log(chalk32.bold("  Assembling canonical JSON\u2026"));
+    console.log(chalk33.bold("  Assembling canonical JSON\u2026"));
   }
   const provenanceAudit = auditStepProvenance(
     await readStepsForRun(run.projectRoot, runId)
@@ -21654,8 +21791,8 @@ async function complete(runId, opts) {
   const walkerSummary = await readWalkerSummary(run.runDirPath);
   let judgeReported;
   try {
-    const verdictsRaw = await fs30.readFile(
-      path29.join(run.runDirPath, "verdicts.json"),
+    const verdictsRaw = await fs31.readFile(
+      path30.join(run.runDirPath, "verdicts.json"),
       "utf8"
     );
     const parsed = JSON.parse(verdictsRaw);
@@ -21707,16 +21844,16 @@ async function loadRun(runId, opts) {
   if (!resolved) return null;
   const { projectRoot, runDirPath } = resolved;
   try {
-    await fs30.access(runDirPath);
+    await fs31.access(runDirPath);
   } catch {
     commandError(`Run not found: ${runId}`, opts);
     return null;
   }
-  const manifestPath = path29.join(runDirPath, "walkthrough.json");
+  const manifestPath = path30.join(runDirPath, "walkthrough.json");
   let manifest;
   try {
     manifest = JSON.parse(
-      await fs30.readFile(manifestPath, "utf8")
+      await fs31.readFile(manifestPath, "utf8")
     );
   } catch {
     commandError(`No walkthrough.json found for run: ${runId}`, opts);
@@ -21728,8 +21865,8 @@ async function reportAlreadyCompleted(run, opts) {
   const { runId, manifest } = run;
   if (opts?.json) {
     try {
-      const raw = await fs30.readFile(
-        path29.join(run.runDirPath, "canonical.json"),
+      const raw = await fs31.readFile(
+        path30.join(run.runDirPath, "canonical.json"),
         "utf8"
       );
       console.log(raw.trim());
@@ -21749,18 +21886,18 @@ async function reportAlreadyCompleted(run, opts) {
     return;
   }
   console.log();
-  console.log(chalk32.bold("  Run: ") + chalk32.cyan(runId));
-  console.log(`  status     ${chalk32.green("completed")}`);
+  console.log(chalk33.bold("  Run: ") + chalk33.cyan(runId));
+  console.log(`  status     ${chalk33.green("completed")}`);
   if (manifest.completed_at) {
-    console.log(`  completed  ${chalk32.dim(manifest.completed_at)}`);
+    console.log(`  completed  ${chalk33.dim(manifest.completed_at)}`);
   }
   const viewUrl = await pushedRunUrl(run.projectRoot, runId);
   if (viewUrl) {
-    console.log(`  view       ${chalk32.underline(viewUrl)}`);
+    console.log(`  view       ${chalk33.underline(viewUrl)}`);
   }
   console.log();
   console.log(
-    chalk32.dim(
+    chalk33.dim(
       "  Already completed \u2014 nothing to do. Use --force to reassemble the report."
     )
   );
@@ -21776,13 +21913,13 @@ function reportStrictProvenanceFailure(audit, opts) {
   }
   console.error();
   console.error(
-    chalk32.red(`  ${symbols.error} Strict provenance audit failed:`)
+    chalk33.red(`  ${symbols.error} Strict provenance audit failed:`)
   );
   for (const w of audit.warnings) {
-    console.error(chalk32.red(`    \u2022 ${w}`));
+    console.error(chalk33.red(`    \u2022 ${w}`));
   }
   console.error(
-    chalk32.dim(
+    chalk33.dim(
       "  Run was flagged as synthetic / scripted. Remove --strict-provenance to complete anyway."
     )
   );
@@ -21823,41 +21960,41 @@ function completeJsonPayload(canonical, extras) {
 function printCompletionSummary(run, completedAt, assembled, extras, provenanceAudit) {
   const { runId, projectRoot, manifest } = run;
   const { canonical } = assembled;
-  const count = (n) => n === 0 ? chalk32.dim("0") : chalk32.cyan(String(n));
-  console.log(chalk32.bold("  Run: ") + chalk32.cyan(runId));
-  console.log(`  scenario   ${chalk32.dim(manifest.scenario_slug)}`);
-  console.log(`  url        ${chalk32.dim(manifest.target_url)}`);
+  const count = (n) => n === 0 ? chalk33.dim("0") : chalk33.cyan(String(n));
+  console.log(chalk33.bold("  Run: ") + chalk33.cyan(runId));
+  console.log(`  scenario   ${chalk33.dim(manifest.scenario_slug)}`);
+  console.log(`  url        ${chalk33.dim(manifest.target_url)}`);
   if (manifest.environment) {
-    console.log(`  env        ${chalk32.dim(manifest.environment)}`);
+    console.log(`  env        ${chalk33.dim(manifest.environment)}`);
   }
   if (manifest.build) {
-    console.log(`  build      ${chalk32.dim(formatBuild(manifest.build))}`);
+    console.log(`  build      ${chalk33.dim(formatBuild(manifest.build))}`);
   }
   if (manifest.viewport) {
-    console.log(`  device     ${chalk32.dim(formatViewport(manifest.viewport))}`);
+    console.log(`  device     ${chalk33.dim(formatViewport(manifest.viewport))}`);
   }
-  console.log(`  status     ${chalk32.green("completed")}`);
+  console.log(`  status     ${chalk33.green("completed")}`);
   console.log(`  findings   ${count(canonical.findings.length)}`);
   console.log(`  steps      ${count(canonical.steps.length)}`);
-  console.log(`  started    ${chalk32.dim(manifest.created_at)}`);
-  console.log(`  completed  ${chalk32.dim(completedAt)}`);
+  console.log(`  started    ${chalk33.dim(manifest.created_at)}`);
+  console.log(`  completed  ${chalk33.dim(completedAt)}`);
   const models = manifest.models;
   if (models?.velocity_sec_per_step != null) {
     console.log(
-      `  velocity   ${chalk32.cyan(`~${models.velocity_sec_per_step}s/step`)} ${chalk32.dim(`(${models.total_duration_sec}s total)`)}`
+      `  velocity   ${chalk33.cyan(`~${models.velocity_sec_per_step}s/step`)} ${chalk33.dim(`(${models.total_duration_sec}s total)`)}`
     );
   }
   if (models && (models.walker || models.judge || models.matcher)) {
     const w = models.walker_reported ? `${models.walker} (${models.walker_reported})` : models.walker ?? "fast";
     const j = models.judge_reported ? `${models.judge} (${models.judge_reported})` : models.judge ?? "thorough";
-    console.log(`  models     ${chalk32.dim(`walker: ${w} \xB7 judge: ${j}`)}`);
+    console.log(`  models     ${chalk33.dim(`walker: ${w} \xB7 judge: ${j}`)}`);
   }
   console.log();
   console.log(
-    `  ${chalk32.dim("canonical:")} ${chalk32.dim(path29.relative(projectRoot, assembled.canonicalPath))}`
+    `  ${chalk33.dim("canonical:")} ${chalk33.dim(path30.relative(projectRoot, assembled.canonicalPath))}`
   );
   console.log(
-    `  ${chalk32.dim("report:")}    ${chalk32.dim(path29.relative(projectRoot, assembled.reportPath))}`
+    `  ${chalk33.dim("report:")}    ${chalk33.dim(path30.relative(projectRoot, assembled.reportPath))}`
   );
   if (extras.viewportWarning) {
     console.log();
@@ -21865,7 +22002,7 @@ function printCompletionSummary(run, completedAt, assembled, extras, provenanceA
   }
   if (extras.codeWarning) {
     console.log();
-    console.log(`  ${chalk32.yellow("!")} ${extras.codeWarning}`);
+    console.log(`  ${chalk33.yellow("!")} ${extras.codeWarning}`);
   }
   if (extras.revisit) printRevisit(extras.revisit);
   if (assembled.verification) printVerification(assembled.verification);
@@ -21877,13 +22014,13 @@ function printProvenanceWarnings(audit) {
   if (audit.warnings.length === 0) return;
   console.log();
   console.log(
-    `  ${symbols.warning} ${chalk32.yellow("Step provenance audit flagged suspicious timing:")}`
+    `  ${symbols.warning} ${chalk33.yellow("Step provenance audit flagged suspicious timing:")}`
   );
   for (const w of audit.warnings) {
-    console.log(`    ${chalk32.dim("\u2022")} ${w}`);
+    console.log(`    ${chalk33.dim("\u2022")} ${w}`);
   }
   console.log(
-    chalk32.dim(
+    chalk33.dim(
       "    Run appears to be programmatically batch-generated rather than an interactive walkthrough."
     )
   );
@@ -21915,17 +22052,17 @@ function screenshotFitsViewport(width, expected) {
 }
 async function screenshotSizeWarning(runDirPath, viewport) {
   if (!viewport) return null;
-  const dir = path29.join(runDirPath, "screenshots");
+  const dir = path30.join(runDirPath, "screenshots");
   let first;
   try {
-    first = (await fs30.readdir(dir)).filter((f) => f.toLowerCase().endsWith(".png")).sort((a, b) => a.localeCompare(b, void 0, { numeric: true }))[0];
+    first = (await fs31.readdir(dir)).filter((f) => f.toLowerCase().endsWith(".png")).sort((a, b) => a.localeCompare(b, void 0, { numeric: true }))[0];
   } catch {
     return null;
   }
   if (!first) return null;
   let size = null;
   try {
-    const handle = await fs30.open(path29.join(dir, first), "r");
+    const handle = await fs31.open(path30.join(dir, first), "r");
     try {
       const head = Buffer.alloc(24);
       const { bytesRead } = await handle.read(head, 0, 24, 0);
@@ -21942,7 +22079,7 @@ async function screenshotSizeWarning(runDirPath, viewport) {
 async function readWalkerSummary(runDirPath) {
   try {
     const data = JSON.parse(
-      await fs30.readFile(path29.join(runDirPath, "summary.json"), "utf8")
+      await fs31.readFile(path30.join(runDirPath, "summary.json"), "utf8")
     );
     const strings = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string" && x.trim() !== "") : void 0;
     const model = typeof data.model === "string" && data.model.trim() !== "" ? data.model.trim() : void 0;
@@ -22051,7 +22188,7 @@ function validateCanonicalWalkthrough(canonical) {
 async function applyRecordedVerdicts(canonical, runDirPath) {
   try {
     const recorded = JSON.parse(
-      await fs30.readFile(path29.join(runDirPath, "verdicts.json"), "utf8")
+      await fs31.readFile(path30.join(runDirPath, "verdicts.json"), "utf8")
     );
     if (Array.isArray(recorded.verdicts)) {
       return applyVerdicts(canonical, recorded);
@@ -22061,7 +22198,7 @@ async function applyRecordedVerdicts(canonical, runDirPath) {
   return canonical;
 }
 async function persistCanonical(runDirPath, canonical) {
-  const canonicalPath = path29.join(runDirPath, "canonical.json");
+  const canonicalPath = path30.join(runDirPath, "canonical.json");
   await atomicWriteFile(
     canonicalPath,
     `${JSON.stringify(canonical, null, 2)}
@@ -22070,7 +22207,7 @@ async function persistCanonical(runDirPath, canonical) {
   return canonicalPath;
 }
 async function persistReport(runDirPath, canonical) {
-  const reportPath = path29.join(runDirPath, "report.md");
+  const reportPath = path30.join(runDirPath, "report.md");
   await atomicWriteFile(reportPath, renderCanonicalMarkdown(canonical));
   return reportPath;
 }
@@ -22170,17 +22307,17 @@ function placeLabel(p) {
 function printRevisit(r) {
   const missed = r.places.filter((p) => !p.reached);
   console.log();
-  const head = `  ${chalk32.bold("Re-check places:")} reached ${r.reached} of ${r.requested}`;
+  const head = `  ${chalk33.bold("Re-check places:")} reached ${r.reached} of ${r.requested}`;
   if (missed.length === 0) {
-    console.log(`${head} ${chalk32.green("\u2713")}`);
+    console.log(`${head} ${chalk33.green("\u2713")}`);
     return;
   }
   console.log(`${head} \u2014 not reached:`);
   for (const p of missed) {
-    console.log(`    ${chalk32.yellow("\u25CB")} ${placeLabel(p)}`);
+    console.log(`    ${chalk33.yellow("\u25CB")} ${placeLabel(p)}`);
   }
   console.log(
-    chalk32.dim(
+    chalk33.dim(
       "    Fixes there stay awaiting a re-run until a walk gets there."
     )
   );
@@ -22188,7 +22325,7 @@ function printRevisit(r) {
 function printVerification(verification) {
   console.log();
   console.log(
-    chalk32.bold("  Since this scenario's last run") + chalk32.dim(` (${verification.baseline_run_id.slice(0, 30)}\u2026)`) + chalk32.bold(":")
+    chalk33.bold("  Since this scenario's last run") + chalk33.dim(` (${verification.baseline_run_id.slice(0, 30)}\u2026)`) + chalk33.bold(":")
   );
   if (verification.resolved.length > 0) {
     console.log(
@@ -22197,7 +22334,7 @@ function printVerification(verification) {
   }
   if (verification.not_observed.length > 0) {
     console.log(
-      `    ${symbols.pending} ${verification.not_observed.length} not seen this run ${chalk32.dim("(not evidence of a fix)")}`
+      `    ${symbols.pending} ${verification.not_observed.length} not seen this run ${chalk33.dim("(not evidence of a fix)")}`
     );
   }
   if (verification.persists.length > 0) {
@@ -22239,14 +22376,14 @@ __export(match_exports, {
   match: () => match,
   matchRecord: () => matchRecord
 });
-import { promises as fs31 } from "fs";
-import path30 from "path";
-import chalk33 from "chalk";
+import { promises as fs32 } from "fs";
+import path31 from "path";
+import chalk34 from "chalk";
 async function completedManifest2(runDirPath, runId, opts) {
   let manifest;
   try {
     manifest = JSON.parse(
-      await fs31.readFile(path30.join(runDirPath, "walkthrough.json"), "utf8")
+      await fs32.readFile(path31.join(runDirPath, "walkthrough.json"), "utf8")
     );
   } catch {
     commandError(`Run not found: ${runId}`, opts);
@@ -22275,12 +22412,12 @@ async function match(runId, opts) {
   );
   const needed = input.current.length > 0 && (input.prior.length > 0 || (input.guidance ?? []).length > 0);
   const prompt = needed ? composeMatchPrompt(input) : null;
-  const promptFilePath = opts?.promptFile ?? path30.join(runDirPath, "match_prompt.md");
+  const promptFilePath = opts?.promptFile ?? path31.join(runDirPath, "match_prompt.md");
   if (prompt) {
-    await fs31.writeFile(promptFilePath, prompt, "utf8");
+    await fs32.writeFile(promptFilePath, prompt, "utf8");
   } else {
     try {
-      await fs31.unlink(promptFilePath);
+      await fs32.unlink(promptFilePath);
     } catch {
     }
   }
@@ -22290,8 +22427,8 @@ async function match(runId, opts) {
         {
           ...input,
           needed,
-          prompt_file: prompt ? path30.relative(ctx.projectRoot, promptFilePath) : null,
-          prompt_file_abs: prompt ? path30.resolve(promptFilePath) : null,
+          prompt_file: prompt ? path31.relative(ctx.projectRoot, promptFilePath) : null,
+          prompt_file_abs: prompt ? path31.resolve(promptFilePath) : null,
           match_prompt: prompt
         },
         null,
@@ -22302,7 +22439,7 @@ async function match(runId, opts) {
   }
   if (!prompt) {
     console.log(
-      chalk33.dim(
+      chalk34.dim(
         "  No earlier findings or tester guidance for this scenario to match against \u2014 nothing to do."
       )
     );
@@ -22318,11 +22455,30 @@ async function matchRecord(runId, opts) {
   });
   const manifest = await completedManifest2(runDirPath, runId, opts);
   if (!manifest) return;
+  if (!opts.file && !opts.data) {
+    commandError("Either --file <path> or --data <json> is required", opts);
+    return;
+  }
   let answer;
   try {
-    answer = JSON.parse(await fs31.readFile(opts.file, "utf8"));
-  } catch {
-    commandError(`Cannot read matches file: ${opts.file}`, opts);
+    let raw;
+    if (opts.data) {
+      raw = opts.data;
+    } else if (opts.file === "-") {
+      const chunks = [];
+      for await (const chunk of process.stdin) {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+      }
+      raw = Buffer.concat(chunks).toString("utf8");
+    } else {
+      raw = await fs32.readFile(opts.file, "utf8");
+    }
+    answer = JSON.parse(raw);
+  } catch (err) {
+    commandError(
+      `Cannot read matches: ${err instanceof Error ? err.message : String(err)}`,
+      opts
+    );
     return;
   }
   let result;
@@ -22361,17 +22517,17 @@ async function matchRecord(runId, opts) {
   }
   console.log();
   console.log(
-    `  ${chalk33.green("\u2713")} Matched ${result.linked} finding${result.linked === 1 ? "" : "s"} to earlier ones, ${result.new} first seen, ${result.rechecked_fixed} earlier re-checked fixed`
+    `  ${chalk34.green("\u2713")} Matched ${result.linked} finding${result.linked === 1 ? "" : "s"} to earlier ones, ${result.new} first seen, ${result.rechecked_fixed} earlier re-checked fixed`
   );
   if (result.suppressed > 0) {
     console.log(
-      `  ${chalk33.yellow("!")} ${result.suppressed} finding${result.suppressed === 1 ? "" : "s"} match tester guidance (flagged with suppressed_by_guidance \u2014 dismiss them in triage if the rule holds)`
+      `  ${chalk34.yellow("!")} ${result.suppressed} finding${result.suppressed === 1 ? "" : "s"} match tester guidance (flagged with suppressed_by_guidance \u2014 dismiss them in triage if the rule holds)`
     );
   }
   if (verification) printVerification(verification);
   console.log();
   console.log(
-    chalk33.dim("  Run `iamu sync` to push the linked findings to the cloud.")
+    chalk34.dim("  Run `iamu sync` to push the linked findings to the cloud.")
   );
   console.log();
 }
@@ -22393,7 +22549,7 @@ __export(prune_exports, {
   prune: () => prune
 });
 import { confirm, isCancel as isCancel5 } from "@clack/prompts";
-import chalk34 from "chalk";
+import chalk35 from "chalk";
 function formatBytes(bytes) {
   if (bytes <= 0) return "0 B";
   if (bytes < 1024) return `${bytes} B`;
@@ -22439,7 +22595,7 @@ async function prune(opts = {}) {
     });
     if (preview.prunedRuns.length === 0) {
       console.log(
-        chalk34.dim("  No runs match the pruning criteria. Nothing to prune.")
+        chalk35.dim("  No runs match the pruning criteria. Nothing to prune.")
       );
       return preview;
     }
@@ -22448,7 +22604,7 @@ async function prune(opts = {}) {
       message: `Prune ${mode} ${preview.prunedRuns.length} run(s) and reclaim ${formatBytes(preview.totalBytesReclaimed)}?`
     });
     if (isCancel5(confirmed) || !confirmed) {
-      console.log(chalk34.yellow("  Pruning cancelled."));
+      console.log(chalk35.yellow("  Pruning cancelled."));
       return;
     }
   }
@@ -22459,14 +22615,14 @@ async function prune(opts = {}) {
   }
   if (result.dryRun) {
     console.log(
-      chalk34.cyan(
+      chalk35.cyan(
         `
   [DRY RUN] Would prune ${result.prunedRuns.length} of ${result.totalRunsScanned} run(s):`
       )
     );
   } else {
     console.log(
-      chalk34.bold(
+      chalk35.bold(
         `
   ${symbols.success} Pruned ${result.prunedRuns.length} of ${result.totalRunsScanned} run(s):`
       )
@@ -22474,18 +22630,18 @@ async function prune(opts = {}) {
   }
   if (result.prunedRuns.length === 0) {
     console.log(
-      chalk34.dim("    No runs matched the pruning criteria. Nothing pruned.")
+      chalk35.dim("    No runs matched the pruning criteria. Nothing pruned.")
     );
   } else {
     for (const run of result.prunedRuns) {
       const mode = run.fullyDeleted ? "removed" : "screenshots purged";
       const count = run.screenshotsDeleted > 0 ? `${run.screenshotsDeleted} screenshots, ` : "";
       console.log(
-        `    ${chalk34.dim("\u2022")} ${chalk34.bold(run.runId)} ${chalk34.dim(`(${run.scenarioSlug ?? "unknown scenario"})`)}: ${chalk34.yellow(formatBytes(run.bytesReclaimed))} (${count}${mode})`
+        `    ${chalk35.dim("\u2022")} ${chalk35.bold(run.runId)} ${chalk35.dim(`(${run.scenarioSlug ?? "unknown scenario"})`)}: ${chalk35.yellow(formatBytes(run.bytesReclaimed))} (${count}${mode})`
       );
     }
     console.log(
-      chalk34.dim(
+      chalk35.dim(
         `
   Total reclaimed: ${formatBytes(result.totalBytesReclaimed)} (${result.totalScreenshotsDeleted} screenshots deleted)
 `
@@ -22674,9 +22830,9 @@ function registerProjectCommands(program) {
     "after",
     "\nExamples:\n  $ iamu validate --all\n  $ iamu validate --all --fix --dry-run\n  $ iamu validate iamu/personas/maria.md"
   ).action(
-    async (path31, opts) => {
+    async (path32, opts) => {
       const { validate: validate2 } = await Promise.resolve().then(() => (init_validate(), validate_exports));
-      await validate2(path31, opts);
+      await validate2(path32, opts);
     }
   );
   program.command("update").helpGroup("Project:").description("Update and repair agent skills and prompts to latest version").option(
@@ -22901,6 +23057,15 @@ function registerWalkthroughCommands(program) {
   ).option(
     "--step <n>",
     "Step whose screenshot shows the finding \u2014 its evidence (step must be recorded first)"
+  ).option(
+    "--description <text>",
+    "Finding narrative description below frontmatter"
+  ).option(
+    "--recommendation <text>",
+    "Concrete recommendation for how to fix or address the finding"
+  ).option(
+    "--body <markdown>",
+    "Complete markdown body (overrides --description and --recommendation)"
   ).option("--json", "Output as JSON").addHelpText(
     "after",
     '\nExamples:\n  $ iamu new-finding run-123 --title "Submit fails" --type hinders --severity critical\n  $ iamu new-finding --run run-123 --scenario login --title "Submit fails" --type hinders --severity critical'
@@ -22911,6 +23076,20 @@ function registerWalkthroughCommands(program) {
       await newFinding2({ ...opts, run });
     }
   );
+  program.command("summary [run-id]").helpGroup("Walkthrough:").description(
+    "Record walker summary (what worked, open questions) atomically"
+  ).option("--run <run-id>", "Run ID (or pass as positional argument)").option(
+    "--worked <note...>",
+    "Things that worked well (can be specified multiple times)"
+  ).option(
+    "--question <note...>",
+    "Open questions that arose (can be specified multiple times)"
+  ).option("--model <name>", "Model identifier (e.g. flash, haiku)").option("--file <path>", "Path to summary JSON file (or - for stdin)").option("--json", "Output as JSON").action(
+    async (runIdArg, opts) => {
+      const { summaryCommand: summaryCommand2 } = await Promise.resolve().then(() => (init_summary(), summary_exports));
+      await summaryCommand2(runIdArg, opts);
+    }
+  );
   program.command("complete <run-id>").helpGroup("Walkthrough:").description("Assemble canonical JSON + report from a walkthrough run").option("--json", "Output canonical JSON to stdout").option(
     "--force",
     "Reassemble canonical.json and report.md for an already completed run"
@@ -22936,17 +23115,19 @@ function registerWalkthroughCommands(program) {
   );
   program.command("match-record <run-id>").helpGroup("Walkthrough:").description(
     "Record finding matches and re-derive the run's since-last-run delta"
-  ).requiredOption("--file <path>", "Path to matches JSON file").option("--json", "Output match results as JSON").action(async (runId, opts) => {
-    const { matchRecord: matchRecord2 } = await Promise.resolve().then(() => (init_match(), match_exports));
-    await matchRecord2(runId, opts);
-  });
+  ).option("--file <path>", "Path to matches JSON file (or - for stdin)").option("--data <json>", "Inline matches JSON string").option("--json", "Output match results as JSON").action(
+    async (runId, opts) => {
+      const { matchRecord: matchRecord2 } = await Promise.resolve().then(() => (init_match(), match_exports));
+      await matchRecord2(runId, opts);
+    }
+  );
   program.command("evaluate <run-id>").helpGroup("Walkthrough:").description("Compose evaluation prompt for human-test questions").option("--json", "Output evaluation input bundle as JSON").option("--prompt-file <path>", "Write the generated prompt to a file").action(
     async (runId, opts) => {
       const { evaluate: evaluate2 } = await Promise.resolve().then(() => (init_evaluate(), evaluate_exports));
       await evaluate2(runId, opts);
     }
   );
-  program.command("evaluate-record <run-id>").helpGroup("Walkthrough:").description("Record evaluation verdicts into the run's verdicts.json").requiredOption("--file <path>", "Path to verdicts JSON file").option("--json", "Output summary as JSON").option("-y, --yes", "Skip interactive prompts").option("--no-prompt", "Skip interactive prompt to view results").option("--no-push", "Skip pushing the updated run to Iamu Cloud").option("--view", "Open results in browser immediately without prompt").addHelpText(
+  program.command("evaluate-record <run-id>").helpGroup("Walkthrough:").description("Record evaluation verdicts into the run's verdicts.json").option("--file <path>", "Path to verdicts JSON file (or - for stdin)").option("--data <json>", "Inline verdicts JSON string").option("--json", "Output summary as JSON").option("-y, --yes", "Skip interactive prompts").option("--no-prompt", "Skip interactive prompt to view results").option("--no-push", "Skip pushing the updated run to Iamu Cloud").option("--view", "Open results in browser immediately without prompt").addHelpText(
     "after",
     "\nExamples:\n  $ iamu evaluate-record <run-id> --file verdicts.json\n  $ iamu evaluate-record <run-id> --file verdicts.json --no-prompt\n  $ iamu evaluate-record <run-id> --file verdicts.json --no-push\n  $ iamu evaluate-record <run-id> --file verdicts.json --json"
   ).action(
@@ -22977,7 +23158,7 @@ function registerAllCommands(program) {
 
 // src/ui/panic.ts
 init_logger();
-import chalk35 from "chalk";
+import chalk36 from "chalk";
 var handlersRegistered = false;
 var customSigintHandler = null;
 function registerSigintCleanup(handler) {
@@ -22989,17 +23170,17 @@ function registerSigintCleanup(handler) {
 function logFatalAndExit(title, errOrReason) {
   process.stderr.write("\x1B[?25h");
   if (isVerbose()) {
-    console.error(chalk35.red(`
+    console.error(chalk36.red(`
   ${title}:`));
     console.error(
       errOrReason instanceof Error ? errOrReason.stack || errOrReason : errOrReason
     );
   } else {
     const msg = errOrReason instanceof Error ? errOrReason.message : String(errOrReason);
-    console.error(chalk35.red(`
+    console.error(chalk36.red(`
   Fatal Error: ${msg}`));
     console.error(
-      chalk35.dim(
+      chalk36.dim(
         "  Run with --verbose or DEBUG=1 to view the full stack trace.\n"
       )
     );
@@ -23018,7 +23199,7 @@ function setupProcessHandlers() {
       }
       process.exit(130);
     } else {
-      console.error(chalk35.dim("\n  Operation cancelled."));
+      console.error(chalk36.dim("\n  Operation cancelled."));
       process.exit(130);
     }
   });