@iamu-dev/iamu 0.2.0-beta.3 → 0.2.0-beta.5

package/dist/bin.js

@@ -11896,7 +11896,7 @@ var init_credentials = __esm({
     "use strict";
     init_dist2();
     init_dist();
-    DEFAULT_API_URL = "https://api.iamu.dev";
+    DEFAULT_API_URL = "https://app.iamu.dev";
     CredentialsFileError = class extends IamuConfigError {
       /**
        * @param path - The unreadable credentials file.
@@ -11993,7 +11993,7 @@ async function resolveCloudProject(opts) {
     commandError("Not cloud-linked. Run `iamu auth login` to connect.", opts);
     return null;
   }
-  const apiUrl = ctx.config.cloud_api_url ?? "https://api.iamu.dev";
+  const apiUrl = ctx.config.cloud_api_url ?? DEFAULT_API_URL;
   try {
     assertSecureApiUrl(apiUrl, "cloud_api_url");
   } catch (err) {
@@ -13502,12 +13502,24 @@ async function browserLogin(apiUrl, opts, t) {
       chalk8.red(`
   Auth session expired or failed (HTTP ${result.status}).`)
     );
+    console.error(
+      chalk8.dim("  Re-run `iamu auth login` to start a new login session.\n")
+    );
     process.exitCode = 1;
     return null;
   }
   if (result.kind === "timeout") {
     s.stop("Authentication timed out.");
-    console.error(chalk8.red("\n  Authentication timed out. Try again."));
+    console.error(
+      chalk8.red(
+        "\n  Authentication timed out (no approval received within 2 minutes)."
+      )
+    );
+    console.error(
+      chalk8.dim(
+        "  \u2022 Complete browser authorization faster, or authenticate non-interactively with --token <key>.\n  \u2022 Local setup is unaffected \u2014 re-run `iamu auth login` anytime.\n"
+      )
+    );
     process.exitCode = 1;
     return null;
   }
@@ -13533,7 +13545,12 @@ async function startAuthSession(apiUrl, timeoutMs) {
     if (!res.ok) {
       console.error(
         chalk8.red(
-          `  Failed to start auth session: ${res.text || `HTTP ${res.status}`}`
+          `  Failed to start auth session at ${apiUrl}: ${res.text || `HTTP ${res.status}`}`
+        )
+      );
+      console.error(
+        chalk8.dim(
+          "  \u2022 The cloud service may be experiencing downtime or maintenance.\n  \u2022 Local setup is unaffected; continue with local workflows or retry later with `iamu auth login`.\n"
         )
       );
       process.exitCode = 1;
@@ -13547,7 +13564,13 @@ async function startAuthSession(apiUrl, timeoutMs) {
     return { sessionId: data.sessionId, loginUrl: data.loginUrl };
   } catch (err) {
     console.error(
-      chalk8.red("  Cannot reach Iamu Cloud.") + chalk8.dim(` (${errorMessage(err)})`)
+      chalk8.red(`  Cannot reach Iamu Cloud (${apiUrl}).`) + chalk8.dim(`
+  Reason: ${errorMessage(err)}`)
+    );
+    console.error(
+      chalk8.dim(
+        "\n  \u2022 Check your internet connection or proxy settings.\n  \u2022 If using a custom instance, pass --url <api-url> or set IAMU_API_URL.\n  \u2022 Local setup is unaffected; continue with local workflows or retry later with `iamu auth login`.\n"
+      )
     );
     process.exitCode = 1;
     return null;
@@ -16978,6 +17001,35 @@ function printStep(opts, record, projectRoot) {
   }
 }
 async function browseStep(args, opts, driver) {
+  if (opts.stepFile) {
+    try {
+      let raw;
+      if (opts.stepFile === "-") {
+        raw = readFileSync6(0, "utf8");
+      } else {
+        raw = readFileSync6(opts.stepFile, "utf8");
+      }
+      const data = JSON.parse(raw);
+      if (data.run && typeof data.run === "string") opts.run = data.run;
+      if (data.action && typeof data.action === "string")
+        opts.action = data.action;
+      if (data.note && typeof data.note === "string") opts.note = data.note;
+      if (data.surface && typeof data.surface === "string")
+        opts.surface = data.surface;
+      if (args.length === 0 && data.cmd) {
+        if (Array.isArray(data.cmd)) {
+          args = data.cmd.map(String);
+        } else if (typeof data.cmd === "string") {
+          args = data.cmd.trim().split(/\s+/);
+        }
+      }
+    } catch (err) {
+      return fail(
+        `Failed to read step payload from ${opts.stepFile}: ${err.message}`,
+        opts
+      );
+    }
+  }
   if (!opts.run)
     return fail("--run <run-id> is required for browse step.", opts);
   if (!opts.action) {
@@ -18393,7 +18445,8 @@ function defaultFrontmatter(type2, id, slug, name, opts) {
         ...base,
         name,
         role: opts.role ?? "TODO",
-        ...opts.disposition ? { disposition: opts.disposition } : {}
+        ...opts.disposition ? { disposition: opts.disposition } : {},
+        ...opts.access ? { access: opts.access } : {}
       };
     case "outline":
       return { ...base, title: name, ...description };
@@ -18462,7 +18515,7 @@ async function newEntity(type2, opts) {
   }
   const id = randomUUID9();
   const frontmatter = defaultFrontmatter(entityType, id, slug, opts.name, opts);
-  const body = "";
+  const body = opts.body ?? opts.narrative ?? "";
   try {
     const record = await writeEntity(
       projectRoot,
@@ -19433,8 +19486,21 @@ async function evaluate(runId, opts) {
     )
   };
   const prompt = composeJudgePrompt(input);
+  const promptFilePath = opts?.promptFile ?? path25.join(runDirPath, "judge_prompt.md");
+  await fs25.writeFile(promptFilePath, prompt, "utf8");
   if (opts?.json) {
-    console.log(JSON.stringify({ ...input, judge_prompt: prompt }, null, 2));
+    console.log(
+      JSON.stringify(
+        {
+          ...input,
+          prompt_file: path25.relative(projectRoot, promptFilePath),
+          prompt_file_abs: path25.resolve(promptFilePath),
+          judge_prompt: prompt
+        },
+        null,
+        2
+      )
+    );
     return;
   }
   console.log(prompt);
@@ -19526,7 +19592,7 @@ ${formatIssues(fileResult.error)}`,
     runId,
     validatedVerdicts
   );
-  const cloudInfo = await pushRunToCloud(projectRoot, runId);
+  const cloudInfo = opts?.push === false ? void 0 : await pushRunToCloud(projectRoot, runId);
   if (opts?.json) {
     console.log(
       JSON.stringify(
@@ -19770,7 +19836,7 @@ async function collectCompletionExtras(run, opts) {
     parseRunViewport(manifest.viewport)
   );
   const codeWarning = opts?.force ? null : codeChangedWarning(manifest.build, detectWorktreeState(projectRoot));
-  const cloudInfo = await pushRunToCloud(projectRoot, runId);
+  const cloudInfo = opts?.push === false ? void 0 : await pushRunToCloud(projectRoot, runId);
   return { revisit, viewportWarning, codeWarning, cloudInfo };
 }
 function completeJsonPayload(canonical, extras) {
@@ -20223,9 +20289,28 @@ 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 ?? path27.join(runDirPath, "match_prompt.md");
+  if (prompt) {
+    await fs27.writeFile(promptFilePath, prompt, "utf8");
+  } else {
+    try {
+      await fs27.unlink(promptFilePath);
+    } catch {
+    }
+  }
   if (opts?.json) {
     console.log(
-      JSON.stringify({ ...input, needed, match_prompt: prompt }, null, 2)
+      JSON.stringify(
+        {
+          ...input,
+          needed,
+          prompt_file: prompt ? path27.relative(ctx.projectRoot, promptFilePath) : null,
+          prompt_file_abs: prompt ? path27.resolve(promptFilePath) : null,
+          match_prompt: prompt
+        },
+        null,
+        2
+      )
     );
     return;
   }
@@ -20464,7 +20549,7 @@ function registerCloudCommands(program2) {
     "Connect to local cloud stack (default port: 3000)"
   ).addOption(
     new Option("-s, --staging", "Connect to staging cloud stack").hideHelp()
-  ).option("-t, --token <token>", "Authenticate directly with API token / key").option("--web-url <url>", "Custom web dashboard URL").option("--url <api-url>", "API URL (default: https://api.iamu.dev)").option("-y, --yes", "Accept default project without interactive selection").option(
+  ).option("-t, --token <token>", "Authenticate directly with API token / key").option("--web-url <url>", "Custom web dashboard URL").option("--url <api-url>", "API URL (default: https://app.iamu.dev)").option("-y, --yes", "Accept default project without interactive selection").option(
     "--project <project-id>",
     "Cloud project ID to link to, or `new` to create one. Required in a non-interactive shell when cloud projects exist"
   ).option("--no-browser", "Do not launch browser automatically").addHelpText(
@@ -20620,6 +20705,9 @@ function registerProjectCommands(program2) {
   program2.command("new <type>").helpGroup("Project:").description(
     "Create a new entity (persona, outline, capability, source, scenario)"
   ).requiredOption("--name <name>", "Entity name").option("--slug <slug>", "Custom entity slug (defaults to slugified name)").option("--role <role>", "Role description (persona only)").option("--disposition <text>", "Disposition / attitude (persona only)").option(
+    "--access <role>",
+    "Access role or testing account key (persona only)"
+  ).option("--body <text>", "Markdown body / narrative content").option("--narrative <text>", "Alias for --body").option(
     "--description <text>",
     "One-line description (capability, outline)"
   ).option("--outline <slug>", "Outline slug (scenario only)").option("--persona <slug>", "Persona slug (scenario only)").option(
@@ -20696,7 +20784,10 @@ function registerWalkthroughCommands(program2) {
   ).option(
     "--run <run-id>",
     "Run ID to size browser (start) or record step into (step)"
-  ).option("--action <text>", "Action description (step only)").option("--note <text>", "Persona inner monologue / reasoning (step only)").option("--surface <name>", "Screen or surface name (step only)").option("--width <px>", "Window width (start)").option("--height <px>", "Window height (start)").option("--headless", "Run without a window (start)").option(
+  ).option("--action <text>", "Action description (step only)").option("--note <text>", "Persona inner monologue / reasoning (step only)").option("--surface <name>", "Screen or surface name (step only)").option(
+    "--step-file <path>",
+    "Read step payload (action, note, cmd) from a JSON file or '-' for stdin (step only)"
+  ).option("--width <px>", "Window width (start)").option("--height <px>", "Window height (start)").option("--headless", "Run without a window (start)").option(
     "--port <port>",
     "CDP port (start), default 9333",
     (value) => parsePortOption(value)
@@ -20772,9 +20863,9 @@ function registerWalkthroughCommands(program2) {
   ).option("-y, --yes", "Skip interactive prompts").option("--no-prompt", "Skip interactive prompt to view results").option("--view", "Open results in browser immediately without prompt").option(
     "--strict-provenance",
     "Fail if steps show synthetic or programmatic timing anomalies"
-  ).addHelpText(
+  ).option("--no-push", "Skip pushing the run to Iamu Cloud").addHelpText(
     "after",
-    "\nExamples:\n  $ iamu complete <run-id>\n  $ iamu complete <run-id> --view\n  $ iamu complete <run-id> --no-prompt\n  $ iamu complete <run-id> --json\n  $ iamu complete <run-id> --strict-provenance"
+    "\nExamples:\n  $ iamu complete <run-id>\n  $ iamu complete <run-id> --view\n  $ iamu complete <run-id> --no-prompt\n  $ iamu complete <run-id> --no-push\n  $ iamu complete <run-id> --json\n  $ iamu complete <run-id> --strict-provenance"
   ).action(
     async (runId, opts) => {
       const { complete: complete2 } = await Promise.resolve().then(() => (init_complete(), complete_exports));
@@ -20783,23 +20874,27 @@ function registerWalkthroughCommands(program2) {
   );
   program2.command("match <run-id>").helpGroup("Walkthrough:").description(
     "Compose the prompt that links this run's findings to earlier ones"
-  ).option("--json", "Output the match input bundle as JSON").action(async (runId, opts) => {
-    const { match: match2 } = await Promise.resolve().then(() => (init_match(), match_exports));
-    await match2(runId, opts);
-  });
+  ).option("--json", "Output the match input bundle as JSON").option("--prompt-file <path>", "Write the generated prompt to a file").action(
+    async (runId, opts) => {
+      const { match: match2 } = await Promise.resolve().then(() => (init_match(), match_exports));
+      await match2(runId, opts);
+    }
+  );
   program2.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);
   });
-  program2.command("evaluate <run-id>").helpGroup("Walkthrough:").description("Compose evaluation prompt for human-test questions").option("--json", "Output evaluation input bundle as JSON").action(async (runId, opts) => {
-    const { evaluate: evaluate2 } = await Promise.resolve().then(() => (init_evaluate(), evaluate_exports));
-    await evaluate2(runId, opts);
-  });
-  program2.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("--view", "Open results in browser immediately without prompt").addHelpText(
+  program2.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);
+    }
+  );
+  program2.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(
     "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 --json"
+    "\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(
     async (runId, opts) => {
       const { evaluateRecord: evaluateRecord2 } = await Promise.resolve().then(() => (init_evaluate(), evaluate_exports));

package/dist/index.js

@@ -11968,7 +11968,7 @@ var init_credentials = __esm({
     "use strict";
     init_dist2();
     init_dist();
-    DEFAULT_API_URL = "https://api.iamu.dev";
+    DEFAULT_API_URL = "https://app.iamu.dev";
     CredentialsFileError = class extends IamuConfigError {
       /**
        * @param path - The unreadable credentials file.
@@ -12118,7 +12118,7 @@ async function resolveCloudProject(opts) {
     commandError("Not cloud-linked. Run `iamu auth login` to connect.", opts);
     return null;
   }
-  const apiUrl = ctx.config.cloud_api_url ?? "https://api.iamu.dev";
+  const apiUrl = ctx.config.cloud_api_url ?? DEFAULT_API_URL;
   try {
     assertSecureApiUrl(apiUrl, "cloud_api_url");
   } catch (err) {
@@ -13481,12 +13481,24 @@ async function browserLogin(apiUrl, opts, t) {
       chalk8.red(`
   Auth session expired or failed (HTTP ${result.status}).`)
     );
+    console.error(
+      chalk8.dim("  Re-run `iamu auth login` to start a new login session.\n")
+    );
     process.exitCode = 1;
     return null;
   }
   if (result.kind === "timeout") {
     s.stop("Authentication timed out.");
-    console.error(chalk8.red("\n  Authentication timed out. Try again."));
+    console.error(
+      chalk8.red(
+        "\n  Authentication timed out (no approval received within 2 minutes)."
+      )
+    );
+    console.error(
+      chalk8.dim(
+        "  \u2022 Complete browser authorization faster, or authenticate non-interactively with --token <key>.\n  \u2022 Local setup is unaffected \u2014 re-run `iamu auth login` anytime.\n"
+      )
+    );
     process.exitCode = 1;
     return null;
   }
@@ -13512,7 +13524,12 @@ async function startAuthSession(apiUrl, timeoutMs) {
     if (!res.ok) {
       console.error(
         chalk8.red(
-          `  Failed to start auth session: ${res.text || `HTTP ${res.status}`}`
+          `  Failed to start auth session at ${apiUrl}: ${res.text || `HTTP ${res.status}`}`
+        )
+      );
+      console.error(
+        chalk8.dim(
+          "  \u2022 The cloud service may be experiencing downtime or maintenance.\n  \u2022 Local setup is unaffected; continue with local workflows or retry later with `iamu auth login`.\n"
         )
       );
       process.exitCode = 1;
@@ -13526,7 +13543,13 @@ async function startAuthSession(apiUrl, timeoutMs) {
     return { sessionId: data.sessionId, loginUrl: data.loginUrl };
   } catch (err) {
     console.error(
-      chalk8.red("  Cannot reach Iamu Cloud.") + chalk8.dim(` (${errorMessage(err)})`)
+      chalk8.red(`  Cannot reach Iamu Cloud (${apiUrl}).`) + chalk8.dim(`
+  Reason: ${errorMessage(err)}`)
+    );
+    console.error(
+      chalk8.dim(
+        "\n  \u2022 Check your internet connection or proxy settings.\n  \u2022 If using a custom instance, pass --url <api-url> or set IAMU_API_URL.\n  \u2022 Local setup is unaffected; continue with local workflows or retry later with `iamu auth login`.\n"
+      )
     );
     process.exitCode = 1;
     return null;
@@ -16957,6 +16980,35 @@ function printStep(opts, record, projectRoot) {
   }
 }
 async function browseStep(args, opts, driver) {
+  if (opts.stepFile) {
+    try {
+      let raw;
+      if (opts.stepFile === "-") {
+        raw = readFileSync6(0, "utf8");
+      } else {
+        raw = readFileSync6(opts.stepFile, "utf8");
+      }
+      const data = JSON.parse(raw);
+      if (data.run && typeof data.run === "string") opts.run = data.run;
+      if (data.action && typeof data.action === "string")
+        opts.action = data.action;
+      if (data.note && typeof data.note === "string") opts.note = data.note;
+      if (data.surface && typeof data.surface === "string")
+        opts.surface = data.surface;
+      if (args.length === 0 && data.cmd) {
+        if (Array.isArray(data.cmd)) {
+          args = data.cmd.map(String);
+        } else if (typeof data.cmd === "string") {
+          args = data.cmd.trim().split(/\s+/);
+        }
+      }
+    } catch (err) {
+      return fail(
+        `Failed to read step payload from ${opts.stepFile}: ${err.message}`,
+        opts
+      );
+    }
+  }
   if (!opts.run)
     return fail("--run <run-id> is required for browse step.", opts);
   if (!opts.action) {
@@ -18372,7 +18424,8 @@ function defaultFrontmatter(type2, id, slug, name, opts) {
         ...base,
         name,
         role: opts.role ?? "TODO",
-        ...opts.disposition ? { disposition: opts.disposition } : {}
+        ...opts.disposition ? { disposition: opts.disposition } : {},
+        ...opts.access ? { access: opts.access } : {}
       };
     case "outline":
       return { ...base, title: name, ...description };
@@ -18441,7 +18494,7 @@ async function newEntity(type2, opts) {
   }
   const id = randomUUID9();
   const frontmatter = defaultFrontmatter(entityType, id, slug, opts.name, opts);
-  const body = "";
+  const body = opts.body ?? opts.narrative ?? "";
   try {
     const record = await writeEntity(
       projectRoot,
@@ -19412,8 +19465,21 @@ async function evaluate(runId, opts) {
     )
   };
   const prompt = composeJudgePrompt(input);
+  const promptFilePath = opts?.promptFile ?? path25.join(runDirPath, "judge_prompt.md");
+  await fs25.writeFile(promptFilePath, prompt, "utf8");
   if (opts?.json) {
-    console.log(JSON.stringify({ ...input, judge_prompt: prompt }, null, 2));
+    console.log(
+      JSON.stringify(
+        {
+          ...input,
+          prompt_file: path25.relative(projectRoot, promptFilePath),
+          prompt_file_abs: path25.resolve(promptFilePath),
+          judge_prompt: prompt
+        },
+        null,
+        2
+      )
+    );
     return;
   }
   console.log(prompt);
@@ -19505,7 +19571,7 @@ ${formatIssues(fileResult.error)}`,
     runId,
     validatedVerdicts
   );
-  const cloudInfo = await pushRunToCloud(projectRoot, runId);
+  const cloudInfo = opts?.push === false ? void 0 : await pushRunToCloud(projectRoot, runId);
   if (opts?.json) {
     console.log(
       JSON.stringify(
@@ -19749,7 +19815,7 @@ async function collectCompletionExtras(run, opts) {
     parseRunViewport(manifest.viewport)
   );
   const codeWarning = opts?.force ? null : codeChangedWarning(manifest.build, detectWorktreeState(projectRoot));
-  const cloudInfo = await pushRunToCloud(projectRoot, runId);
+  const cloudInfo = opts?.push === false ? void 0 : await pushRunToCloud(projectRoot, runId);
   return { revisit, viewportWarning, codeWarning, cloudInfo };
 }
 function completeJsonPayload(canonical, extras) {
@@ -20202,9 +20268,28 @@ 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 ?? path27.join(runDirPath, "match_prompt.md");
+  if (prompt) {
+    await fs27.writeFile(promptFilePath, prompt, "utf8");
+  } else {
+    try {
+      await fs27.unlink(promptFilePath);
+    } catch {
+    }
+  }
   if (opts?.json) {
     console.log(
-      JSON.stringify({ ...input, needed, match_prompt: prompt }, null, 2)
+      JSON.stringify(
+        {
+          ...input,
+          needed,
+          prompt_file: prompt ? path27.relative(ctx.projectRoot, promptFilePath) : null,
+          prompt_file_abs: prompt ? path27.resolve(promptFilePath) : null,
+          match_prompt: prompt
+        },
+        null,
+        2
+      )
     );
     return;
   }
@@ -20435,7 +20520,7 @@ function registerCloudCommands(program) {
     "Connect to local cloud stack (default port: 3000)"
   ).addOption(
     new Option("-s, --staging", "Connect to staging cloud stack").hideHelp()
-  ).option("-t, --token <token>", "Authenticate directly with API token / key").option("--web-url <url>", "Custom web dashboard URL").option("--url <api-url>", "API URL (default: https://api.iamu.dev)").option("-y, --yes", "Accept default project without interactive selection").option(
+  ).option("-t, --token <token>", "Authenticate directly with API token / key").option("--web-url <url>", "Custom web dashboard URL").option("--url <api-url>", "API URL (default: https://app.iamu.dev)").option("-y, --yes", "Accept default project without interactive selection").option(
     "--project <project-id>",
     "Cloud project ID to link to, or `new` to create one. Required in a non-interactive shell when cloud projects exist"
   ).option("--no-browser", "Do not launch browser automatically").addHelpText(
@@ -20591,6 +20676,9 @@ function registerProjectCommands(program) {
   program.command("new <type>").helpGroup("Project:").description(
     "Create a new entity (persona, outline, capability, source, scenario)"
   ).requiredOption("--name <name>", "Entity name").option("--slug <slug>", "Custom entity slug (defaults to slugified name)").option("--role <role>", "Role description (persona only)").option("--disposition <text>", "Disposition / attitude (persona only)").option(
+    "--access <role>",
+    "Access role or testing account key (persona only)"
+  ).option("--body <text>", "Markdown body / narrative content").option("--narrative <text>", "Alias for --body").option(
     "--description <text>",
     "One-line description (capability, outline)"
   ).option("--outline <slug>", "Outline slug (scenario only)").option("--persona <slug>", "Persona slug (scenario only)").option(
@@ -20667,7 +20755,10 @@ function registerWalkthroughCommands(program) {
   ).option(
     "--run <run-id>",
     "Run ID to size browser (start) or record step into (step)"
-  ).option("--action <text>", "Action description (step only)").option("--note <text>", "Persona inner monologue / reasoning (step only)").option("--surface <name>", "Screen or surface name (step only)").option("--width <px>", "Window width (start)").option("--height <px>", "Window height (start)").option("--headless", "Run without a window (start)").option(
+  ).option("--action <text>", "Action description (step only)").option("--note <text>", "Persona inner monologue / reasoning (step only)").option("--surface <name>", "Screen or surface name (step only)").option(
+    "--step-file <path>",
+    "Read step payload (action, note, cmd) from a JSON file or '-' for stdin (step only)"
+  ).option("--width <px>", "Window width (start)").option("--height <px>", "Window height (start)").option("--headless", "Run without a window (start)").option(
     "--port <port>",
     "CDP port (start), default 9333",
     (value) => parsePortOption(value)
@@ -20743,9 +20834,9 @@ function registerWalkthroughCommands(program) {
   ).option("-y, --yes", "Skip interactive prompts").option("--no-prompt", "Skip interactive prompt to view results").option("--view", "Open results in browser immediately without prompt").option(
     "--strict-provenance",
     "Fail if steps show synthetic or programmatic timing anomalies"
-  ).addHelpText(
+  ).option("--no-push", "Skip pushing the run to Iamu Cloud").addHelpText(
     "after",
-    "\nExamples:\n  $ iamu complete <run-id>\n  $ iamu complete <run-id> --view\n  $ iamu complete <run-id> --no-prompt\n  $ iamu complete <run-id> --json\n  $ iamu complete <run-id> --strict-provenance"
+    "\nExamples:\n  $ iamu complete <run-id>\n  $ iamu complete <run-id> --view\n  $ iamu complete <run-id> --no-prompt\n  $ iamu complete <run-id> --no-push\n  $ iamu complete <run-id> --json\n  $ iamu complete <run-id> --strict-provenance"
   ).action(
     async (runId, opts) => {
       const { complete: complete2 } = await Promise.resolve().then(() => (init_complete(), complete_exports));
@@ -20754,23 +20845,27 @@ function registerWalkthroughCommands(program) {
   );
   program.command("match <run-id>").helpGroup("Walkthrough:").description(
     "Compose the prompt that links this run's findings to earlier ones"
-  ).option("--json", "Output the match input bundle as JSON").action(async (runId, opts) => {
-    const { match: match2 } = await Promise.resolve().then(() => (init_match(), match_exports));
-    await match2(runId, opts);
-  });
+  ).option("--json", "Output the match input bundle as JSON").option("--prompt-file <path>", "Write the generated prompt to a file").action(
+    async (runId, opts) => {
+      const { match: match2 } = await Promise.resolve().then(() => (init_match(), match_exports));
+      await match2(runId, opts);
+    }
+  );
   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);
   });
-  program.command("evaluate <run-id>").helpGroup("Walkthrough:").description("Compose evaluation prompt for human-test questions").option("--json", "Output evaluation input bundle as JSON").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("--view", "Open results in browser immediately without prompt").addHelpText(
+  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(
     "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 --json"
+    "\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(
     async (runId, opts) => {
       const { evaluateRecord: evaluateRecord2 } = await Promise.resolve().then(() => (init_evaluate(), evaluate_exports));

package/dist/templates/skills/iamu-findings.md

@@ -67,47 +67,45 @@ Filter to `triage_status: open`.
 
 A run that simply did not come across a finding proves nothing — never call a fix verified because it was not seen. After the list, if any fixes await a re-run, say how many and in which scenarios (`iamu status --json` → `rerun`, with `requests.open` for team requests), and offer `iamu-run <scenario>` for the first one.
 
-Group by `scenario` field and render as a severity-sorted table per scenario group (CRITICAL → MAJOR → MINOR → OBS; hinders and missing first, helps last):
+Group by `scenario` field and render with an executive tally header, followed by a severity-sorted list per scenario group (CRITICAL → MAJOR → MINOR → OBS; hinders and missing first, helps last), including persona quotes, evidence, and clickable file links:
 
 ```
-Open findings (N total)
-
-▼ maria-gomez--busy-shift (4 findings)
-
-| # | Severity | Type    | Finding                                          | Slug                                                       |
-|---|----------|---------|--------------------------------------------------|------------------------------------------------------------|
-| 1 | CRITICAL | hinders | Handoff list is cluttered                        | maria-gomez--busy-shift--handoff-list-cluttered-a1b2c3     |
-| 2 | MAJOR    | missing | No visible confirmation after shift submit       | maria-gomez--busy-shift--no-submit-confirmation-d4e5f6     |
-| 3 | MINOR    | hinders | Timeout warning fires mid-input                  | maria-gomez--busy-shift--timeout-mid-input-g7h8i9          |
-| 4 | OBS      | helps   | Gesture hint at top of screen                    | maria-gomez--busy-shift--gesture-hint-j1k2l3               |
-
-▼ dev-patel--checkout-abandon (3 findings)
-
-| # | Severity | Type      | Finding                                          | Slug                                                       |
-|---|----------|-----------|--------------------------------------------------|------------------------------------------------------------|
-| 5 | CRITICAL | incorrect | Cart total recalculates to wrong amount          | dev-patel--checkout-abandon--cart-total-wrong-...          |
-| 6 | MAJOR    | missing   | No save-for-later affordance                     | dev-patel--checkout-abandon--no-save-for-later-...         |
-| 7 | MINOR    | hinders   | Auto-scroll on form error                        | dev-patel--checkout-abandon--auto-scroll-error-...         |
+Findings Tally: <N> Open (<C> Critical · <M> Major · <m> Minor) across <S> Scenarios
+Awaiting verification: <K> addressed findings pending re-run
+
+▼ [<scenario>](iamu/scenarios/<scenario>.md) (4 findings)
+1. [CRITICAL · hinders] Handoff list is cluttered ([file](iamu/findings/<slug>.md))
+   • Persona: <Persona Name>: "<Persona reaction or consequence quote>"
+   • Evidence: Step <N> at <url>
+   • Recommendation: Add status filter chips
+
+2. [MAJOR · missing] No visible confirmation after shift submit ([file](iamu/findings/<slug>.md))
+   • Persona: <Persona Name>: "<Persona reaction or consequence quote>"
+   • Evidence: Step <N> at <url>
+   • Recommendation: Show inline success toast
 ```
 
-Ask the user which finding to triage (by number, slug, or "skip").
+Ask the user how they would like to triage:
 
+- **"walk through them"** → iterate through all open findings one-by-one in order with full context, code location, and triage choices (`[Fix now]  [Skip / Dismiss]  [Discuss]  [Next]`).
 - **"all critical"** → iterate through all critical findings in order.
 - **Scenario group name** (e.g. "group 1") → iterate through that scenario's findings.
-- **Single number or slug** → single finding.
+- **Single number or slug** → single finding (skip to step 3).
+- **"fix 1 and 2"** → make code fixes and mark addressed immediately.
+- **"skip 3" / "dismiss 3"** → dismiss with reason (`out_of_scope`, `not_relevant`, `walker_error`, `duplicate`).
 
 ### 3. Direct triage: review one finding
 
-Read the finding file at `iamu/findings/<slug>.md`. Parse the YAML frontmatter and markdown body. Render full detail:
+Read the finding file at `iamu/findings/<slug>.md`. Parse the YAML frontmatter and markdown body. Render full detail with clickable links and evidence:
 
 ```
-Finding: <title>
-Slug: <slug>
-Scenario: <scenario>
-Type: <type>  Severity: <severity>  Triage: <triage_status>
+Finding: <title> ([file](iamu/findings/<slug>.md))
+Scenario: [<scenario>](iamu/scenarios/<scenario>.md)
+Severity: <severity> · Type: <type> · Status: <triage_status>
 
-UI fact: <ui_fact>
-Consequence: <consequence>
+Persona Quote: "<persona_reaction_or_consequence>"
+UI Fact: <ui_fact>
+Evidence: Step <N> at <url> (Screenshot: [view](iamu/.runs/<run>/screenshots/<NNN>.png))
 
 Description:
 <markdown body above ## Recommendation>
@@ -115,7 +113,7 @@ Description:
 Recommendation:
 <## Recommendation section, or "none">
 
-Linked run: iamu/.runs/<run>/report.md
+Report: [report.md](iamu/.runs/<run>/report.md)
 ```
 
 If the finding references a run directory, mention the report path for context. If the user wants to see the screenshot, read from `iamu/.runs/<run>/screenshots/`.

package/dist/templates/skills/iamu-new.md

@@ -56,53 +56,48 @@ Determine the mode based on `$ARGUMENTS` and user intent:
 
 ### 2. Propose scenario seeds
 
-Propose 2–3 scenario seeds in a compact comparison table fitting the terminal viewport. If personas exist in `iamu/personas/`, explicitly indicate which existing persona pairs with each seed concept. Do not write full paragraphs or full scenarios until a direction is picked.
+Propose 2–3 scenario seeds as scannable numbered cards. Do NOT use multi-column markdown tables with full prose sentences (they wrap awkwardly and break borders in terminal viewports). If personas exist in `iamu/personas/`, explicitly indicate which existing cast member pairs with each seed concept.
 
 ```
-| # | Seed Concept | Persona / Actor | Type | Human Situation & Core Tension | What It Stress-Tests |
-|---|--------------|-----------------|------|--------------------------------|----------------------|
-| 1 | <Short title> | <existing slug or role> | Routine | <1-2 sentences on who is doing what> | <What this tests> |
-| 2 | <Short title> | <existing slug or role> | Edge case | <1-2 sentences on uncommon situation> | <What this tests> |
-| 3 | <Short title> | <existing slug or role> | Tension | <1-2 sentences on conflicting needs> | <What this tests> |
+1. <Title> (<Type> · <existing persona slug or context actor>)
+   • Tension: <1 concise sentence on the human or organizational tension>
+   • Stress-tests: <What this reveals about the product>
+
+2. <Title> (<Type> · <existing persona slug or context actor>)
+   • Tension: <1 concise sentence>
+   • Stress-tests: <What this reveals about the product>
+
+3. <Title> (<Type> · <existing persona slug or context actor>)
+   • Tension: <1 concise sentence>
+   • Stress-tests: <What this reveals about the product>
 ```
 
 Ask the user: "Which seed should we develop (1–3), or suggest another angle?"
 
 ### 3. Develop the situation
 
-Once the user picks a direction, draft the full situation:
-
-- **Narrative** (3–5 sentences) — mundane specifics, not abstract test language. Time pressure, competing priorities, real constraints. Write it as a human story.
-- **Tension** (usually null; set only when two legitimate needs genuinely collide — e.g., speed vs. thoroughness, privacy vs. transparency)
-- **Situation roles** (2–4 people with stakes) — each person should see the situation differently. Not conflict for drama — realistic tension like: one person wants to move on, another wants to investigate.
-- **Complexity level**
-
-**Before finalizing**, ask the user: "What should this walkthrough focus on?" This is the research question — what they want to learn. Examples: "Can a new admin onboard without training?", "Does the checkout flow work under time pressure?", "Is the reporting workflow accessible to non-technical users?"
-
-From their answer, derive ONE concrete human test — a specific yes/partial/no checkpoint the evaluation step will score. Suggest it and let the user refine:
+Once the user picks a direction (e.g. "1"), draft the situation concisely.
 
-> Focus: "Can a new admin onboard without training?"
-> Human test: "Could the admin complete employee bulk-import without consulting documentation?"
+Do NOT ask an open-ended question like "What should this walkthrough focus on?" and then immediately answer it yourself in the same turn. Instead, propose an opinionated research focus question and one concrete binary (yes/partial/no) human checkpoint directly in the draft for the user to confirm or adjust.
 
-The user's focus frames the overall assessment after the walkthrough. The human test is a concrete checkpoint that feeds into it.
+Do NOT use markdown blockquote syntax (`>`), which renders as stray `|` pipe characters in terminal frontends. Keep the narrative capped at 2–3 punchy sentences (problem-space only, zero UI terms).
 
 Present the draft to the user as a structured, scannable block **before creating anything**:
 
 ```
 ### Situation Draft: <Name>
 
-> **Narrative:** <3–5 sentences describing the human situation without mentioning UI>
->
-> **Tension:** <legitimate colliding needs or "None">
-> **Focus Question:** <user's research question>
-> **Human Checkpoint:** <derived checkpoint question>
+Narrative: <2–3 sentences describing the human situation, time pressure, or physical reality without mentioning software UI>
+Tension: <Legitimate colliding needs or "None">
+Focus Question: <Proposed research focus question, e.g. "Can a frontline worker submit an urgent slip hazard report in under 60 seconds without abandoning floor duties?">
+Human Checkpoint: <Concrete binary yes/partial/no question scored at evaluation>
 
-**Roles with Stakes:**
-- **<role>**: <stake>
-- **<role>**: <stake>
+Roles with Stakes:
+• <Role 1>: <Stake>
+• <Role 2>: <Stake>
 ```
 
-User approves, refines ("make it more time-pressured"), or rejects.
+Ask the user: "Ready to test this draft, or would you like to refine the focus question or circumstances? (Enter to accept, or type adjustments)"
 
 ### 4. Pick or propose personas
 
@@ -110,25 +105,25 @@ User approves, refines ("make it more time-pressured"), or rejects.
 Inspect `iamu/personas/` (`iamu list personas`). If an existing persona in the casting panel is a natural fit for this situation, propose them first to build longitudinal test history:
 `Reusable from panel: <slug> (<role>) — <why they fit this situation>`
 
-If no existing persona fits, or if testing an uncovered perspective is needed, propose 2–3 persona candidates in a compact table:
-
-- Different roles (the manager vs. the field worker vs. the auditor)
-- Different dispositions (the patient learner vs. the harried pragmatist)
-- Different contexts (first time vs. experienced, desktop vs. mobile, fluent vs. second-language)
+If no existing persona fits, or if testing an uncovered perspective is needed, propose 2–3 persona candidates as numbered cards (do NOT use a wide table):
 
 ```
-| # | Name | Role | Why this persona tests something different |
-|---|------|------|-------------------------------------------|
-| 1 | ... | ... | ... |
-| 2 | ... | ... | ... |
-| 3 | ... | ... | ... |
+1. <Name> (<Role>)
+   • Friction & Biases: <Specific friction triggers, skepticism, and bounce risks>
+   • Why this tests something different: <Unique perspective or workflow divergence>
+
+2. <Name> (<Role>)
+   • Friction & Biases: <Specific friction triggers, skepticism, and bounce risks>
+   • Why this tests something different: <Unique perspective or workflow divergence>
 ```
 
 The user picks one (or more — each becomes a separate scenario). "New" to propose different candidates. "Skip" to save as draft without a persona.
 
 ### 5. Classify into capabilities
 
-Situations carry ONE primary capability (product area grouping) and optional secondary capabilities (cross-cutting tags). Read existing capabilities from `iamu/capabilities/`.
+Situations carry ONE primary capability (product area grouping) and optional secondary capabilities (cross-cutting tags). Read existing capabilities directly from `iamu/capabilities/` or `iamu/context.yml`.
+
+Do NOT execute interactive bash commands (like `iamu list capabilities`) during conversational turns; resolve capabilities silently from workspace files.
 
 - **High confidence match** → assign silently, one line: `Capability: <slug> (auto)`
 - **Low confidence or new** → ask: "Create new capability `<slug>`?"
@@ -178,12 +173,16 @@ For drafts (no persona): omit `--persona`, omit the brief body.
 
 ### 7. Summarize
 
+Present the created entities with clickable file links and exact run commands:
+
 ```
-Scenario: <scenario-slug>
-Situation: <situation name>
-Persona: <persona-name>   (or "draft — no persona yet")
+Created Scenario: [<scenario-slug>](iamu/scenarios/<scenario-slug>.md)
+• Situation: [<outline-slug>](iamu/outlines/<outline-slug>.md)
+• Persona: [<persona-slug>](iamu/personas/<persona-slug>.md)  (or "draft — no persona bound yet")
+• Capability: <primary_capability>
 
-Run it:  iamu-run <scenario-slug>
+Next step:
+  iamu-run <scenario-slug>              # Run walkthrough as <persona-name>
 ```
 
 Run `iamu validate --all` to verify all entities before reporting done.

package/dist/templates/skills/iamu-propose.md

@@ -61,40 +61,56 @@ Four entry paths based on `$ARGUMENTS`:
 - **Open-ended** (e.g. `iamu-propose`, `iamu-propose "what's missing?"`) — analyze coverage gaps across both scenarios and persona diversity. Prioritize uncovered capabilities and actors without personas.
 - **Specific tension** (e.g. `iamu-propose "what happens when the safety coordinator disagrees with HR?"`) — use as seed but ground in context. Verify the tension is real (do these actors and dynamics exist in the domain?).
 
-### 4. Present candidates (Comparison Table)
+### 4. Present candidates (Numbered Cards)
 
-Present candidates in a single, high-contrast **Markdown comparison table** fitting the terminal viewport. Do NOT dump long paragraphs, full narratives, or regulatory citations upfront.
+Present candidates as scannable numbered cards. Do NOT use multi-column markdown tables with full prose sentences (they wrap awkwardly and break borders in terminal viewports). Do NOT dump long paragraphs, full narratives, or regulatory citations upfront.
 
 #### A. When proposing Scenarios:
 
-Lead with a one-line summary of existing coverage, then render the table:
+Lead with existing coverage using clickable links, then render the candidates:
 
 ```
-Existing coverage: <N> scenarios (<list slugs>). Uncovered areas: <gaps>.
+Existing coverage: <N> scenarios ([<slug1>](iamu/scenarios/<slug1>.md), ...). Uncovered areas: <gaps>.
 
-| # | Situation | Role | Core Domain Tension | What It Stress-Tests |
-|---|-----------|------|---------------------|----------------------|
-| 1 | <Short situation name> | <Actor from context> | <1-line human/domain tension> | <What this reveals about the product> |
-| 2 | ... | ... | ... | ... |
-| 3 | ... | ... | ... | ... |
+1. <Short situation name> (<Actor from context>)
+   • Tension: <1-line human/domain tension>
+   • Stress-tests: <What this reveals about the product>
 
-Pick a number (1–3) to draft via iamu-new, or refine (e.g. "make #2 more time-pressured", "none of these — explore <area>").
+2. <Short situation name> (<Actor from context>)
+   • Tension: <1-line human/domain tension>
+   • Stress-tests: <What this reveals about the product>
+
+3. <Short situation name> (<Actor from context>)
+   • Tension: <1-line human/domain tension>
+   • Stress-tests: <What this reveals about the product>
+
+Next action:
+  Type 1, 2, or 3 to scaffold via iamu-new
+  Or describe adjustments (e.g. "make #2 more time-pressured", "explore <area>")
 ```
 
 #### B. When proposing Personas:
 
-Lead with existing persona coverage and uncovered roles from `context.yml`:
+Lead with existing persona coverage using clickable links and uncovered roles from `context.yml`:
 
 ```
-Existing personas: <list slugs>. Uncovered roles from context.yml: <roles>.
+Existing personas: [<slug1>](iamu/personas/<slug1>.md), ... Uncovered roles from context.yml: <roles>.
+
+1. <Name> (<Actor role>)
+   • Friction & Biases: <Specific friction triggers, skepticism, and bounce risks>
+   • Key Expectations & Vocabulary: <Domain terms and spec requirements>
+
+2. <Name> (<Actor role>)
+   • Friction & Biases: <Specific friction triggers, skepticism, and bounce risks>
+   • Key Expectations & Vocabulary: <Domain terms and spec requirements>
 
-| # | Persona Candidate | Domain Role | Diagnostic Friction & Biases | Key Expectations & Vocabulary |
-|---|-------------------|-------------|------------------------------|-------------------------------|
-| 1 | <Name> | <Actor role> | <Specific friction triggers, skepticism, and bounce risks> | <Domain terms and spec requirements> |
-| 2 | ... | ... | ... | ... |
-| 3 | ... | ... | ... | ... |
+3. <Name> (<Actor role>)
+   • Friction & Biases: <Specific friction triggers, skepticism, and bounce risks>
+   • Key Expectations & Vocabulary: <Domain terms and spec requirements>
 
-Pick a number (1–3) to draft via iamu-new (as a standalone persona or with a scenario), or refine.
+Next action:
+  Type 1, 2, or 3 to scaffold via iamu-new
+  Or describe adjustments
 ```
 
 Ground rules for generation:

package/dist/templates/skills/iamu-run.md

@@ -215,6 +215,12 @@ Use atomic CLI commands to drive and record in one step — do NOT manually auth
   iamu browse step --run <run-id> --action "Opened dashboard" --note "First thing I see is the overview panel" goto https://app.example.com/dashboard
   iamu browse step --run <run-id> --action "Click checkout" --note "Button was hard to find" click button "Checkout"
   ```
+  **Avoid shell quoting friction:** When persona notes or actions contain quotes, apostrophes, or multi-line monologues, use `--step-file <path>` (or `-` for stdin) to avoid shell escaping errors:
+  ```bash
+  iamu browse step --run <run-id> --step-file <path-to-step.json> click button "Checkout"
+  # or pass the entire action payload including cmd via JSON / stdin:
+  # { "action": "...", "note": "...", "cmd": ["click", "button", "Checkout"] }
+  ```
   This executes the browser action, waits for the DOM, takes the screenshot into `screenshots/step-N.png`, captures the URL, and writes `steps/NNN.json` atomically.
 
 - **When using an external surface (iOS Simulator / custom MCP):**
@@ -249,26 +255,21 @@ Findings never name a human test: the walker does not see them. The judge links
 
 After the walker returns, you MUST complete ALL of the following before presenting findings to the user. Do NOT present findings early. Do NOT ask the user anything. Execute steps A→B→C→D→E in order.
 
-**A. Assemble canonical + report.** Use the CLI:
+**A. Assemble canonical + report (local).** Use `--no-push` so post-processing stays fast, local, and synchronous:
 
 ```bash
-iamu complete <run-id> --no-prompt
+iamu complete <run-id> --no-prompt --no-push --json
 ```
 
-This reads all steps, findings, and entity files, assembles `canonical.json`, generates `report.md`, computes the delta against prior runs, and flips the manifest to completed. All in one command.
+This reads all steps, findings, and entity files, assembles `canonical.json`, generates `report.md`, and computes the delta against prior runs.
 
-To get the canonical data for presentation, run with `--json`:
-```bash
-iamu complete <run-id> --no-prompt --json
-```
-
-**B. Match findings to earlier runs.** A fresh walker never words a recurring problem the same way twice, so `complete` alone reports recurrences as new and earlier findings as "not seen". Get the matcher bundle:
+**B. Match findings to earlier runs.** Get the matcher bundle:
 
 ```bash
 iamu match <run-id> --json
 ```
 
-If `needed` is `false` (no earlier findings for this scenario, or none this run), skip to C. Otherwise dispatch a matcher subagent with `match_prompt` as its only context — NOT the walker, which must never see earlier findings. Write its JSON answer to a file and record it:
+If `needed` is `false` (no earlier findings for this scenario, or none this run), skip to C. Otherwise, read the prompt from `iamu/.runs/<run-id>/match_prompt.md` directly and dispatch a matcher subagent with it as its only context. Write its JSON answer to `<matches.json>` and record it:
 
 ```bash
 iamu match-record <run-id> --file <matches.json>
@@ -276,23 +277,23 @@ iamu match-record <run-id> --file <matches.json>
 
 This links recurrences to their earlier canonical finding, marks earlier findings the run's steps show fixed (only with cited steps), and re-derives the delta and report. If the matcher's output is rejected, show the error to the matcher once and retry; if it fails again, continue without it — the exact-text delta from A stands.
 
-**C. Evaluate human tests.** Use the CLI to get the evaluation prompt:
+**C. Evaluate human tests.** Get the evaluation prompt:
 
 ```bash
 iamu evaluate <run-id> --json
 ```
 
-This returns the judge prompt input bundle. Dispatch the evaluator as a subagent with that prompt. After the evaluator returns verdicts, record them:
+Read the evaluation prompt from `iamu/.runs/<run-id>/judge_prompt.md` directly. Dispatch the evaluator as a subagent with that prompt. After the evaluator returns verdicts, record them locally with `--no-push`:
 
 ```bash
-iamu evaluate-record <run-id> --file <verdicts.json> --no-prompt
+iamu evaluate-record <run-id> --file <verdicts.json> --no-prompt --no-push
 ```
 
-This also links the findings each verdict cites to that human test (`human_test_id` on the finding file, only where none is set), so `iamu sync` carries the link to the cloud.
+This links findings to human tests (`human_test_id`) and updates the report with judge verdicts.
 
 **D. Read the completed canonical.** Read `iamu/.runs/<run-id>/canonical.json` for the final data including verification delta (if a prior run exists). Use this for step 5 presentation.
 
-**E. Publish (linked mode only).** `complete` and `evaluate-record` already pushed the run itself — report, steps, screenshots, verdicts. What they do not push are the finding files the matcher and judge updated (recurrence links, `human_test_id`); those go with sync:
+**E. Publish (linked mode only).** Upload the completed run, screenshots, verdicts, and findings in one atomic sync:
 
 ```bash
 iamu sync --json
@@ -320,15 +321,17 @@ The `walker_prompt` from `iamu instructions walk` is the source of truth and con
 
 ### 5. Present assessment — stay in the conversation
 
-Render results **inline** so the user can act without leaving the conversation. Lead with the overall assessment, not a findings dump.
-
-1. **Overall assessment** — answer the research question from the outline's human test. Read the outline's `human_tests[0].question` (the focus question the user defined when creating the scenario). Frame the verdict around it:
+Render results **inline** with a high-contrast executive summary banner, followed by findings enriched with persona voice, evidence citations, and clickable file links.
 
-   > **Could the admin complete bulk-import without consulting documentation?** No. The import flow requires knowledge of the role hierarchy that isn't documented in-app. 3 issues found, 1 critical.
+1. **Executive Summary Banner & Focus Checkpoint**
 
-   If the evaluation subagent ran, use its verdict. If it failed or wasn't run, synthesize from findings: count hinders/missing by severity, state whether the persona could complete their task.
+   Read the outline's `human_tests[0].question` and answer it directly. Use the evaluation verdict if available:
 
-   **This is the most important part of the output.** The user defined this question as their focus — answer it directly.
+   ```
+   Walkthrough: [<scenario-slug>](iamu/scenarios/<scenario-slug>.md) ([<persona>](iamu/personas/<persona>.md))
+   Verdict: <FAIL / PARTIAL / PASS> · <N> Blockers (Critical) · <M> Friction points (Major/Minor) · <K> Helpers (Steps: <N>)
+   Focus Checkpoint: "<human_tests[0].question>" → <No / Partial / Yes>: <1-2 sentence direct answer explaining why>
+   ```
 
 2. **Progress since last run** (only when canonical.json contains a `verification` section). Present the delta:
 
@@ -340,25 +343,25 @@ Render results **inline** so the user can act without leaving the conversation.
      + 1 new since that run (date picker locale)
    ```
 
-   `resolved` means the matcher saw this run's steps do the thing the finding said failed — say which step. `not_observed` means only that this walk did not record the finding again. Never present it as fixed: the walker may have stopped before that screen or taken another route. Say which ones were not seen and, if the walk plainly never reached the screen they live on, say that too. `iamu complete` reports whether the walk reached the places where fixes await a re-run (`Re-check places: reached N of M`, `revisit_coverage` in `--json`); name the ones not reached — their fixes stay awaiting.
-
-   If no prior run exists, skip this.
+   `resolved` means the matcher saw this run's steps do the thing the finding said failed — say which step. `not_observed` means only that this walk did not record the finding again. Never present it as fixed: the walker may have stopped before that screen or taken another route. Say which ones were not seen and, if the walk plainly never reached the screen they live on, say that too.
 
-3. **Findings** — severity-first (CRITICAL → MAJOR → MINOR), grouped by type (hinders and missing first — the actionable ones — then helps at the bottom):
+3. **Findings** — severity-first (CRITICAL → MAJOR → MINOR), grouped by type (hinders and missing first, helps at the bottom). For each finding, include the **persona reaction**, **evidence citation**, and **clickable link**:
 
    **Hinders / Missing** (act on these):
 
-   | # | Severity | Type | Finding | Recommendation |
-   |---|----------|------|---------|----------------|
-   | 1 | CRITICAL | hinders | Submit fails opaquely when required field empty | Show validation inline before submit |
-   | 2 | MAJOR | hinders | Date picker has no "today" shortcut | Add quick-select for common dates |
-   | 3 | MINOR | missing | Help text uses jargon ("slutdatum") | Use plain language ("end date") |
+   1. [CRITICAL · hinders] Submit fails opaquely when required field empty ([file](iamu/findings/<slug>.md))
+      • Persona: <Persona Name>: "<Persona reaction quote or consequence showing real human friction>"
+      • Evidence: Step <N> at <url> (Screenshot: [view](iamu/.runs/<run-id>/screenshots/<NNN>.png))
+      • Recommendation: <Concrete recommendation from finding>
+
+   2. [MAJOR · hinders] Date picker has no "today" shortcut ([file](iamu/findings/<slug>.md))
+      • Persona: <Persona Name>: "<Persona reaction quote or consequence>"
+      • Evidence: Step <N> at <url>
+      • Recommendation: <Concrete recommendation from finding>
 
    **Helps** (preserve these):
 
-   | # | Type | Finding |
-   |---|------|---------|
-   | 4 | helps | Search auto-suggests from recent entries |
+   • [helps] Search auto-suggests from recent entries (Step <N>)
 
 4. **What worked** — supportive moments worth preserving (brief, from `what_worked` in the canonical JSON).
 
@@ -369,16 +372,65 @@ Render results **inline** so the user can act without leaving the conversation.
 
 6. **Cloud** — one line, by mode:
    - **Linked, run on the cloud** → `Shareable report: <url>` (screenshots and step replay for anyone on the team).
-   - **Linked, run not on the cloud** → the reason from step E and its remedy, e.g. `Cloud: queued — retries on the next iamu sync` or `Cloud: not pushed — <reason>`.
-   - **Linked, no credentials** → `Cloud: not pushed — this machine has no credentials; iamu auth login restores them.`
-   - **Sync conflicts or pending deletions** (step E) → one line each: name the findings a teammate changed and give the CLI's resolution (`iamu pull --force` to take theirs after copying your edits aside, or `iamu sync --keep-mine` to keep yours — the user runs that one); for deletions, tell the user to review them and run `iamu sync --confirm-deletes` themselves.
-   - **Local-only** → nothing, with one exception: on the project's first completed run (`iamu status --json` → `runs.count` is 1), add `Want a link to share this report? iamu auth login connects the project to Iamu Cloud — optional, everything keeps working locally.` Never repeat it on later runs unless the user asks how to share a report.
+   - **Linked, run not on the cloud** → the reason from step E and its remedy, e.g. `Cloud: queued — retries on the next iamu sync`.
+   - **Local-only** → on first completed run: `Want a link to share this report? iamu auth login connects to Iamu Cloud — optional, everything keeps working locally.`
 
-7. **End with a verb**: "Which ones should I fix? (You can also dismiss any finding — it won't show up in future runs.)"
+7. **Next actions (Conversational Triage)**:
 
-**Stay conversational.** The user says "fix 1 and 2" → you read the finding details from the canonical JSON (already in your context from the canonical assembly), look at the relevant code, and make the fix. Mark findings addressed by editing their frontmatter (`triage_status: addressed`, `triage_note: "..."`) as you go.
+   Conclude your report with clear conversational prompts instead of raw terminal commands:
+
+   ```
+   What would you like to do?
+     • "walk through them"    → Review findings one by one with persona context & code location
+     • "fix 1 and 2"          → Have me implement code fixes directly
+     • "discuss 2"            → Ask why the persona hit this friction or explore trade-offs
+     • "skip 3" / "dismiss 3" → Dismiss finding (out of scope, intended, or walker error)
+     • "re-run"               → Re-run walkthrough to verify fixes
+   ```
 
-If the user says "skip 3" or "not relevant" or "dismiss" for a finding, set `triage_status: dismissed` with a `triage_note` explaining why. **Tell the user:** "Dismissed — this won't be reported in any future walkthrough."
+### 6. Conversational Triage & Guided Review
+
+The conversation is the triage surface. Do NOT eject the user to manual CLI commands or dump them at file paths.
+
+#### A. Guided One-by-One Review ("walk through them" / "review one by one")
+When the user asks to review findings one by one:
+1. **Present Finding #N in isolation**:
+   - Number, severity, type, and title
+   - Persona consequence quote and why the friction occurred
+   - Relevant source code location (inspect project files to provide file path + line numbers)
+   - Step & screenshot evidence ([view](iamu/.runs/<run-id>/screenshots/<NNN>.png))
+   - Actionable recommendation
+   - Clear options prompt:
+     `Options: [Fix now]  [Skip / Dismiss]  [Discuss / Why]  [Next finding]`
+
+2. **Handle the user's decision**:
+   - **Fix now**:
+     Make the code edit, verify it loads (or check local tests/types), update the finding's frontmatter (`triage_status: addressed`, `triage_note: "<summary of fix>"`).
+     Tell the user the fix is applied and ask: "Ready for finding #<N+1>?".
+   - **Skip / Dismiss**:
+     If reason is not specified, ask or infer the appropriate category:
+     - `out_of_scope`: Not relevant to this project/flow scope.
+     - `not_relevant`: By design / intended behavior.
+     - `walker_error`: Walker misread the screen or made a navigational error.
+     - `duplicate`: Duplicate of another finding.
+     Execute: `iamu triage <slug> --status dismissed --reason <reason> --note "<why>"`.
+     Tell the user: "Dismissed as `<reason>` — created guidance rule in `iamu/guidance/<slug>.md` so future walkthroughs will not report this."
+     Then advance to finding #<N+1>.
+   - **Discuss / Why**:
+     Analyze why the persona experienced this friction, cite the persona brief and steps/screenshots, evaluate whether competitor tools solve this pattern, and give a direct opinion on whether it's worth fixing.
+   - **Next**:
+     Leave open (or set `triage_status: deferred` with note) and advance to finding #<N+1>.
+
+3. **Wrap up after all findings are reviewed**:
+   - Run `iamu validate --all`.
+   - In linked mode, run `iamu sync --json` once so teammates see the triage decisions.
+   - Suggest re-running the walkthrough: `iamu-run <scenario-slug>` to verify fixes.
+
+#### B. Direct Batch Actions ("fix 1 and 2", "fix all critical")
+Read the finding details from the canonical JSON (already in context), inspect the code, make the edits, and update frontmatter to `triage_status: addressed` with `triage_note`.
+
+#### C. Ad-hoc Questions & Challenges ("why did Karl do that?", "is #2 really a bug?")
+Answer directly using persona brief context and step evidence. If the walker got confused or misinterpreted intended behavior, recommend dismissing as `walker_error` or `not_relevant` rather than adding unnecessary code.
 
 **Linked mode: publish triage decisions.** When the user is done fixing and dismissing, run `iamu sync --json` once so teammates see the decisions (and any team request for these findings closes). Report it in one line (`Synced 3 findings to Iamu Cloud.`), with conflicts handled as in item 6. Do not sync after every single edit.
 

package/dist/templates/skills/iamu-setup.md

@@ -137,16 +137,17 @@ Persist the step-2 summary as structured fields so every scenario draft and walk
 
 4. **Scaffold confirmed personas (unless `skip-personas` selected):**
 
-   Always use the CLI to scaffold valid persona entities with schema-compliant UUIDs, slugs, and timestamps:
+   Use the CLI to scaffold valid persona entities with schema-compliant UUIDs, slugs, frontmatter, and narrative body in a single command:
    ```bash
-   iamu new persona --name "<Name>" --role "<Role>" --disposition "<Disposition>" --json
+   iamu new persona --name "<Name>" --role "<Role>" --disposition "<Disposition>" --body "<2-4 sentence narrative detailing technical habits, patience level, and specific friction triggers>" [--access "<account-or-role>"] --json
    ```
 
-   Then open the created file (`iamu/personas/<slug>.md`) and write 2–4 sentences of background narrative into the markdown body below the frontmatter, detailing their technical habits, patience level, and specific friction triggers.
+   If `iamu/context.yml` specifies an `access` mechanism, pass `--access "<role>"` matching an existing product account/role.
 
-   If `iamu/context.yml` has an `access` mechanism, set the persona's `access` field in frontmatter to match an existing product account/role.
-
-   Run `iamu validate --all`.
+   Once all confirmed personas are created, run validation once:
+   ```bash
+   iamu validate --all
+   ```
 
 5. Confirm: "Context saved and personas seeded in iamu/personas/. Run `iamu-new` to draft your first scenario." (or "Context saved. Run `iamu-new` to draft your first scenario." if personas were skipped).
 
@@ -172,11 +173,15 @@ Three outcomes:
 
 **Linking:**
 
-1. Run `iamu auth login` (add `--url <api-url>` only if the user names a self-hosted cloud). It opens the sign-in page in the user's browser and waits up to two minutes — tell the user to approve it there. Allow the command at least 150 seconds before your shell tool times out. If your shell cannot wait that long, or runs where no browser can open (remote or container session), ask the user to run `iamu auth login` in their own terminal and tell you when it is done.
-2. **Never pick the cloud project for the user.** In a non-interactive shell with existing cloud projects, login stops after sign-in and lists them as `iamu auth login --project <id>` lines plus `--project new`. Show that list, ask which project this repository belongs to, then re-run with their choice — the stored sign-in is reused, no second browser trip. Linking pushes every local persona, scenario and finding into the chosen project; a wrong guess leaks them into someone else's.
-3. On success the output ends with `Dashboard: <url>` and, when an agent host was detected, `iamu-sync MCP server registered`. Relay both in two lines: the dashboard link, and that restarting the agent session loads the team tools (work requests, teammate-change alerts).
+1. Tell the user: "Opening browser for Iamu Cloud login..." then run `iamu auth login`. Allow the command at least 150 seconds for the user to complete sign-in in their browser. If your shell cannot wait that long, or runs where no browser can open (remote or container session), ask the user to run `iamu auth login` in their own terminal and tell you when it is done.
+2. **Never pick the cloud project for the user.** In a non-interactive shell with existing cloud projects, login stops after sign-in and lists them as `iamu auth login --project <id>` lines plus `--project new`. Show that list, ask which project this repository belongs to, then re-run with their choice — the stored sign-in is reused, no second browser trip.
+3. On success the output ends with `Dashboard: <url>` and, when an agent host was detected, `iamu-sync MCP server registered`. Relay both: the dashboard link, and that restarting the agent session loads the team tools (work requests, teammate-change alerts).
 
-If login fails (cloud unreachable, sign-in timed out), report the error in one line and continue — setup is complete without the cloud.
+If login times out or fails (cloud unreachable, sign-in timed out, or network error):
+- Explain clearly what happened: "Cloud linking could not be completed (<echo specific reason from command output>)."
+- Reassure the user: "Your local project setup is 100% complete and fully functional. Personas, scenarios, outlines, and walkthroughs run locally without cloud."
+- Provide the next step for linking: "You can link to Iamu Cloud anytime later by running `iamu auth login` in your terminal."
+- Point to the next creative action: "Next: run `iamu-new` to draft your first scenario."
 
 All three outcomes leave a usable local setup. Cloud is strictly additive.
 

package/dist/templates/skills/iamu-status.md

@@ -21,24 +21,28 @@ $ARGUMENTS
 
 Do NOT use `find`, `grep`, or `cat` to dump raw `.md` files in `iamu/`. The CLI outputs clean, validated data.
 
-### 2. Format entity responses as compact tables
+### 2. Format entity responses with an executive tally and clickable links
 
-When the user asks for personas, scenarios, or findings, respond with a scannable Markdown table. Never dump full psychological profiles, vocabulary lists, or raw frontmatter unless the user explicitly asks for deep detail on one entity.
+When the user asks for project status, lead with an executive tally banner, followed by scannable tables with clickable markdown file links:
+
+```
+Project Status: <P> Personas · <S> Scenarios (<R> Tested, <U> Untested) · <F> Open Findings · <C> Capabilities
+```
 
 **Personas:**
 | Slug | Name | Role | Status |
 |---|---|---|---|
-| `elin-dahl` | Elin Dahl | Architect & first-time house owner in Falun | active |
+| [`elin-dahl`](iamu/personas/elin-dahl.md) | Elin Dahl | Architect & first-time house owner in Falun | active |
 
 **Scenarios:**
 | Slug | Persona | Outline | Status / Target |
 |---|---|---|---|
-| `replacing-windows` | `elin-dahl` | `measure-and-order` | ready |
+| [`replacing-windows`](iamu/scenarios/replacing-windows.md) | [`elin-dahl`](iamu/personas/elin-dahl.md) | [`measure-and-order`](iamu/outlines/measure-and-order.md) | ready |
 
 **Findings:**
-| # | Severity | Type | Finding | Status |
+| # | Severity | Type | Finding | File |
 |---|---|---|---|---|
-| 1 | CRITICAL | hinders | Submit fails opaquely on empty field | open |
+| 1 | CRITICAL | hinders | Submit fails opaquely on empty field | [`view`](iamu/findings/<slug>.md) |
 
 ### 3. Ignore internal templates
 
@@ -52,13 +56,16 @@ For a project-status question, add one line on the cloud from `iamu status --jso
 - **Linked, no credentials** → `Cloud: linked, but this machine has no credentials — iamu auth login.`
 - **Local-only** → `Cloud: local-only.` Nothing more; no upgrade pitch.
 
-### 5. Provide clear next steps
+### 5. Provide copy-pasteable next actions
+
+Conclude with exact copy-pasteable commands:
 
-Conclude with one concise action prompt:
-- To run a scenario: `iamu-run <scenario-slug>`
-- To propose new personas or scenarios: `iamu-propose`
-- To draft a persona or scenario directly: `iamu-new`
-- To review open findings or team requests: `iamu-findings`
-- To inspect reports: `iamu report`, or `iamu open` for the cloud dashboard (linked projects)
-- To share unpushed work with the team: `iamu sync` (linked projects)
+```
+Next actions:
+  iamu-run <scenario-slug>              # Run a walkthrough for this scenario
+  iamu-propose                          # Propose missing personas or scenarios
+  iamu-new                              # Draft a new scenario or persona
+  iamu-findings                         # Triage open findings
+  iamu open                             # Open project in cloud dashboard
+```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamu-dev/iamu",
-  "version": "0.2.0-beta.3",
+  "version": "0.2.0-beta.5",
   "type": "module",
   "description": "Test your product as realistic personas — scenario-driven development CLI",
   "license": "UNLICENSED",
@@ -58,8 +58,8 @@
     "typescript": "^5.8.0",
     "vitest": "^4.1.11",
     "@iamu-dev/local-store": "0.1.0",
-    "@iamu-dev/protocol": "0.1.0",
-    "@iamu/tsconfig": "0.1.0"
+    "@iamu/tsconfig": "0.1.0",
+    "@iamu-dev/protocol": "0.1.0"
   },
   "scripts": {
     "build": "tsup && tsc -b tsconfig.build.json --emitDeclarationOnly && node scripts/copy-assets.mjs",