@iamu-dev/iamu 0.3.0-beta.0 → 0.3.0-beta.1

package/dist/index.js

@@ -5459,10 +5459,20 @@ async function readTestability(projectRoot) {
     body: parsed.body
   };
 }
+async function writeTestability(projectRoot, input, body) {
+  const p = testabilityPath(projectRoot);
+  const isLocalDoc = "frontmatter" in input && typeof input.frontmatter === "object";
+  const fm = isLocalDoc ? input.frontmatter : input;
+  const effectiveBody = body !== void 0 ? body : isLocalDoc ? input.body : "";
+  const validated = testabilityFrontmatterSchema.parse(fm);
+  const serialized = serializeFrontmatter(validated, effectiveBody);
+  await atomicWriteFile(p, serialized);
+}
 var init_testability2 = __esm({
   "../../packages/local-store/dist/testability.js"() {
     "use strict";
     init_dist();
+    init_atomic();
     init_markdown();
     init_paths();
   }
@@ -8621,7 +8631,7 @@ function formatRefError(err) {
   const dir = ENTITY_DIRS[err.missing_ref];
   const hint = MISSING_REF_HINTS[err.missing_ref] ?? "";
   if (!err.missing_slug) {
-    const fieldHint = err.missing_ref === "capability" && err.entity_type === "outline" ? "add `primary_capability:` to the outline frontmatter" : `add a \`${err.missing_ref}:\` field to the file`;
+    const fieldHint = err.missing_ref === "capability" && err.entity_type === "outline" ? `run \`iamu set outline ${err.entity_slug ?? "<slug>"} --capability <slug>\`` : `add a \`${err.missing_ref}:\` field to the file`;
     return `${err.entity_type} ${err.entity_slug || err.entity_id}: ${err.missing_ref} slug is missing from frontmatter \u2014 ${fieldHint}`;
   }
   return `${err.entity_type} ${err.entity_slug || err.entity_id}: \`${err.missing_slug}\` not found in iamu/${dir}/${hint}`;
@@ -8635,7 +8645,7 @@ var init_refs = __esm({
     init_sync_tracking();
     init_walkthrough_mirror();
     MISSING_REF_HINTS = {
-      capability: " \u2014 create it with `iamu new capability` or check the slug in frontmatter",
+      capability: " \u2014 create it with `iamu new capability` or set with `iamu set outline <slug> --capability <slug>`",
       outline: " \u2014 create it with `iamu new` or verify the slug matches a file in iamu/outlines/",
       persona: " \u2014 create it with `iamu new persona` or check the slug",
       scenario: " \u2014 verify the scenario exists locally with `iamu list scenarios`"
@@ -13581,8 +13591,8 @@ import { dirname as dirname3, join as join4, resolve as resolve2 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import chalk6 from "chalk";
 function getVersion() {
-  if ("0.3.0-beta.0") {
-    return "0.3.0-beta.0";
+  if ("0.3.0-beta.1") {
+    return "0.3.0-beta.1";
   }
   try {
     const thisDir = dirname3(fileURLToPath2(import.meta.url));
@@ -20818,6 +20828,15 @@ function validateFile(filePath, raw, projectRoot) {
       );
     }
   }
+  if (type2 === "outline" && zodResult.success) {
+    const fm = zodResult.data;
+    if (!fm.primary_capability && !fm.capability) {
+      result.warnings = result.warnings ?? [];
+      result.warnings.push(
+        `outline has no primary capability \u2014 sync will require one (run \`iamu set outline ${fm.slug ?? "<slug>"} --capability <slug>\`)`
+      );
+    }
+  }
   return result;
 }
 async function buildRepairLookups(projectRoot) {
@@ -21386,6 +21405,15 @@ async function newEntity(type2, opts) {
     );
     return;
   }
+  if (entityType === "outline" && !opts.capability) {
+    try {
+      const { entities } = await listEntities(projectRoot, "capability");
+      if (entities.length === 1 && typeof entities[0].frontmatter.slug === "string") {
+        opts.capability = entities[0].frontmatter.slug;
+      }
+    } catch {
+    }
+  }
   const id = randomUUID10();
   const frontmatter = defaultFrontmatter(entityType, id, slug, opts.name, opts);
   const body = opts.body ?? (entityType === "outline" ? "" : opts.narrative) ?? "";
@@ -21504,6 +21532,42 @@ function applyChanges(type2, fm, opts) {
       put("paths", paths);
     }
     if (opts.area !== void 0) put("area", opts.area || null);
+  } else if (type2 === "outline") {
+    if (opts.capability === false) {
+      put("primary_capability", null);
+      put("capability", null);
+    } else if (opts.capability !== void 0) {
+      put("primary_capability", opts.capability || null);
+      put("capability", opts.capability || null);
+    }
+    if (opts.additionalCapabilities === false) {
+      put("additional_capabilities", []);
+    } else if (opts.additionalCapabilities !== void 0) {
+      const caps = typeof opts.additionalCapabilities === "string" ? splitList(opts.additionalCapabilities) : Array.isArray(opts.additionalCapabilities) ? opts.additionalCapabilities : [];
+      put("additional_capabilities", caps);
+    }
+  } else if (type2 === "testability") {
+    if (opts.target !== void 0) put("target_url", opts.target || null);
+    if (opts.devCommand !== void 0)
+      put("dev_command", opts.devCommand || null);
+    if (opts.authStrategy !== void 0)
+      put("auth_strategy", opts.authStrategy || null);
+    if (opts.access !== void 0) put("access", opts.access || null);
+    if (opts.harnesses !== void 0) {
+      put("harnesses", opts.harnesses ? splitList(opts.harnesses) : null);
+    }
+    if (opts.untestableBoundaries !== void 0) {
+      put(
+        "untestable_boundaries",
+        opts.untestableBoundaries ? splitList(opts.untestableBoundaries) : null
+      );
+    }
+  } else if (type2 === "context") {
+    if (opts.domain !== void 0) put("domain", opts.domain || null);
+    if (opts.industry !== void 0) put("industry", opts.industry || null);
+    if (opts.jurisdiction !== void 0)
+      put("jurisdiction", opts.jurisdiction || null);
+    if (opts.notes !== void 0) put("notes", opts.notes || null);
   }
   return changed;
 }
@@ -21519,6 +21583,15 @@ async function setEntity(type2, slug, opts) {
     );
     return;
   }
+  if (type2 !== "testability" && type2 !== "context" && !slug) {
+    commandError(`A slug is required when setting a ${type2}.`, {
+      ...opts,
+      code: "missing_slug",
+      fix: `iamu set ${type2} <slug>`
+    });
+    return;
+  }
+  const effectiveSlug = slug || type2;
   const foreign = Object.keys(FLAG_NAMES).filter(
     (k) => !allowed.includes(k) && given(opts, k)
   );
@@ -21528,7 +21601,7 @@ async function setEntity(type2, slug, opts) {
       {
         ...opts,
         code: "invalid_field_combination",
-        fix: `iamu set ${type2} ${slug} ${FLAG_NAMES[allowed[0]]} ...`
+        fix: `iamu set ${type2} ${effectiveSlug} ${FLAG_NAMES[allowed[0]]} ...`
       }
     );
     return;
@@ -21569,7 +21642,38 @@ async function setEntity(type2, slug, opts) {
     const allowedPatchKeys = {
       scenario: ["entry", "entry_path", "target", "target_url", "state"],
       persona: ["access"],
-      capability: ["paths", "addPath", "removePath", "area"]
+      capability: ["paths", "addPath", "removePath", "area"],
+      outline: [
+        "capability",
+        "primary_capability",
+        "additional_capabilities",
+        "additionalCapabilities"
+      ],
+      testability: [
+        "target",
+        "target_url",
+        "devCommand",
+        "dev_command",
+        "authStrategy",
+        "auth_strategy",
+        "access",
+        "harnesses",
+        "untestableBoundaries",
+        "untestable_boundaries",
+        "body"
+      ],
+      context: [
+        "domain",
+        "industry",
+        "jurisdiction",
+        "notes",
+        "description",
+        "name",
+        "governed_by",
+        "actors",
+        "terminology",
+        "body"
+      ]
     };
     const foreignPatchKeys = Object.keys(parsed).filter(
       (k) => !allowedPatchKeys[type2]?.includes(k)
@@ -21628,6 +21732,65 @@ async function setEntity(type2, slug, opts) {
       if (effectiveOpts.area === void 0 && parsed.area !== void 0) {
         effectiveOpts.area = parsed.area === null || parsed.area === false ? false : String(parsed.area);
       }
+    } else if (type2 === "outline") {
+      if (effectiveOpts.capability === void 0 && (parsed.capability !== void 0 || parsed.primary_capability !== void 0)) {
+        const v = parsed.capability ?? parsed.primary_capability;
+        effectiveOpts.capability = v === null || v === false ? false : String(v);
+      }
+      if (effectiveOpts.additionalCapabilities === void 0 && (parsed.additionalCapabilities !== void 0 || parsed.additional_capabilities !== void 0)) {
+        const v = parsed.additionalCapabilities ?? parsed.additional_capabilities;
+        effectiveOpts.additionalCapabilities = v === null || v === false ? false : Array.isArray(v) ? v.join(",") : String(v);
+      }
+    } else if (type2 === "testability") {
+      if (effectiveOpts.target === void 0 && (parsed.target !== void 0 || parsed.target_url !== void 0)) {
+        const v = parsed.target ?? parsed.target_url;
+        effectiveOpts.target = v === null || v === false ? false : String(v);
+      }
+      if (effectiveOpts.devCommand === void 0 && (parsed.devCommand !== void 0 || parsed.dev_command !== void 0)) {
+        const v = parsed.devCommand ?? parsed.dev_command;
+        effectiveOpts.devCommand = v === null || v === false ? false : String(v);
+      }
+      if (effectiveOpts.authStrategy === void 0 && (parsed.authStrategy !== void 0 || parsed.auth_strategy !== void 0)) {
+        const v = parsed.authStrategy ?? parsed.auth_strategy;
+        effectiveOpts.authStrategy = v === null || v === false ? false : String(v);
+      }
+      if (effectiveOpts.access === void 0 && parsed.access !== void 0) {
+        effectiveOpts.access = parsed.access === null || parsed.access === false ? false : String(parsed.access);
+      }
+      if (effectiveOpts.harnesses === void 0 && parsed.harnesses !== void 0) {
+        effectiveOpts.harnesses = parsed.harnesses === null || parsed.harnesses === false ? false : Array.isArray(parsed.harnesses) ? parsed.harnesses.join(",") : String(parsed.harnesses);
+      }
+      if (effectiveOpts.untestableBoundaries === void 0 && (parsed.untestableBoundaries !== void 0 || parsed.untestable_boundaries !== void 0)) {
+        const b = parsed.untestableBoundaries ?? parsed.untestable_boundaries;
+        effectiveOpts.untestableBoundaries = b === null || b === false ? false : Array.isArray(b) ? b.join(",") : String(b);
+      }
+      if (effectiveOpts.body === void 0 && parsed.body !== void 0) {
+        effectiveOpts.body = String(parsed.body);
+      }
+    } else if (type2 === "context") {
+      if (effectiveOpts.domain === void 0 && parsed.domain !== void 0) {
+        effectiveOpts.domain = parsed.domain === null || parsed.domain === false ? false : String(parsed.domain);
+      }
+      if (effectiveOpts.industry === void 0 && parsed.industry !== void 0) {
+        effectiveOpts.industry = parsed.industry === null || parsed.industry === false ? false : String(parsed.industry);
+      }
+      if (effectiveOpts.jurisdiction === void 0 && parsed.jurisdiction !== void 0) {
+        effectiveOpts.jurisdiction = parsed.jurisdiction === null || parsed.jurisdiction === false ? false : String(parsed.jurisdiction);
+      }
+      if (effectiveOpts.notes === void 0 && parsed.notes !== void 0) {
+        effectiveOpts.notes = parsed.notes === null || parsed.notes === false ? false : String(parsed.notes);
+      }
+      if (effectiveOpts.description === void 0 && parsed.description !== void 0) {
+        effectiveOpts.description = parsed.description === null || parsed.description === false ? false : String(parsed.description);
+      }
+      if (effectiveOpts.name === void 0 && parsed.name !== void 0) {
+        effectiveOpts.name = parsed.name === null || parsed.name === false ? false : String(parsed.name);
+      }
+      if (effectiveOpts.body === void 0 && parsed.body !== void 0) {
+        effectiveOpts.body = String(parsed.body);
+      } else if (effectiveOpts.body === void 0 && effectiveOpts.description !== void 0) {
+        effectiveOpts.body = effectiveOpts.description ? String(effectiveOpts.description) : "";
+      }
     }
   }
   if (!allowed.some((k) => given(effectiveOpts, k))) {
@@ -21636,11 +21799,112 @@ async function setEntity(type2, slug, opts) {
       {
         ...opts,
         code: "nothing_to_set",
-        fix: `iamu set ${type2} ${slug} ${FLAG_NAMES[allowed[0]]} ...`
+        fix: `iamu set ${type2}${type2 === "testability" || type2 === "context" ? "" : ` ${effectiveSlug}`} ${FLAG_NAMES[allowed[0]]} ...`
       }
     );
     return;
   }
+  if (type2 === "testability") {
+    const doc = await readTestability(projectRoot) ?? {
+      frontmatter: {
+        schema_version: 1,
+        status: "draft",
+        target_url: "http://localhost:3000"
+      },
+      body: ""
+    };
+    const fm2 = { ...doc.frontmatter };
+    const changed2 = applyChanges(type2, fm2, effectiveOpts);
+    let body = doc.body;
+    if (effectiveOpts.body !== void 0) {
+      body = effectiveOpts.body;
+      changed2.push("body");
+    }
+    const writtenPath2 = testabilityPath(projectRoot);
+    try {
+      await writeTestability(
+        projectRoot,
+        fm2,
+        body
+      );
+    } catch (err) {
+      const message = err instanceof ZodError2 ? err.issues.map((i) => `${i.path.join(".") || "root"}: ${i.message}`).join("; ") : err instanceof Error ? err.message : String(err);
+      commandError(`Could not set testability: ${message}`, {
+        ...opts,
+        code: "testability_write_error",
+        fix: "iamu set testability --target <url>"
+      });
+      return;
+    }
+    if (opts.json) {
+      console.log(
+        JSON.stringify({
+          slug: "testability",
+          type: "testability",
+          path: writtenPath2,
+          changed: changed2
+        })
+      );
+      return;
+    }
+    console.log();
+    console.log(
+      `  ${symbols.success} Updated testability: ${changed2.join(", ")}`
+    );
+    console.log(`  ${chalk28.dim("path:")} ${writtenPath2}`);
+    console.log();
+    return;
+  }
+  if (type2 === "context") {
+    const doc = await readContext(projectRoot) ?? {
+      frontmatter: {
+        schema_version: SCHEMA_VERSION,
+        status: "draft"
+      },
+      notes_body: ""
+    };
+    const fm2 = { ...doc.frontmatter };
+    const changed2 = applyChanges(type2, fm2, effectiveOpts);
+    let body = doc.notes_body;
+    if (effectiveOpts.body !== void 0) {
+      body = effectiveOpts.body;
+      changed2.push("body");
+    } else if (effectiveOpts.description !== void 0) {
+      body = effectiveOpts.description ? String(effectiveOpts.description) : "";
+      changed2.push("body");
+    }
+    const writtenPath2 = contextPath(projectRoot);
+    try {
+      await writeContext(projectRoot, {
+        frontmatter: fm2,
+        notes_body: body
+      });
+    } catch (err) {
+      const message = err instanceof ZodError2 ? err.issues.map((i) => `${i.path.join(".") || "root"}: ${i.message}`).join("; ") : err instanceof Error ? err.message : String(err);
+      commandError(`Could not set context: ${message}`, {
+        ...opts,
+        code: "context_write_error",
+        fix: "iamu set context --domain <domain>"
+      });
+      return;
+    }
+    if (opts.json) {
+      console.log(
+        JSON.stringify({
+          slug: "context",
+          type: "context",
+          path: writtenPath2,
+          changed: changed2
+        })
+      );
+      return;
+    }
+    console.log();
+    console.log(`  ${symbols.success} Updated context: ${changed2.join(", ")}`);
+    console.log(`  ${chalk28.dim("path:")} ${writtenPath2}`);
+    console.log();
+    return;
+  }
   if (type2 === "capability") {
     const candidatePaths = [
       ...typeof effectiveOpts.paths === "string" ? splitList(effectiveOpts.paths) : [],
@@ -21653,7 +21917,7 @@ async function setEntity(type2, slug, opts) {
         {
           ...opts,
           code: "invalid_route_prefix",
-          fix: `iamu set ${type2} ${slug} --paths /${invalid[0]?.replace(/^\/+/, "") || ""}`
+          fix: `iamu set ${type2} ${effectiveSlug} --paths /${invalid[0]?.replace(/^\/+/, "") || ""}`
         }
       );
       return;
@@ -21726,7 +21990,25 @@ var init_set_entity = __esm({
         "state"
       ],
       persona: ["access"],
-      capability: ["paths", "addPath", "removePath", "area"]
+      capability: ["paths", "addPath", "removePath", "area"],
+      outline: ["capability", "additionalCapabilities"],
+      testability: [
+        "target",
+        "devCommand",
+        "authStrategy",
+        "access",
+        "harnesses",
+        "untestableBoundaries",
+        "body"
+      ],
+      context: [
+        "domain",
+        "industry",
+        "jurisdiction",
+        "notes",
+        "description",
+        "body"
+      ]
     };
     FLAG_NAMES = {
       entry: "--entry",
@@ -21738,7 +22020,20 @@ var init_set_entity = __esm({
       paths: "--paths",
       addPath: "--add-path",
       removePath: "--remove-path",
-      area: "--area"
+      area: "--area",
+      capability: "--capability",
+      additionalCapabilities: "--additional-capabilities",
+      devCommand: "--dev-command",
+      authStrategy: "--auth-strategy",
+      harnesses: "--harnesses",
+      untestableBoundaries: "--untestable-boundaries",
+      domain: "--domain",
+      industry: "--industry",
+      jurisdiction: "--jurisdiction",
+      notes: "--notes",
+      description: "--description",
+      name: "--name",
+      body: "--body"
     };
   }
 });
@@ -22999,7 +23294,7 @@ __export(instructions_walk_exports, {
   revisitSection: () => revisitSection,
   viewportLine: () => viewportLine
 });
-import { existsSync as existsSync16, readFileSync as readFileSync9 } from "fs";
+import { existsSync as existsSync16, readFileSync as readFileSync9, writeFileSync as writeFileSync4 } from "fs";
 import { join as join9 } from "path";
 import chalk31 from "chalk";
 function selfCommand() {
@@ -23386,8 +23681,17 @@ async function instructionsWalk(opts) {
       state: sfm.state ?? null,
       context: contextYml,
       untestableBoundaries
-    }) : null
+    }) : null,
+    walker_prompt_path: null
   };
+  if (runDirPath && result.walker_prompt) {
+    try {
+      const promptPath = join9(runDirPath, "walker_prompt.txt");
+      writeFileSync4(promptPath, result.walker_prompt, "utf-8");
+      result.walker_prompt_path = promptPath;
+    } catch {
+    }
+  }
   if (opts.json) {
     console.log(JSON.stringify(result, null, 2));
     return;
@@ -24408,13 +24712,25 @@ async function evaluateRecord(runId, opts) {
     });
     return;
   }
+  const defaultVerdictsPath = path34.join(runDirPath, "verdicts.json");
   if (!opts.file && !opts.data) {
-    commandError("Either --file <path> or --data <json> is required", {
-      ...opts,
-      code: "missing_verdicts_input",
-      fix: "iamu evaluate-record --file verdicts.json"
-    });
-    return;
+    let hasExisting = false;
+    try {
+      await fs32.access(defaultVerdictsPath);
+      hasExisting = true;
+    } catch {
+      hasExisting = false;
+    }
+    if (hasExisting) {
+      opts.file = defaultVerdictsPath;
+    } else {
+      commandError("Either --file <path> or --data <json> is required", {
+        ...opts,
+        code: "missing_verdicts_input",
+        fix: `iamu evaluate-record ${runId} --data '<json>'`
+      });
+      return;
+    }
   }
   let parsedFile;
   try {
@@ -25371,13 +25687,25 @@ async function matchRecord(runId, opts) {
   });
   const manifest = await completedManifest2(runDirPath, runId, opts);
   if (!manifest) return;
+  const defaultMatchesPath = path36.join(runDirPath, "matches.json");
   if (!opts.file && !opts.data) {
-    commandError("Either --file <path> or --data <json> is required", {
-      ...opts,
-      code: "missing_matches_input",
-      fix: "iamu match-record --file matches.json"
-    });
-    return;
+    let hasExisting = false;
+    try {
+      await fs34.access(defaultMatchesPath);
+      hasExisting = true;
+    } catch {
+      hasExisting = false;
+    }
+    if (hasExisting) {
+      opts.file = defaultMatchesPath;
+    } else {
+      commandError("Either --file <path> or --data <json> is required", {
+        ...opts,
+        code: "missing_matches_input",
+        fix: `iamu match-record ${runId} --data '<json>'`
+      });
+      return;
+    }
   }
   let answer;
   try {
@@ -25811,12 +26139,12 @@ function registerProjectCommands(program) {
       await newEntity2(type2, opts);
     }
   );
-  program.command("set <type> <slug>").helpGroup("Project:").description(
-    "Change how an entity is staged: a scenario's start path, target and starting state, a persona's access key, a capability's routes (scenario, persona, capability)"
+  program.command("set <type> [slug]").helpGroup("Project:").description(
+    "Change how an entity is staged: a scenario's start path, target and starting state, a persona's access key, a capability's routes, or project testability / context (scenario, persona, capability, testability, context)"
   ).option(
     "--entry <path>",
     "Where the walk starts, as a path on the product (scenario)"
-  ).option("--no-entry", "Clear the start path (scenario)").option("--target <url>", "Default target URL (scenario)").option("--no-target", "Clear the default target URL (scenario)").option(
+  ).option("--no-entry", "Clear the start path (scenario)").option("--target <url>", "Default target URL (scenario, testability)").option("--no-target", "Clear the default target URL (scenario)").option(
     "--state-description <text>",
     "What the world must contain, in domain words (scenario)"
   ).option(
@@ -25824,8 +26152,8 @@ function registerProjectCommands(program) {
     "How the walker picks the closest record when the exact one is missing (scenario)"
   ).option("--no-state", "Clear the starting state (scenario)").option(
     "--access <key>",
-    "Account, role or switcher key this persona uses (persona)"
-  ).option("--no-access", "Clear the access key (persona)").option(
+    "Account, role or switcher key this persona uses (persona, testability)"
+  ).option("--no-access", "Clear the access key (persona, testability)").option(
     "--paths <paths>",
     "Route prefixes, comma-separated; replaces the list (capability)"
   ).option("--no-paths", "Clear route prefixes (capability)").option(
@@ -25836,12 +26164,27 @@ function registerProjectCommands(program) {
     "--remove-path <path>",
     "Remove a route prefix (capability, repeatable)",
     (val, prev = []) => [...prev, val]
-  ).option("--area <name>", "Visual grouping category (capability)").option("--no-area", "Clear the area (capability)").option(
+  ).option("--area <name>", "Visual grouping category (capability)").option("--no-area", "Clear the area (capability)").option("--capability <slug>", "Primary capability slug (outline)").option("--no-capability", "Clear primary capability (outline)").option(
+    "--additional-capabilities <slugs>",
+    "Secondary capability slugs, comma-separated (outline)"
+  ).option(
+    "--no-additional-capabilities",
+    "Clear secondary capabilities (outline)"
+  ).option("--dev-command <cmd>", "Dev startup command (testability)").option("--no-dev-command", "Clear dev startup command (testability)").option("--auth-strategy <strategy>", "Auth strategy (testability)").option("--no-auth-strategy", "Clear auth strategy (testability)").option(
+    "--harnesses <list>",
+    "Mock frameworks or seed scripts, comma-separated (testability)"
+  ).option("--no-harnesses", "Clear harnesses (testability)").option(
+    "--untestable-boundaries <list>",
+    "Forbidden external endpoints, comma-separated (testability)"
+  ).option(
+    "--no-untestable-boundaries",
+    "Clear untestable boundaries (testability)"
+  ).option("--domain <text>", "Domain name (context)").option("--industry <text>", "Industry category (context)").option("--jurisdiction <text>", "Jurisdiction or region (context)").option("--notes <text>", "Orientation notes (context)").option("--description <text>", "Project description (context)").option("--name <text>", "Project name (context)").option("--body <text>", "Markdown narrative body (testability, context)").option(
     "--file <path>",
     "JSON patch file to apply staging fields (or - for stdin)"
   ).option("--json", "Output as JSON").addHelpText(
     "after",
-    '\nWhat a scenario is about (narrative, tension, human tests, brief) is not set here.\n\nExamples:\n  $ iamu set scenario maria--handoff --entry /incidents --state-description "Five open incidents at one site"\n  $ iamu set persona maria --access coordinator@site-a.test\n  $ iamu set capability team-access --add-path /team\n  $ iamu set scenario maria--handoff --file patch.json'
+    '\nWhat a scenario is about (narrative, tension, human tests, brief) is not set here.\n\nExamples:\n  $ iamu set scenario maria--handoff --entry /incidents --state-description "Five open incidents at one site"\n  $ iamu set persona maria --access coordinator@site-a.test\n  $ iamu set outline shift-handoff --capability incident-reporting\n  $ iamu set capability team-access --add-path /team\n  $ iamu set testability --target http://localhost:5173 --dev-command "./dev" --auth-strategy dev_switcher\n  $ iamu set context --domain "Workplace safety" --industry "Manufacturing" --description "..."\n  $ iamu set scenario maria--handoff --file patch.json'
   ).action(
     async (type2, slug, opts) => {
       const { setEntity: setEntity2 } = await Promise.resolve().then(() => (init_set_entity(), set_entity_exports));
@@ -25960,41 +26303,65 @@ function registerWalkthroughCommands(program) {
     "--surface <text>",
     `"browse" (default) for iamu browse, or a description of your own browser tool \u2014 becomes the walker prompt's Driving surface section`
   ).option("--json", "Output as JSON").action(
-    async (phase, slug, opts) => {
+    async (phase, slug, opts, cmd) => {
+      const effectiveOpts = {
+        ...cmd.optsWithGlobals(),
+        ...opts
+      };
       const { instructions: instructions2 } = await Promise.resolve().then(() => (init_instructions(), instructions_exports));
-      await instructions2(phase, slug, opts);
+      await instructions2(phase, slug, effectiveOpts);
     }
   );
   instrCmd.command("walk [scenario-slug]").description("Compose walking prompt from scenario + persona + outline").option("--scenario <slug>", "Scenario slug (default: active scenario)").option("--run <run-id>", "Run ID (resolves target URL from manifest)").option(
     "--surface <text>",
     `"browse" (default) for iamu browse, or a description of your own browser tool \u2014 becomes the walker prompt's Driving surface section`
   ).option("--json", "Output as JSON").action(
-    async (scenarioSlug, opts) => {
+    async (scenarioSlug, opts, cmd) => {
+      const effectiveOpts = {
+        ...cmd.parent?.opts(),
+        ...cmd.optsWithGlobals(),
+        ...opts
+      };
       const { instructionsWalk: instructionsWalk2 } = await Promise.resolve().then(() => (init_instructions_walk(), instructions_walk_exports));
       await instructionsWalk2({
-        ...opts,
-        scenario: scenarioSlug ?? opts.scenario
+        ...effectiveOpts,
+        scenario: scenarioSlug ?? effectiveOpts.scenario
       });
     }
   );
   instrCmd.command("stage [scenario-slug]").description(
     "Dynamic staging instructions: persona, outline, tension, boundaries"
   ).option("--json", "Output as JSON").action(
-    async (scenarioSlug, opts) => {
+    async (scenarioSlug, opts, cmd) => {
+      const effectiveOpts = {
+        ...cmd.parent?.opts(),
+        ...cmd.optsWithGlobals(),
+        ...opts
+      };
       const { instructionsStage: instructionsStage2 } = await Promise.resolve().then(() => (init_instructions(), instructions_exports));
-      await instructionsStage2(scenarioSlug, opts);
+      await instructionsStage2(scenarioSlug, effectiveOpts);
     }
   );
-  instrCmd.command("setup").description("Dynamic project setup instructions & prerequisite checks").option("--json", "Output as JSON").action(async (opts) => {
+  instrCmd.command("setup").description("Dynamic project setup instructions & prerequisite checks").option("--json", "Output as JSON").action(async (opts, cmd) => {
+    const effectiveOpts = {
+      ...cmd.parent?.opts(),
+      ...cmd.optsWithGlobals(),
+      ...opts
+    };
     const { instructionsSetup: instructionsSetup2 } = await Promise.resolve().then(() => (init_instructions(), instructions_exports));
-    await instructionsSetup2(opts);
+    await instructionsSetup2(effectiveOpts);
   });
   instrCmd.command("triage [run-or-scenario-slug]").description(
     "Dynamic triage instructions: finding triage, confirmation, dismissal guidance"
   ).option("--run <run-id>", "Run ID to triage findings for").option("--json", "Output as JSON").action(
-    async (slug, opts) => {
+    async (slug, opts, cmd) => {
+      const effectiveOpts = {
+        ...cmd.parent?.opts(),
+        ...cmd.optsWithGlobals(),
+        ...opts
+      };
       const { instructionsTriage: instructionsTriage2 } = await Promise.resolve().then(() => (init_instructions(), instructions_exports));
-      await instructionsTriage2(slug, opts);
+      await instructionsTriage2(slug, effectiveOpts);
     }
   );
   program.command("browse <command> [args...]").helpGroup("Walkthrough:").description(
@@ -26132,7 +26499,14 @@ 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"
-  ).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(
+  ).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").addHelpText(
+    "after",
+    `
+Examples:
+  $ iamu match-record <run-id> --data '{"matches":[]}'
+  $ iamu match-record <run-id> --file matches.json
+  $ iamu match-record <run-id> --json`
+  ).action(
     async (runId, opts) => {
       const { matchRecord: matchRecord2 } = await Promise.resolve().then(() => (init_match(), match_exports));
       await matchRecord2(runId, opts);
@@ -26146,7 +26520,13 @@ function registerWalkthroughCommands(program) {
   );
   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"
+    `
+Examples:
+  $ iamu evaluate-record <run-id> --data '{"verdicts":[]}' --no-prompt --no-push
+  $ iamu evaluate-record <run-id> --file verdicts.json
+  $ iamu evaluate-record <run-id> --file verdicts.json --no-prompt
+  $ iamu evaluate-record <run-id> --file verdicts.json --no-push
+  $ iamu evaluate-record <run-id> --file verdicts.json --json`
   ).action(
     async (runId, opts) => {
       const { evaluateRecord: evaluateRecord2 } = await Promise.resolve().then(() => (init_evaluate(), evaluate_exports));