@iamu-dev/iamu 0.2.0-beta.17 → 0.2.0-beta.19

package/dist/index.js

@@ -385,7 +385,7 @@ var init_context = __esm({
       jurisdiction: z7.string().max(1024).nullish().describe("Country / region the regulations and policies apply in. Example: 'Sweden', 'EU', 'United States'."),
       architecture: z7.string().max(8192).nullish().describe("High-level architecture notes for the software. Brief is fine \u2014 this is orientation, not spec."),
       notes: z7.string().max(16384).nullish().describe("Additional orientation context that doesn't fit the structured fields. Extended multi-paragraph notes belong in the file body BELOW the frontmatter, not here."),
-      access: z7.string().max(4096).nullish().describe(`How a walker becomes a given user in this product: the switching mechanism, written once for the project. Example: 'No login in dev. In the page, run localStorage.setItem("dev_persona", "<persona access>") and reload.' Each persona's own \`access\` names which user they are. Never put passwords or tokens here \u2014 name where they live instead.`),
+      access: z7.string().max(4096).nullish().describe("Deprecated: belongs in `iamu/testability.md` `access` \u2014 how to switch user is test setup, not domain. Still read as a fallback when testability.md has none."),
       governed_by: z7.array(contextGovernedBySchema).max(64).optional().describe("Regulations / standards / policies the domain is governed by, ordered roughly by authority."),
       actors: z7.array(contextActorSchema).max(64).optional().describe("Key domain roles + their responsibilities."),
       glossary: z7.array(contextGlossaryEntrySchema).max(512).optional().describe("Domain-specific terms the project uses. Flattened into one file locally; the cloud handler splits into the terminology table on push.")
@@ -926,6 +926,7 @@ var init_testability = __esm({
       target_url: z17.string().url().describe("Target URL where the product is hosted or served locally."),
       dev_command: z17.string().max(1e3).optional().describe("Dev script or startup command to boot the app locally."),
       auth_strategy: authStrategyEnum.or(z17.string().min(1).max(100)).optional().describe("How personas authenticate in test environments."),
+      access: z17.string().max(4096).optional().describe(`How a walker becomes a given user in this product: the switching mechanism, written once for the project. Example: 'No login in dev. In the page, run localStorage.setItem("dev_persona", "<persona access>") and reload.' Each persona's own \`access\` names which user they are. Never put passwords or tokens here \u2014 name where they live instead.`),
       harnesses: z17.array(z17.string().min(1).max(500)).max(64).optional().describe("Mocking frameworks, seed scripts, or test harnesses present."),
       untestable_boundaries: z17.array(z17.string().min(1).max(1024)).max(128).optional().describe("External services, third-party APIs, or surfaces forbidden to autonomous walkers.")
     });
@@ -1197,6 +1198,9 @@ var init_walkthrough_bundle = __esm({
       what_worked: z20.array(z20.string().max(4096)).max(64).optional(),
       open_questions: z20.array(z20.string().max(4096)).max(64).optional(),
       verification: bundleVerificationSchema.optional().describe("Since-last-run delta from canonical.json \u2014 which earlier findings persist, were re-checked fixed, were not seen, and which are new. Persists to walkthroughs.verification."),
+      blocked: z20.object({
+        reason: z20.string().min(1).max(2048)
+      }).optional().describe("Set when the walk could not start as set up (missing preconditions)."),
       build: buildMetadataSchema.optional().describe("Build of the product under test (git SHA, branch, CI run). Absent for runs started before `start-run` recorded it."),
       environment: z20.string().min(1).max(ENVIRONMENT_MAX_LENGTH).optional().describe("Where the product ran: `--env <name>` or, by default, the target URL's origin (e.g. `http://localhost:3000`)."),
       /** Holistic UX quality score from UX review pass. Present only when `lenses` includes "ux". */
@@ -1470,7 +1474,12 @@ var init_walkthrough_canonical = __esm({
       human_tests: z21.array(canonicalHumanTestSchema),
       human_test_overall: canonicalHumanTestOverallSchema,
       errors: z21.array(canonicalErrorSchema),
-      cloud_mirror_state: cloudMirrorStateSchema
+      cloud_mirror_state: cloudMirrorStateSchema,
+      /**
+       * The walk could not start as set up (the walker's `iamu summary
+       * --blocked`). Its findings say nothing about earlier ones.
+       */
+      blocked: z21.object({ reason: z21.string() }).passthrough().optional()
     }).passthrough();
   }
 });
@@ -6570,6 +6579,8 @@ async function readRunEvidence(projectRoot) {
       continue;
     if (manifest.status !== "completed")
       continue;
+    if (manifest.blocked)
+      continue;
     const canonical = await readJson(path8.join(dir, "canonical.json"));
     const matches = await readMatches(projectRoot, runId);
     const declared = typeof manifest.started_at === "string" ? manifest.started_at : typeof manifest.created_at === "string" ? manifest.created_at : null;
@@ -7385,7 +7396,8 @@ async function buildCanonical(projectRoot, manifest, completedAt, inputs) {
     // renderers + judge agents can surface them without losing signal.
     // Consumers MUST preserve unknown keys (per design D3).
     ...inputs.what_worked && inputs.what_worked.length > 0 ? { what_worked: inputs.what_worked } : {},
-    ...inputs.open_questions && inputs.open_questions.length > 0 ? { open_questions: inputs.open_questions } : {}
+    ...inputs.open_questions && inputs.open_questions.length > 0 ? { open_questions: inputs.open_questions } : {},
+    ...manifest.blocked ? { blocked: manifest.blocked } : {}
   };
 }
 async function compareWithBaseline(projectRoot, scenarioSlug, currentRunId, currentFindings) {
@@ -7400,7 +7412,7 @@ async function compareWithBaseline(projectRoot, scenarioSlug, currentRunId, curr
       const mPath = path9.join(runDir(projectRoot, rid), "walkthrough.json");
       const raw = await fs12.readFile(mPath, "utf8");
       const m = JSON.parse(raw);
-      if (m.scenario_slug === scenarioSlug && m.status === "completed") {
+      if (m.scenario_slug === scenarioSlug && m.status === "completed" && !m.blocked) {
         baselineRunId = rid;
         baselineManifest = m;
         break;
@@ -7509,6 +7521,13 @@ function renderCanonicalMarkdown(canonical) {
     "",
     `# Walkthrough report: ${canonical.scenario.slug}`,
     "",
+    ...canonical.blocked ? [
+      "> **Blocked \u2014 the walk could not start as it was set up.**",
+      `> ${canonical.blocked.reason}`,
+      ">",
+      "> This run is not compared with earlier runs and proves nothing about earlier findings. Fix the setup (the scenario's starting state or the persona's access) and run it again.",
+      ""
+    ] : [],
     `- Run ID: ${canonical.run_id}`,
     `- Target URL: ${canonical.target.url}`
   ];
@@ -7618,7 +7637,11 @@ function renderCanonicalMarkdown(canonical) {
     for (const ht of canonical.human_tests) {
       lines.push("", `- **${ht.question}**`);
       if (ht.verdict === null) {
-        lines.push(`  - Verdict: _pending judge_ (walker does not self-grade)`);
+        if (canonical.blocked) {
+          lines.push(`  - Verdict: _skipped (walk blocked)_`);
+        } else {
+          lines.push(`  - Verdict: _pending judge_ (walker does not self-grade)`);
+        }
       } else {
         lines.push(`  - Verdict: **${ht.verdict}**`);
         if (ht.reasoning)
@@ -7628,7 +7651,11 @@ function renderCanonicalMarkdown(canonical) {
   }
   lines.push("", "## Human test overall", "", `> ${canonical.human_test_overall.question}`);
   if (canonical.human_test_overall.answer === null) {
-    lines.push("", "_Pending judge stage._");
+    if (canonical.blocked) {
+      lines.push("", "_Skipped (walk blocked)._");
+    } else {
+      lines.push("", "_Pending judge stage._");
+    }
   } else {
     lines.push("", canonical.human_test_overall.answer);
     if (canonical.human_test_overall.reasoning)
@@ -7799,10 +7826,15 @@ async function readCanonicalExtras(projectRoot, runId) {
     const data = JSON.parse(await fs13.readFile(path10.join(runDir(projectRoot, runId), "canonical.json"), "utf-8"));
     const strings = (v) => Array.isArray(v) && v.every((x) => typeof x === "string") ? v : void 0;
     const verification = bundleVerificationSchema.safeParse(data.verification);
+    let blocked;
+    if (typeof data.blocked === "object" && data.blocked !== null && "reason" in data.blocked && typeof data.blocked.reason === "string" && data.blocked.reason.trim().length > 0) {
+      blocked = { reason: data.blocked.reason.trim() };
+    }
     return {
       what_worked: strings(data.what_worked),
       open_questions: strings(data.open_questions),
-      verification: verification.success ? verification.data : void 0
+      verification: verification.success ? verification.data : void 0,
+      ...blocked ? { blocked } : {}
     };
   } catch {
     return {};
@@ -7899,6 +7931,10 @@ async function assembleWalkthroughBundle(projectRoot, runId) {
       }
     } : {}
   } : void 0;
+  const canonicalExtras = await readCanonicalExtras(projectRoot, runId);
+  const rawBlocked = manifest.blocked;
+  const manifestBlocked = typeof rawBlocked === "object" && rawBlocked !== null && "reason" in rawBlocked && typeof rawBlocked.reason === "string" && rawBlocked.reason.trim().length > 0 ? { reason: rawBlocked.reason.trim() } : void 0;
+  const blocked = canonicalExtras.blocked ?? manifestBlocked;
   const bundle = {
     manifest: {
       run_id: cloudRunUuid,
@@ -7916,7 +7952,8 @@ async function assembleWalkthroughBundle(projectRoot, runId) {
       judge_meta: judgeMeta,
       ...manifest.models ? { models: manifest.models } : {},
       ...buildFields(manifest),
-      ...await readCanonicalExtras(projectRoot, runId)
+      ...canonicalExtras,
+      ...blocked ? { blocked } : {}
     },
     steps: bundleSteps,
     findings: bundleFindings,
@@ -10896,6 +10933,26 @@ function summarizeCapabilityCoverage(surfaces, capabilities, outlines = []) {
     unassigned_surfaces: unassigned
   };
 }
+function groupUnassignedByPrefix(surfaces) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const s of surfaces) {
+    const pathOnly = s.place.split(/[?#]/)[0] ?? "";
+    const first = pathOnly.split("/").filter(Boolean)[0];
+    const prefix = first ? `/${first}` : "/";
+    let g = groups.get(prefix);
+    if (!g) {
+      g = { prefix, surfaces: 0, reached: 0, examples: [] };
+      groups.set(prefix, g);
+    }
+    g.surfaces += 1;
+    if (s.status === "reached")
+      g.reached += 1;
+    if (g.examples.length < 3 && !g.examples.includes(pathOnly)) {
+      g.examples.push(pathOnly);
+    }
+  }
+  return [...groups.values()].sort((a, b) => b.surfaces - a.surfaces || a.prefix.localeCompare(b.prefix));
+}
 async function readCapabilityCoverage(projectRoot, coverage) {
   const [capsResult, outlinesResult] = await Promise.all([
     listEntities(projectRoot, "capability"),
@@ -11433,7 +11490,7 @@ function buildPersonaFrontmatter(row, slug) {
   };
   return { frontmatter, body: resolveBody(row, "") };
 }
-function buildScenarioFrontmatter(row, personaSlug, outlineSlug) {
+function buildScenarioFrontmatter(row, personaSlug, outlineSlug, localFrontmatter) {
   const slug = `${personaSlug}--${outlineSlug}`;
   const frontmatter = {
     id: row.id,
@@ -11444,6 +11501,8 @@ function buildScenarioFrontmatter(row, personaSlug, outlineSlug) {
     // writing null wiped the local value on every pull.
     ..."targetUrl" in row ? { target_url: row.targetUrl ?? null } : {},
     ..."entryPath" in row ? { entry_path: row.entryPath ?? null } : {},
+    ..."reviews" in row && Array.isArray(row.reviews) ? { reviews: row.reviews } : localFrontmatter?.reviews !== void 0 ? { reviews: localFrontmatter.reviews } : {},
+    ..."state" in row && row.state !== void 0 ? { state: row.state ?? null } : localFrontmatter?.state !== void 0 ? { state: localFrontmatter.state } : {},
     baseline_score: row.baselineScore ?? null,
     current_score: row.currentScore ?? null,
     target_score: row.targetScore ?? 95,
@@ -11535,6 +11594,7 @@ async function loadLocalIndex(projectRoot, type2) {
   const byId = /* @__PURE__ */ new Map();
   const bySlug = /* @__PURE__ */ new Map();
   const bodyById = /* @__PURE__ */ new Map();
+  const frontmatterById = /* @__PURE__ */ new Map();
   const [result, baseById, lastPushById] = await Promise.all([
     listEntities(projectRoot, type2),
     readBaseHashes(projectRoot),
@@ -11546,9 +11606,10 @@ async function loadLocalIndex(projectRoot, type2) {
       byId.set(fm.id, fm.slug);
       bySlug.set(fm.slug, fm.id);
       bodyById.set(fm.id, entity.body);
+      frontmatterById.set(fm.id, entity.frontmatter);
     }
   }
-  return { byId, bySlug, bodyById, baseById, lastPushById };
+  return { byId, bySlug, bodyById, frontmatterById, baseById, lastPushById };
 }
 async function classifyExisting(projectRoot, type2, cloudId, localSlug, targetSlug, cloudVersion, localIndex) {
   const base = localIndex.baseById[cloudId];
@@ -11889,7 +11950,8 @@ async function pullScenarios(projectRoot, cloud, projectId, outlineIdToSlug, per
       });
       continue;
     }
-    const { frontmatter, body, slug } = buildScenarioFrontmatter(row, personaSlug, outlineSlug);
+    const localFm = localIndex.frontmatterById.get(row.id);
+    const { frontmatter, body, slug } = buildScenarioFrontmatter(row, personaSlug, outlineSlug, localFm);
     await applyEntityPullOutcome(projectRoot, "scenario", row, slug, frontmatter, body, localIndex, mode, result.pulls.scenario, batch);
   }
   await finalizePullBatch(projectRoot, batch);
@@ -12401,15 +12463,15 @@ function resolveApiUrl(configured) {
   assertSecureApiUrl(url, configured ? "API URL" : "IAMU_API_URL");
   return url;
 }
-function parseStore(raw, path32) {
+function parseStore(raw, path34) {
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch (err) {
-    throw new CredentialsFileError(path32, "not valid JSON", err);
+    throw new CredentialsFileError(path34, "not valid JSON", err);
   }
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    throw new CredentialsFileError(path32, "expected a JSON object");
+    throw new CredentialsFileError(path34, "expected a JSON object");
   }
   return parsed;
 }
@@ -12417,26 +12479,26 @@ function isNotFound(err) {
   return typeof err === "object" && err !== null && err.code === "ENOENT";
 }
 async function readCredentialsStore() {
-  const path32 = getCredentialsPath();
+  const path34 = getCredentialsPath();
   let raw;
   try {
-    raw = await readFile(path32, "utf-8");
+    raw = await readFile(path34, "utf-8");
   } catch (err) {
     if (isNotFound(err)) return {};
     warnUnreadableStoreOnce(err);
     throw err;
   }
   try {
-    return parseStore(raw, path32);
+    return parseStore(raw, path34);
   } catch (err) {
     warnUnreadableStoreOnce(err);
     throw err;
   }
 }
 async function writeCredentialsStore(store) {
-  const path32 = getCredentialsPath();
-  await mkdir(dirname(path32), { recursive: true, mode: 448 });
-  await atomicWriteFile(path32, `${JSON.stringify(store, null, 2)}
+  const path34 = getCredentialsPath();
+  await mkdir(dirname(path34), { recursive: true, mode: 448 });
+  await atomicWriteFile(path34, `${JSON.stringify(store, null, 2)}
 `, {
     mode: 384
   });
@@ -12456,16 +12518,16 @@ function resolveApiKey(apiUrl) {
   } catch {
     return null;
   }
-  const path32 = getCredentialsPath();
+  const path34 = getCredentialsPath();
   let raw;
   try {
-    raw = readFileSync(path32, "utf-8");
+    raw = readFileSync(path34, "utf-8");
   } catch (err) {
     if (!isNotFound(err)) warnUnreadableStoreOnce(err);
     return null;
   }
   try {
-    const entry = parseStore(raw, path32)[url];
+    const entry = parseStore(raw, path34)[url];
     if (typeof entry !== "object" || entry === null) return null;
     const token = entry.token;
     return typeof token === "string" && token ? token : null;
@@ -12504,12 +12566,12 @@ var init_credentials = __esm({
        * @param reason - What is wrong with it.
        * @param cause - Underlying parse error, if any.
        */
-      constructor(path32, reason, cause) {
+      constructor(path34, reason, cause) {
         super(
-          `Credentials file ${path32} is corrupt (${reason}). Fix it by hand, or delete it and run \`iamu auth login\` again.`,
+          `Credentials file ${path34} is corrupt (${reason}). Fix it by hand, or delete it and run \`iamu auth login\` again.`,
           {
             cause,
-            suggestedAction: `Delete ${path32} and run \`iamu auth login\`, or set IAMU_TOKEN.`
+            suggestedAction: `Delete ${path34} and run \`iamu auth login\`, or set IAMU_TOKEN.`
           }
         );
       }
@@ -13189,8 +13251,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.2.0-beta.17") {
-    return "0.2.0-beta.17";
+  if ("0.2.0-beta.19") {
+    return "0.2.0-beta.19";
   }
   try {
     const thisDir = dirname3(fileURLToPath2(import.meta.url));
@@ -13219,6 +13281,7 @@ function loadSkillTemplates(version) {
     "iamu-setup.md",
     "iamu-propose.md",
     "iamu-new.md",
+    "iamu-stage.md",
     "iamu-run.md",
     "iamu-findings.md",
     "iamu-status.md"
@@ -13296,16 +13359,16 @@ async function needsWrite(filePath, content) {
     return true;
   }
 }
-function isCliWrittenSkill(path32) {
+function isCliWrittenSkill(path34) {
   try {
-    return /^generatedBy:/m.test(readFileSync3(path32, "utf-8"));
+    return /^generatedBy:/m.test(readFileSync3(path34, "utf-8"));
   } catch {
     return false;
   }
 }
-function isCliWrittenPrompt(path32) {
+function isCliWrittenPrompt(path34) {
   try {
-    const content = readFileSync3(path32, "utf-8");
+    const content = readFileSync3(path34, "utf-8");
     return content.includes("iamu") || /^generatedBy:/m.test(content);
   } catch {
     return false;
@@ -13317,8 +13380,8 @@ function planSkillFiles(hosts, projectRoot, version) {
   for (const host of hosts) {
     if (pluginProvidesSkills(host, projectRoot)) {
       for (const name of skillTemplates.keys()) {
-        const path32 = join4(host.getSkillsDir(projectRoot), name, "SKILL.md");
-        if (isCliWrittenSkill(path32)) files.push({ host, path: path32, content: null });
+        const path34 = join4(host.getSkillsDir(projectRoot), name, "SKILL.md");
+        if (isCliWrittenSkill(path34)) files.push({ host, path: path34, content: null });
       }
     } else if (host.supportsSkills) {
       const skillsDir = host.getSkillsDir(projectRoot);
@@ -18809,6 +18872,22 @@ async function checkProjectTestabilityContract(projectRoot) {
       status: "ok",
       message: `Configured (${details.join(" \xB7 ") || "present"})`
     });
+    if (!frontmatter.access) {
+      let contextAccess = null;
+      try {
+        contextAccess = (await readContext(projectRoot))?.frontmatter.access ?? null;
+      } catch {
+      }
+      if (contextAccess) {
+        checks.push({
+          category: "target",
+          name: "User switching (access)",
+          status: "warn",
+          message: "How to switch user is in iamu/context.yml, which holds the domain. Walks still read it there.",
+          remedy: "Move the `access:` field from iamu/context.yml to the iamu/testability.md frontmatter."
+        });
+      }
+    }
     return { checks, targetUrl };
   } catch (err) {
     checks.push({
@@ -19361,6 +19440,7 @@ var init_list = __esm({
 // src/commands/validate.ts
 var validate_exports = {};
 __export(validate_exports, {
+  schemaByType: () => schemaByType,
   validate: () => validate
 });
 import { randomUUID as randomUUID8 } from "crypto";
@@ -20035,6 +20115,413 @@ var init_new_entity = __esm({
   }
 });
 
+// src/commands/set-entity.ts
+var set_entity_exports = {};
+__export(set_entity_exports, {
+  setEntity: () => setEntity
+});
+import { promises as fs28 } from "fs";
+import path26 from "path";
+import chalk27 from "chalk";
+import { ZodError as ZodError2 } from "zod";
+function given(opts, key) {
+  const v = opts[key];
+  if (Array.isArray(v)) return v.length > 0;
+  if (key === "state") return v === false;
+  return v !== void 0;
+}
+function splitList(raw) {
+  return raw.split(",").map((s) => s.trim()).filter(Boolean);
+}
+function applyChanges(type2, fm, opts) {
+  const changed = [];
+  const put = (key, value) => {
+    if (value === null) delete fm[key];
+    else fm[key] = value;
+    changed.push(key);
+  };
+  if (type2 === "scenario") {
+    if (opts.entry !== void 0) put("entry_path", opts.entry || null);
+    if (opts.target !== void 0) put("target_url", opts.target || null);
+    if (opts.state === false) {
+      put("state", null);
+    } else if (opts.stateDescription !== void 0 || opts.stateApproximation !== void 0) {
+      const prev = fm.state ?? {};
+      const next = { ...prev };
+      if (opts.stateDescription !== void 0) {
+        if (opts.stateDescription.trim() === "") delete next.description;
+        else next.description = opts.stateDescription;
+      }
+      if (opts.stateApproximation !== void 0) {
+        if (opts.stateApproximation.trim() === "") delete next.approximation;
+        else next.approximation = opts.stateApproximation;
+      }
+      if (Object.keys(next).length === 0) {
+        put("state", null);
+      } else {
+        put("state", next);
+      }
+    }
+  } else if (type2 === "persona") {
+    if (opts.access !== void 0) put("access", opts.access || null);
+  } else if (type2 === "capability") {
+    if (opts.paths === false) {
+      put("paths", []);
+    } else if (opts.paths !== void 0 || given(opts, "addPath") || given(opts, "removePath")) {
+      let paths = typeof opts.paths === "string" ? splitList(opts.paths) : Array.isArray(fm.paths) ? fm.paths : [];
+      for (const p of opts.addPath ?? []) {
+        if (!paths.includes(p)) paths = [...paths, p];
+      }
+      const drop = new Set(opts.removePath ?? []);
+      paths = paths.filter((p) => !drop.has(p));
+      put("paths", paths);
+    }
+    if (opts.area !== void 0) put("area", opts.area || null);
+  }
+  return changed;
+}
+async function setEntity(type2, slug, opts) {
+  const ctx = await resolveProject(opts);
+  if (!ctx) return;
+  const { projectRoot } = ctx;
+  const allowed = SETTABLE[type2];
+  if (!allowed) {
+    commandError(
+      `Cannot set fields on "${type2}". Supported: ${Object.keys(SETTABLE).join(", ")}. What a scenario is about (narrative, tension, human tests, brief) is edited in its file, not here.`,
+      opts
+    );
+    return;
+  }
+  const foreign = Object.keys(FLAG_NAMES).filter(
+    (k) => !allowed.includes(k) && given(opts, k)
+  );
+  if (foreign.length > 0) {
+    commandError(
+      `${foreign.map((k) => FLAG_NAMES[k]).join(", ")} ${foreign.length === 1 ? "does" : "do"} not apply to a ${type2}. ${type2} takes: ${allowed.map((k) => FLAG_NAMES[k]).join(", ")}.`,
+      opts
+    );
+    return;
+  }
+  const effectiveOpts = { ...opts };
+  if (opts.file) {
+    let raw;
+    try {
+      if (opts.file === "-") {
+        const chunks = [];
+        for await (const chunk of process.stdin) {
+          chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+        }
+        raw = Buffer.concat(chunks).toString("utf8");
+      } else {
+        raw = await fs28.readFile(path26.resolve(projectRoot, opts.file), "utf8");
+      }
+    } catch (err) {
+      commandError(
+        `Could not read patch file: ${err instanceof Error ? err.message : String(err)}`,
+        opts
+      );
+      return;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("Patch must be a JSON object");
+      }
+    } catch (err) {
+      commandError(
+        `Failed to parse patch JSON: ${err instanceof Error ? err.message : String(err)}`,
+        opts
+      );
+      return;
+    }
+    const allowedPatchKeys = {
+      scenario: ["entry", "entry_path", "target", "target_url", "state"],
+      persona: ["access"],
+      capability: ["paths", "addPath", "removePath", "area"]
+    };
+    const foreignPatchKeys = Object.keys(parsed).filter(
+      (k) => !allowedPatchKeys[type2]?.includes(k)
+    );
+    if (foreignPatchKeys.length > 0) {
+      commandError(
+        `Cannot set authoring fields on ${type2} via staging patch: ${foreignPatchKeys.join(", ")}. What an entity is about (narrative, tension, human tests, brief) is edited in its file, not through staging.`,
+        opts
+      );
+      return;
+    }
+    if (type2 === "scenario") {
+      if (effectiveOpts.entry === void 0 && (parsed.entry !== void 0 || parsed.entry_path !== void 0)) {
+        const v = parsed.entry ?? parsed.entry_path;
+        effectiveOpts.entry = v === null || v === false ? false : String(v);
+      }
+      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 (parsed.state !== void 0) {
+        if (parsed.state === null || parsed.state === false) {
+          if (effectiveOpts.state === void 0) effectiveOpts.state = false;
+        } else if (typeof parsed.state === "object") {
+          const s = parsed.state;
+          if (effectiveOpts.stateDescription === void 0 && s.description !== void 0) {
+            effectiveOpts.stateDescription = s.description === null ? "" : String(s.description);
+          }
+          if (effectiveOpts.stateApproximation === void 0 && s.approximation !== void 0) {
+            effectiveOpts.stateApproximation = s.approximation === null ? "" : String(s.approximation);
+          }
+        }
+      }
+    } else if (type2 === "persona") {
+      if (effectiveOpts.access === void 0 && parsed.access !== void 0) {
+        effectiveOpts.access = parsed.access === null || parsed.access === false ? false : String(parsed.access);
+      }
+    } else if (type2 === "capability") {
+      if (effectiveOpts.paths === void 0 && parsed.paths !== void 0) {
+        if (parsed.paths === null || parsed.paths === false) {
+          effectiveOpts.paths = false;
+        } else if (Array.isArray(parsed.paths)) {
+          effectiveOpts.paths = parsed.paths.length === 0 ? false : parsed.paths.join(",");
+        }
+      }
+      if (effectiveOpts.addPath === void 0 && Array.isArray(parsed.addPath)) {
+        effectiveOpts.addPath = parsed.addPath.map(String);
+      }
+      if (effectiveOpts.removePath === void 0 && Array.isArray(parsed.removePath)) {
+        effectiveOpts.removePath = parsed.removePath.map(String);
+      }
+      if (effectiveOpts.area === void 0 && parsed.area !== void 0) {
+        effectiveOpts.area = parsed.area === null || parsed.area === false ? false : String(parsed.area);
+      }
+    }
+  }
+  if (!allowed.some((k) => given(effectiveOpts, k))) {
+    commandError(
+      `Nothing to set. ${type2} takes: ${allowed.map((k) => FLAG_NAMES[k]).join(", ")}, or --file <path>.`,
+      opts
+    );
+    return;
+  }
+  if (type2 === "capability") {
+    const candidatePaths = [
+      ...typeof effectiveOpts.paths === "string" ? splitList(effectiveOpts.paths) : [],
+      ...effectiveOpts.addPath ?? []
+    ];
+    const invalid = candidatePaths.filter((p) => !p.startsWith("/"));
+    if (invalid.length > 0) {
+      commandError(
+        `Route prefixes must start with "/": ${invalid.join(", ")}`,
+        opts
+      );
+      return;
+    }
+  }
+  const entity = await safeReadEntity(
+    projectRoot,
+    type2,
+    slug,
+    opts
+  );
+  if (!entity) return;
+  const fm = { ...entity.frontmatter };
+  const changed = applyChanges(type2, fm, effectiveOpts);
+  let writtenPath;
+  try {
+    const record = await writeEntity(
+      projectRoot,
+      type2,
+      fm,
+      entity.body
+    );
+    writtenPath = record.path;
+  } 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 ${type2} "${slug}": ${message}`, opts);
+    return;
+  }
+  const entitySlug = String(fm.slug);
+  if (opts.json) {
+    console.log(
+      JSON.stringify({ slug: entitySlug, type: type2, path: writtenPath, changed })
+    );
+    return;
+  }
+  console.log();
+  console.log(
+    `  ${symbols.success} Updated ${type2} ${chalk27.cyan(entitySlug)}: ${changed.join(", ")}`
+  );
+  console.log(`  ${chalk27.dim("path:")} ${writtenPath}`);
+  console.log();
+}
+var SETTABLE, FLAG_NAMES;
+var init_set_entity = __esm({
+  "src/commands/set-entity.ts"() {
+    "use strict";
+    init_dist2();
+    init_symbols();
+    init_context4();
+    SETTABLE = {
+      scenario: [
+        "entry",
+        "target",
+        "stateDescription",
+        "stateApproximation",
+        "state"
+      ],
+      persona: ["access"],
+      capability: ["paths", "addPath", "removePath", "area"]
+    };
+    FLAG_NAMES = {
+      entry: "--entry",
+      target: "--target",
+      stateDescription: "--state-description",
+      stateApproximation: "--state-approximation",
+      state: "--no-state",
+      access: "--access",
+      paths: "--paths",
+      addPath: "--add-path",
+      removePath: "--remove-path",
+      area: "--area"
+    };
+  }
+});
+
+// src/commands/edit-entity.ts
+var edit_entity_exports = {};
+__export(edit_entity_exports, {
+  editEntity: () => editEntity
+});
+import { spawn as spawn2 } from "child_process";
+import { promises as fs29 } from "fs";
+import path27 from "path";
+import chalk28 from "chalk";
+async function editEntity(type2, slug, opts = {}) {
+  const ctx = await resolveProject(opts);
+  if (!ctx) return;
+  const { projectRoot } = ctx;
+  if (!ENTITY_TYPES.includes(type2)) {
+    commandError(
+      `Unknown entity type "${type2}". Supported: ${ENTITY_TYPES.join(", ")}.`,
+      opts
+    );
+    return;
+  }
+  const dir = ENTITY_DIRS[type2];
+  const filePath = path27.join(projectRoot, "iamu", dir, `${slug}.md`);
+  try {
+    await fs29.access(filePath);
+  } catch {
+    commandError(
+      `${type2} "${slug}" not found at ${path27.relative(projectRoot, filePath)}.`,
+      opts
+    );
+    return;
+  }
+  if (!process.stdin.isTTY || process.env.CI) {
+    commandError(
+      `Cannot open editor in a non-interactive environment. Edit the file directly: ${path27.relative(projectRoot, filePath)}`,
+      opts
+    );
+    return;
+  }
+  const rawEditor = process.env.VISUAL || process.env.EDITOR || (process.platform === "win32" ? "notepad" : "vi");
+  const parts = rawEditor.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [
+    rawEditor
+  ];
+  const editorCmd = parts[0].replace(/^["']|["']$/g, "");
+  const editorArgs = parts.slice(1).map((a) => a.replace(/^["']|["']$/g, ""));
+  await new Promise((resolve3) => {
+    const child = spawn2(editorCmd, [...editorArgs, filePath], {
+      stdio: "inherit"
+    });
+    child.on("exit", (code) => {
+      if (code !== 0) {
+        console.error(
+          chalk28.red(
+            `
+  Editor exited with code ${code}. Changes not validated.
+`
+          )
+        );
+        process.exitCode = code ?? 1;
+        resolve3();
+      } else {
+        resolve3();
+      }
+    });
+    child.on("error", (err) => {
+      commandError(
+        `Failed to launch editor (${rawEditor}): ${err.message}`,
+        opts
+      );
+      resolve3();
+    });
+  });
+  if (process.exitCode) return;
+  try {
+    const content = await fs29.readFile(filePath, "utf8");
+    const { frontmatter } = parseFrontmatter(content);
+    const schema2 = schemaByType[type2];
+    const parsed = schema2.safeParse(frontmatter);
+    if (!parsed.success) {
+      if (opts.json) {
+        console.log(
+          JSON.stringify({
+            valid: false,
+            type: type2,
+            slug,
+            path: filePath,
+            errors: parsed.error.issues.map((i) => ({
+              field: i.path.join(".") || "root",
+              message: i.message
+            }))
+          })
+        );
+      } else {
+        console.log();
+        console.log(
+          `  ${symbols.warning} ${chalk28.yellow(`Validation failed for ${type2} "${slug}":`)}`
+        );
+        for (const issue of parsed.error.issues) {
+          const field2 = issue.path.join(".") || "root";
+          console.log(`    - ${field2}: ${issue.message}`);
+        }
+        console.log();
+        console.log(
+          chalk28.dim(
+            `  Fix the file and run: iamu validate ${path27.relative(projectRoot, filePath)}`
+          )
+        );
+        console.log();
+      }
+      process.exitCode = 1;
+      return;
+    }
+    if (opts.json) {
+      console.log(JSON.stringify({ valid: true, type: type2, slug, path: filePath }));
+      return;
+    }
+    console.log();
+    console.log(`  ${symbols.success} Validated ${type2} ${chalk28.cyan(slug)}`);
+    console.log();
+  } catch (err) {
+    commandError(
+      `Failed to validate ${type2} "${slug}" after edit: ${err instanceof Error ? err.message : String(err)}`,
+      opts
+    );
+  }
+}
+var init_edit_entity = __esm({
+  "src/commands/edit-entity.ts"() {
+    "use strict";
+    init_dist2();
+    init_dist();
+    init_symbols();
+    init_context4();
+    init_validate();
+  }
+});
+
 // src/commands/explore-crawl.ts
 function candidateSig(c) {
   return `${c.role}
@@ -20074,6 +20561,9 @@ async function settle(page, settleMs) {
   });
   await page.waitForLoadState("networkidle", { timeout: settleMs }).catch(() => {
   });
+  const spaSettle = Math.min(Math.max(settleMs, 50), 200);
+  await page.waitForTimeout(spaSettle).catch(() => {
+  });
 }
 async function readPage(page) {
   return page.evaluate(READ_PAGE);
@@ -20091,8 +20581,12 @@ async function clickCandidate(page, want) {
     (x) => candidateSig(x) === candidateSig(want)
   );
   if (!c) return false;
-  await page.locator(`[data-iamu-x="${c.index}"]`).click({ timeout: CLICK_TIMEOUT_MS });
-  return true;
+  try {
+    await page.locator(`[data-iamu-x="${c.index}"]`).click({ timeout: CLICK_TIMEOUT_MS });
+    return true;
+  } catch {
+    return false;
+  }
 }
 async function crawl(page, opts) {
   const origin = originOf(opts.startUrl);
@@ -20149,7 +20643,7 @@ async function crawlFrom(page, opts, origin, takeBlocked) {
   const byKey = /* @__PURE__ */ new Map();
   const byPlaceView = /* @__PURE__ */ new Map();
   const signatureOf = (s) => exploreSignature(s.headings, s.title);
-  function addSurface(state, place, view, path32, depth) {
+  function addSurface(state, place, view, path34, depth) {
     const key = exploreSurfaceKey(place, view);
     const surface = {
       key,
@@ -20161,7 +20655,7 @@ async function crawlFrom(page, opts, origin, takeBlocked) {
       headings: state.headings,
       fields: state.fields,
       depth,
-      path: path32,
+      path: path34,
       actions: []
     };
     surfaces.push(surface);
@@ -20179,9 +20673,9 @@ ${surface.signature}`, key);
     });
     await settle(page, settleMs);
   }
-  async function replay(path32) {
-    if (!("goto" in (path32[0] ?? {}))) await goto(opts.startUrl);
-    for (const step of path32) {
+  async function replay(path34) {
+    if (!("goto" in (path34[0] ?? {}))) await goto(opts.startUrl);
+    for (const step of path34) {
       if ("goto" in step) {
         await goto(step.goto);
       } else {
@@ -20305,8 +20799,8 @@ ${sig}`, key);
               if (stats.surfaces >= budget.max_surfaces) {
                 stats.truncated = true;
               } else {
-                const path32 = !sameDoc && view === null ? [{ goto: after.url }] : [...surface.path, ...via, click];
-                addSurface(after, place, view, path32, surface.depth + 1);
+                const path34 = !sameDoc && view === null ? [{ goto: after.url }] : [...surface.path, ...via, click];
+                addSurface(after, place, view, path34, surface.depth + 1);
               }
             }
           }
@@ -20506,11 +21000,11 @@ __export(explore_exports, {
   exploreList: () => exploreList,
   exploreRun: () => exploreRun
 });
-import path26 from "path";
-import chalk27 from "chalk";
+import path28 from "path";
+import chalk29 from "chalk";
 function fail2(message, json2) {
   if (json2) console.error(JSON.stringify({ error: message }));
-  else console.error(chalk27.red(`  ${message}`));
+  else console.error(chalk29.red(`  ${message}`));
   process.exitCode = 1;
 }
 function positiveInt(raw, fallback, flag) {
@@ -20609,7 +21103,7 @@ async function exploreRun(url, opts) {
   }
   const quiet = opts.json || process.env.IAMU_QUIET === "1";
   if (!quiet) {
-    console.error(chalk27.dim(`  Exploring ${startUrl} (read-only)\u2026`));
+    console.error(chalk29.dim(`  Exploring ${startUrl} (read-only)\u2026`));
   }
   const now = /* @__PURE__ */ new Date();
   let opened = null;
@@ -20620,7 +21114,7 @@ async function exploreRun(url, opts) {
       startUrl,
       budget,
       deny,
-      log: quiet ? void 0 : (line) => console.error(chalk27.dim(line))
+      log: quiet ? void 0 : (line) => console.error(chalk29.dim(line))
     });
   } catch (err) {
     fail2(err.message.split("\n")[0], opts.json);
@@ -20640,7 +21134,7 @@ async function exploreRun(url, opts) {
     surfaces: result.surfaces
   };
   const file = await writeExploreMap(ctx.projectRoot, map2);
-  const rel = path26.relative(process.cwd(), file);
+  const rel = path28.relative(process.cwd(), file);
   if (opts.json) {
     console.log(JSON.stringify({ id: map2.id, path: rel, stats: map2.stats }));
     return;
@@ -20648,17 +21142,17 @@ async function exploreRun(url, opts) {
   const s = map2.stats;
   console.log(
     `
-  ${chalk27.bold(`${s.surfaces} surfaces`)} \xB7 ${s.actions_tried} controls tried \xB7 ${s.skipped} skipped \xB7 ${s.blocked_requests} writes blocked${s.errors ? ` \xB7 ${s.errors} errors` : ""}`
+  ${chalk29.bold(`${s.surfaces} surfaces`)} \xB7 ${s.actions_tried} controls tried \xB7 ${s.skipped} skipped \xB7 ${s.blocked_requests} writes blocked${s.errors ? ` \xB7 ${s.errors} errors` : ""}`
   );
   if (s.truncated) {
     console.log(
-      chalk27.yellow(
+      chalk29.yellow(
         "  Stopped by the budget before the product ran out \u2014 raise --max-surfaces / --max-actions / --max-depth to go further."
       )
     );
   }
   console.log(`  Map: ${rel}`);
-  console.log(chalk27.dim("  Next: iamu explore coverage"));
+  console.log(chalk29.dim("  Next: iamu explore coverage"));
 }
 async function resolveMapId(projectRoot, id, offsetFromEnd = 1) {
   if (id && id !== "latest") return id;
@@ -20686,7 +21180,7 @@ async function exploreList(opts) {
   }
   for (const r of rows) {
     console.log(
-      `  ${r.id}  ${r.surfaces} surfaces  ${chalk27.dim(r.target_url)}`
+      `  ${r.id}  ${r.surfaces} surfaces  ${chalk29.dim(r.target_url)}`
     );
   }
 }
@@ -20713,7 +21207,10 @@ async function exploreCoverageCommand(mapId, opts) {
         ...cov,
         ...capReport.capabilities.length > 0 ? {
           capabilities: capReport.capabilities,
-          unassigned_surfaces: capReport.unassigned_surfaces
+          unassigned_surfaces: capReport.unassigned_surfaces,
+          unassigned_prefixes: groupUnassignedByPrefix(
+            capReport.unassigned_surfaces
+          )
         } : {}
       })
     );
@@ -20724,22 +21221,22 @@ async function exploreCoverageCommand(mapId, opts) {
   Map ${id} (${map2.surfaces.length} surfaces) against ${cov.runs} runs, ${cov.steps} steps`
   );
   console.log(
-    `  ${chalk27.green(`${cov.reached} reached`)} \xB7 ${chalk27.yellow(`${cov.place_only} URL reached, view unclear`)} \xB7 ${chalk27.red(`${cov.unreached} never reached`)}`
+    `  ${chalk29.green(`${cov.reached} reached`)} \xB7 ${chalk29.yellow(`${cov.place_only} URL reached, view unclear`)} \xB7 ${chalk29.red(`${cov.unreached} never reached`)}`
   );
   if (capReport.capabilities.length > 0) {
-    console.log(chalk27.bold("\n  CAPABILITY COVERAGE"));
+    console.log(chalk29.bold("\n  CAPABILITY COVERAGE"));
     console.log(
-      chalk27.dim(
+      chalk29.dim(
         "  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"
       )
     );
     console.log(
-      chalk27.dim(
+      chalk29.dim(
         `  ${"Capability".padEnd(24)} ${"Surfaces".padStart(8)}   ${"Coverage".padStart(8)}   ${"Scenarios (1\xB0 / 2\xB0)"}`
       )
     );
     console.log(
-      chalk27.dim(
+      chalk29.dim(
         "  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"
       )
     );
@@ -20750,8 +21247,8 @@ async function exploreCoverageCommand(mapId, opts) {
       );
       const covStr = `${cap.coverage_pct}%`.padStart(8);
       const scenarios = `${cap.primary_scenarios} / ${cap.secondary_scenarios}`;
-      const untestedFlag = cap.primary_scenarios === 0 && cap.unreached_surfaces > 0 ? chalk27.yellow("  (untested)") : "";
-      const covColored = cap.coverage_pct === 100 ? chalk27.green(covStr) : cap.coverage_pct === 0 ? chalk27.red(covStr) : chalk27.yellow(covStr);
+      const untestedFlag = cap.primary_scenarios === 0 && cap.unreached_surfaces > 0 ? chalk29.yellow("  (untested)") : "";
+      const covColored = cap.coverage_pct === 100 ? chalk29.green(covStr) : cap.coverage_pct === 0 ? chalk29.red(covStr) : chalk29.yellow(covStr);
       console.log(
         `  ${title} ${surfaces}   ${covColored}   ${scenarios}${untestedFlag}`
       );
@@ -20761,26 +21258,41 @@ async function exploreCoverageCommand(mapId, opts) {
       const reached = unassigned.filter((s) => s.status === "reached").length;
       const pct = Math.round(reached / unassigned.length * 100);
       console.log(
-        chalk27.dim(
+        chalk29.dim(
           `  ${"(Unassigned)".padEnd(24)} ${`${reached}/${unassigned.length}`.padStart(8)}   ${`${pct}%`.padStart(8)}   -`
         )
       );
     }
     console.log(
-      chalk27.dim(
+      chalk29.dim(
         "  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"
       )
     );
+    const prefixes = groupUnassignedByPrefix(capReport.unassigned_surfaces);
+    if (prefixes.length > 0) {
+      console.log(chalk29.bold("\n  UNASSIGNED PAGES (no capability owns them)"));
+      for (const g of prefixes) {
+        const count = `${g.surfaces} page${g.surfaces === 1 ? "" : "s"} (${g.reached} reached)`;
+        console.log(
+          `    ${g.prefix.padEnd(24)} ${count.padEnd(24)} ${chalk29.dim(`e.g. ${g.examples.join(", ")}`)}`
+        );
+      }
+      console.log(
+        chalk29.dim(
+          `  Give a prefix to the capability it belongs to: iamu set capability <slug> --add-path ${prefixes[0]?.prefix}`
+        )
+      );
+    }
     const hasGaps = capReport.capabilities.some((c) => c.unreached_surfaces > 0) || capReport.unassigned_surfaces.some((s) => s.status !== "reached");
     if (hasGaps) {
-      console.log(chalk27.red("\n  UNREACHED SURFACES (Gaps)"));
+      console.log(chalk29.red("\n  UNREACHED SURFACES (Gaps)"));
       for (const cap of capReport.capabilities) {
         const gaps = cap.surfaces.filter((s) => s.status !== "reached");
         if (gaps.length === 0) continue;
-        console.log(`    ${chalk27.bold(cap.slug)}:`);
+        console.log(`    ${chalk29.bold(cap.slug)}:`);
         for (const s of gaps) {
           console.log(
-            `      ${chalk27.red("\u25CB")} ${s.key.padEnd(32)} ${s.label}${chalk27.dim(` (depth ${s.depth})`)}`
+            `      ${chalk29.red("\u25CB")} ${s.key.padEnd(32)} ${s.label}${chalk29.dim(` (depth ${s.depth})`)}`
           );
         }
       }
@@ -20788,23 +21300,23 @@ async function exploreCoverageCommand(mapId, opts) {
         (s) => s.status !== "reached"
       );
       if (unassignedGaps.length > 0) {
-        console.log(chalk27.dim("    (Unassigned):"));
+        console.log(chalk29.dim("    (Unassigned):"));
         for (const s of unassignedGaps) {
           console.log(
-            `      ${chalk27.dim("\u25CB")} ${s.key.padEnd(32)} ${s.label}${chalk27.dim(` (depth ${s.depth})`)}`
+            `      ${chalk29.dim("\u25CB")} ${s.key.padEnd(32)} ${s.label}${chalk29.dim(` (depth ${s.depth})`)}`
           );
         }
       }
     }
     if (opts.all) {
-      console.log(chalk27.green("\n  REACHED SURFACES"));
+      console.log(chalk29.green("\n  REACHED SURFACES"));
       for (const cap of capReport.capabilities) {
         const reached = cap.surfaces.filter((s) => s.status === "reached");
         if (reached.length === 0) continue;
-        console.log(`    ${chalk27.bold(cap.slug)}:`);
+        console.log(`    ${chalk29.bold(cap.slug)}:`);
         for (const s of reached) {
           console.log(
-            `      ${chalk27.green("\u2713")} ${s.key.padEnd(32)} ${s.label}${chalk27.dim(` (depth ${s.depth})`)}`
+            `      ${chalk29.green("\u2713")} ${s.key.padEnd(32)} ${s.label}${chalk29.dim(` (depth ${s.depth})`)}`
           );
         }
       }
@@ -20812,10 +21324,10 @@ async function exploreCoverageCommand(mapId, opts) {
         (s) => s.status === "reached"
       );
       if (unassignedReached.length > 0) {
-        console.log(chalk27.dim("    (Unassigned):"));
+        console.log(chalk29.dim("    (Unassigned):"));
         for (const s of unassignedReached) {
           console.log(
-            `      ${chalk27.green("\u2713")} ${s.key.padEnd(32)} ${s.label}${chalk27.dim(` (depth ${s.depth})`)}`
+            `      ${chalk29.green("\u2713")} ${s.key.padEnd(32)} ${s.label}${chalk29.dim(` (depth ${s.depth})`)}`
           );
         }
       }
@@ -20827,24 +21339,24 @@ async function exploreCoverageCommand(mapId, opts) {
   ${color(title)}`);
       for (const r of rows) {
         console.log(
-          `    ${r.key.padEnd(32)} ${r.label}${chalk27.dim(`  (depth ${r.depth})`)}`
+          `    ${r.key.padEnd(32)} ${r.label}${chalk29.dim(`  (depth ${r.depth})`)}`
         );
       }
     };
     section(
       "Never reached by a run",
       cov.surfaces.filter((s) => s.status === "unreached"),
-      chalk27.red
+      chalk29.red
     );
     section(
       "URL reached, but no step names this view",
       cov.surfaces.filter((s) => s.status === "place_only"),
-      chalk27.yellow
+      chalk29.yellow
     );
   }
   if (cov.run_only_places.length > 0) {
     console.log(`
-  ${chalk27.cyan("Walked by runs, not in the map")}`);
+  ${chalk29.cyan("Walked by runs, not in the map")}`);
     for (const p of cov.run_only_places) {
       console.log(
         `    ${p.place.padEnd(32)} ${p.steps} steps, ${p.runs.length} runs`
@@ -20853,7 +21365,7 @@ async function exploreCoverageCommand(mapId, opts) {
   }
   if (cov.runs === 0) {
     console.log(
-      chalk27.dim(
+      chalk29.dim(
         "\n  No runs yet \u2014 every surface counts as never reached. Walk a scenario first (iamu-run)."
       )
     );
@@ -20889,27 +21401,27 @@ async function exploreDiffCommand(a, b, opts) {
   console.log(`
   ${idA} \u2192 ${idB}`);
   console.log(
-    `  ${chalk27.bold(`${pct}% of surfaces match`)} (${d.common} shared, ${d.only_a.length} only in the first, ${d.only_b.length} only in the second)`
+    `  ${chalk29.bold(`${pct}% of surfaces match`)} (${d.common} shared, ${d.only_a.length} only in the first, ${d.only_b.length} only in the second)`
   );
   if (d.only_a.length > 0) {
     console.log(`
-  ${chalk27.red("Only in the first")}`);
+  ${chalk29.red("Only in the first")}`);
     for (const s of d.only_a) console.log(`    ${s.key.padEnd(32)} ${s.label}`);
   }
   if (d.only_b.length > 0) {
     console.log(`
-  ${chalk27.green("Only in the second")}`);
+  ${chalk29.green("Only in the second")}`);
     for (const s of d.only_b) console.log(`    ${s.key.padEnd(32)} ${s.label}`);
   }
   if (d.changed_actions.length > 0) {
     console.log(
       `
-  ${chalk27.yellow(`Controls differ on ${d.changed_actions.length} shared surfaces`)}`
+  ${chalk29.yellow(`Controls differ on ${d.changed_actions.length} shared surfaces`)}`
     );
     for (const c of d.changed_actions) {
       console.log(`    ${c.key}  ${c.label}`);
-      for (const x of c.only_a) console.log(chalk27.red(`      - ${x}`));
-      for (const x of c.only_b) console.log(chalk27.green(`      + ${x}`));
+      for (const x of c.only_a) console.log(chalk29.red(`      - ${x}`));
+      for (const x of c.only_b) console.log(chalk29.green(`      + ${x}`));
     }
   }
 }
@@ -21123,7 +21635,7 @@ __export(instructions_walk_exports, {
 });
 import { existsSync as existsSync12, readFileSync as readFileSync8 } from "fs";
 import { join as join9 } from "path";
-import chalk28 from "chalk";
+import chalk30 from "chalk";
 function selfCommand() {
   const q = (p) => /[\s"'$]/.test(p) ? JSON.stringify(p) : p;
   return `${q(process.execPath)} ${q(process.argv[1] ?? "iamu")}`;
@@ -21253,7 +21765,7 @@ function composeWalkerPrompt(p) {
       "Squinting Guardrails:",
       "\u2022 If the exact target record/option is not available, apply the approximation strategy above to pick the closest plausible entity within the domain flow.",
       "\u2022 Squinting does NOT permit drifting to unrelated settings, account profiles, or off-target pages. Stay strictly within the scenario journey.",
-      "\u2022 If the system is completely empty or unseeded, and your persona role cannot create data, do NOT report false product bugs about the empty state. Note that preconditions are unseeded/blocked."
+      "\u2022 If the system is completely empty or unseeded, and your persona role cannot create data, do NOT report false product bugs about the empty state. End the walk as blocked (below)."
     ].filter(Boolean) : [],
     ...p.untestableBoundaries && p.untestableBoundaries.length > 0 ? [
       "",
@@ -21289,6 +21801,7 @@ function composeWalkerPrompt(p) {
     `Record findings with: ${iamu} new-finding --scenario ${p.scenarioSlug} --run ${p.runId} --step <N> --title "..." --type <helps|hinders|missing|irrelevant|incorrect> --severity <critical|major|minor|observation> --ui-fact "..." --consequence "..." --task-impact <blocks|impairs|slows|neutral|accelerates|enables> --confidence <high|medium|low> --description "..." --recommendation "..." --json`,
     "`--step <N>` is the step whose screenshot shows the problem (or strength): it is the evidence people see next to the finding, so record that step and its screenshot first, and pick the screenshot where the thing is actually visible.",
     `Before you finish, record synthesis with: ${iamu} summary ${p.runId} --worked "..." --worked "..." --question "..."`,
+    `If the walk cannot start as it was set up \u2014 you cannot become this persona (the switch or login fails, or you are someone else), the world the situation needs is not there and you cannot create it, or the starting page does not load \u2014 stop immediately and end the walk with: ${iamu} summary ${p.runId} --blocked "<what was missing, as you saw it>". Do NOT record preliminary findings if preconditions are not met. That is about the setup, not the product: when the product has no way to do what you need, that is a finding (--type missing), not a block. Do not record findings about the missing setup itself.`,
     "Execute everything via CLI commands in the shell. Never invoke host Edit or Write tools on files in the workspace.",
     "",
     "Do not read the product's source code, other iamu/ entity files, or earlier runs: you know only what the persona knows.",
@@ -21406,6 +21919,7 @@ async function instructionsWalk(opts) {
       if (!targetUrl && doc.frontmatter.target_url) {
         targetUrl = doc.frontmatter.target_url;
       }
+      if (doc.frontmatter.access) projectAccess = doc.frontmatter.access;
       const fromFm = doc.frontmatter.untestable_boundaries ?? [];
       const fromBody = extractUntestableBoundaries(doc.body);
       untestableBoundaries.push(
@@ -21491,40 +22005,40 @@ async function instructionsWalk(opts) {
     return;
   }
   console.log();
-  console.log(chalk28.bold("  Walk instructions"));
-  console.log(`  ${chalk28.dim("scenario:")}  ${sfm.slug}`);
-  console.log(`  ${chalk28.dim("persona:")}   ${pfm.name} (${pfm.role})`);
-  console.log(`  ${chalk28.dim("outline:")}   ${ofm.title}`);
+  console.log(chalk30.bold("  Walk instructions"));
+  console.log(`  ${chalk30.dim("scenario:")}  ${sfm.slug}`);
+  console.log(`  ${chalk30.dim("persona:")}   ${pfm.name} (${pfm.role})`);
+  console.log(`  ${chalk30.dim("outline:")}   ${ofm.title}`);
   if (sfm.state?.description || sfm.state?.approximation) {
     console.log(
-      `  ${chalk28.dim("state:")}     ${sfm.state.description ? sfm.state.description : sfm.state.approximation ?? ""}`
+      `  ${chalk30.dim("state:")}     ${sfm.state.description ? sfm.state.description : sfm.state.approximation ?? ""}`
     );
   }
-  if (targetUrl) console.log(`  ${chalk28.dim("target:")}    ${targetUrl}`);
+  if (targetUrl) console.log(`  ${chalk30.dim("target:")}    ${targetUrl}`);
   console.log(
-    `  ${chalk28.dim("access:")}    ${projectAccess || personaAccess ? `${projectAccess ? "project" : ""}${projectAccess && personaAccess ? " + " : ""}${personaAccess ? "persona" : ""}` : "not recorded (walker would run as whoever is signed in)"}`
+    `  ${chalk30.dim("access:")}    ${projectAccess || personaAccess ? `${projectAccess ? "project" : ""}${projectAccess && personaAccess ? " + " : ""}${personaAccess ? "persona" : ""}` : "not recorded (walker would run as whoever is signed in)"}`
   );
   console.log(
-    `  ${chalk28.dim("dismissed:")} ${dismissedFacts.length} findings to skip`
+    `  ${chalk30.dim("dismissed:")} ${dismissedFacts.length} findings to skip`
   );
   console.log(
-    `  ${chalk28.dim("guidance:")}  ${guidance.length} tester guidance rule${guidance.length === 1 ? "" : "s"}`
+    `  ${chalk30.dim("guidance:")}  ${guidance.length} tester guidance rule${guidance.length === 1 ? "" : "s"}`
   );
   if (untestableBoundaries.length > 0) {
     console.log(
-      `  ${chalk28.dim("boundaries:")} ${untestableBoundaries.length} untestable boundaries to avoid`
+      `  ${chalk30.dim("boundaries:")} ${untestableBoundaries.length} untestable boundaries to avoid`
     );
   }
   if (revisit.length > 0) {
     console.log(
-      `  ${chalk28.dim("re-check:")}  ${revisit.length} place${revisit.length === 1 ? "" : "s"} where fixes await a re-run`
+      `  ${chalk30.dim("re-check:")}  ${revisit.length} place${revisit.length === 1 ? "" : "s"} where fixes await a re-run`
     );
   }
   console.log(
-    `  ${chalk28.dim("methodology:")} ${methodology ? "loaded" : "missing (run iamu update)"}`
+    `  ${chalk30.dim("methodology:")} ${methodology ? "loaded" : "missing (run iamu update)"}`
   );
   console.log();
-  console.log(chalk28.dim("  Use --json to get the full instruction bundle."));
+  console.log(chalk30.dim("  Use --json to get the full instruction bundle."));
   console.log();
 }
 var SCREEN;
@@ -21550,8 +22064,8 @@ __export(new_finding_exports, {
 });
 import { randomUUID as randomUUID10 } from "crypto";
 import { access, readFile as readFile7 } from "fs/promises";
-import path27 from "path";
-import chalk29 from "chalk";
+import path29 from "path";
+import chalk31 from "chalk";
 async function newFinding(opts) {
   const ctx = await resolveProject(opts);
   if (!ctx) return;
@@ -21617,7 +22131,7 @@ async function newFinding(opts) {
     }
     try {
       await access(
-        path27.join(runDirPath, "steps", `${String(n).padStart(3, "0")}.json`)
+        path29.join(runDirPath, "steps", `${String(n).padStart(3, "0")}.json`)
       );
     } catch {
       commandError(
@@ -21632,7 +22146,7 @@ async function newFinding(opts) {
   if (!scenarioSlug) {
     try {
       const manifestRaw = await readFile7(
-        path27.join(runDirPath, "walkthrough.json"),
+        path29.join(runDirPath, "walkthrough.json"),
         "utf8"
       );
       const manifest = JSON.parse(manifestRaw);
@@ -21736,10 +22250,10 @@ async function newFinding(opts) {
       return;
     }
     console.log();
-    console.log(`  ${symbols.success} Created finding: ${chalk29.cyan(slug)}`);
-    console.log(`  ${chalk29.dim("path:")} ${record.path}`);
-    console.log(`  ${chalk29.dim("id:")}   ${id}`);
-    for (const w of warnings) console.log(`  ${chalk29.yellow("!")} ${w}`);
+    console.log(`  ${symbols.success} Created finding: ${chalk31.cyan(slug)}`);
+    console.log(`  ${chalk31.dim("path:")} ${record.path}`);
+    console.log(`  ${chalk31.dim("id:")}   ${id}`);
+    for (const w of warnings) console.log(`  ${chalk31.yellow("!")} ${w}`);
     console.log();
   } catch (err) {
     commandError(
@@ -21764,9 +22278,13 @@ var summary_exports = {};
 __export(summary_exports, {
   summaryCommand: () => summaryCommand
 });
-import { promises as fs28 } from "fs";
-import path28 from "path";
-import chalk30 from "chalk";
+import { promises as fs30 } from "fs";
+import path30 from "path";
+import chalk32 from "chalk";
+function blockedFrom(value) {
+  const reason = value && typeof value === "object" ? value.reason : value;
+  return typeof reason === "string" && reason.trim() ? { reason: reason.trim() } : void 0;
+}
 async function summaryCommand(runIdArg, opts) {
   const ctx = await resolveProject(opts);
   if (!ctx) return;
@@ -21781,6 +22299,13 @@ async function summaryCommand(runIdArg, opts) {
   let whatWorked = [];
   let openQuestions = [];
   let model = opts.model?.trim() || void 0;
+  const summaryPath = path30.join(runDirPath, "summary.json");
+  let blocked;
+  try {
+    const prev = JSON.parse(await fs30.readFile(summaryPath, "utf8"));
+    blocked = blockedFrom(prev.blocked);
+  } catch {
+  }
   if (opts.file) {
     try {
       let raw;
@@ -21791,7 +22316,7 @@ async function summaryCommand(runIdArg, opts) {
         }
         raw = Buffer.concat(chunks).toString("utf8");
       } else {
-        raw = await fs28.readFile(path28.resolve(projectRoot, opts.file), "utf8");
+        raw = await fs30.readFile(path30.resolve(projectRoot, opts.file), "utf8");
       }
       const parsed = JSON.parse(raw);
       if (Array.isArray(parsed.what_worked)) {
@@ -21807,6 +22332,7 @@ async function summaryCommand(runIdArg, opts) {
       if (typeof parsed.model === "string" && parsed.model.trim()) {
         model = parsed.model.trim();
       }
+      blocked = blockedFrom(parsed.blocked) ?? blocked;
     } catch (err) {
       commandError(
         `Failed to parse summary file: ${err instanceof Error ? err.message : String(err)}`,
@@ -21828,12 +22354,17 @@ async function summaryCommand(runIdArg, opts) {
   if (cliQuestions.length > 0) {
     openQuestions = [...openQuestions, ...cliQuestions];
   }
+  if (opts.blocked === false) {
+    blocked = void 0;
+  } else {
+    blocked = blockedFrom(opts.blocked) ?? blocked;
+  }
   const data = {
     what_worked: whatWorked,
     open_questions: openQuestions,
-    ...model ? { model } : {}
+    ...model ? { model } : {},
+    ...blocked ? { blocked } : {}
   };
-  const summaryPath = path28.join(runDirPath, "summary.json");
   await atomicWriteFile(summaryPath, `${JSON.stringify(data, null, 2)}
 `);
   if (opts.json) {
@@ -21841,7 +22372,7 @@ async function summaryCommand(runIdArg, opts) {
       JSON.stringify(
         {
           run_id: runId,
-          path: path28.relative(projectRoot, summaryPath),
+          path: path30.relative(projectRoot, summaryPath),
           summary: data
         },
         null,
@@ -21852,16 +22383,19 @@ async function summaryCommand(runIdArg, opts) {
   }
   console.log();
   console.log(
-    `  ${symbols.success} Summary recorded for run ${chalk30.cyan(runId)}`
+    `  ${symbols.success} Summary recorded for run ${chalk32.cyan(runId)}`
   );
+  if (data.blocked) {
+    console.log(`    ${chalk32.yellow("blocked:")}       ${data.blocked.reason}`);
+  }
   if (data.what_worked.length > 0) {
     console.log(
-      `    ${chalk30.dim("what worked:")}   ${data.what_worked.length} item(s)`
+      `    ${chalk32.dim("what worked:")}   ${data.what_worked.length} item(s)`
     );
   }
   if (data.open_questions.length > 0) {
     console.log(
-      `    ${chalk30.dim("open questions:")} ${data.open_questions.length} item(s)`
+      `    ${chalk32.dim("open questions:")} ${data.open_questions.length} item(s)`
     );
   }
   console.log();
@@ -21882,7 +22416,7 @@ __export(view_results_exports, {
   promptViewResults: () => promptViewResults
 });
 import { isCancel as isCancel4, select as select4 } from "@clack/prompts";
-import chalk31 from "chalk";
+import chalk33 from "chalk";
 function launchCloudDashboard(config, runId) {
   const cloudRunId = runId ? toCloudRunUuid(runId) : void 0;
   const url = getCloudDashboardUrl(
@@ -21891,7 +22425,7 @@ function launchCloudDashboard(config, runId) {
     cloudRunId
   );
   console.log();
-  console.log(`  ${symbols.success} Opening Iamu Cloud: ${chalk31.cyan(url)}
+  console.log(`  ${symbols.success} Opening Iamu Cloud: ${chalk33.cyan(url)}
 `);
   openBrowser(url);
 }
@@ -21959,9 +22493,9 @@ __export(evaluate_exports, {
   evaluate: () => evaluate,
   evaluateRecord: () => evaluateRecord
 });
-import { promises as fs29 } from "fs";
-import path29 from "path";
-import chalk32 from "chalk";
+import { promises as fs31 } from "fs";
+import path31 from "path";
+import chalk34 from "chalk";
 import { z as z26 } from "zod";
 function formatIssues(error) {
   return error.issues.map(
@@ -21991,10 +22525,10 @@ async function evaluate(runId, opts) {
   const resolved = await resolveProjectAndRunDir(runId, opts);
   if (!resolved) return;
   const { projectRoot, runDirPath } = resolved;
-  const canonicalPath = path29.join(runDirPath, "canonical.json");
+  const canonicalPath = path31.join(runDirPath, "canonical.json");
   let canonical;
   try {
-    const raw = await fs29.readFile(canonicalPath, "utf8");
+    const raw = await fs31.readFile(canonicalPath, "utf8");
     canonical = JSON.parse(raw);
   } catch {
     commandError(
@@ -22050,15 +22584,15 @@ async function evaluate(runId, opts) {
     )
   };
   const prompt = composeJudgePrompt(input);
-  const promptFilePath = opts?.promptFile ?? path29.join(runDirPath, "judge_prompt.md");
-  await fs29.writeFile(promptFilePath, prompt, "utf8");
+  const promptFilePath = opts?.promptFile ?? path31.join(runDirPath, "judge_prompt.md");
+  await fs31.writeFile(promptFilePath, prompt, "utf8");
   if (opts?.json) {
     console.log(
       JSON.stringify(
         {
           ...input,
-          prompt_file: path29.relative(projectRoot, promptFilePath),
-          prompt_file_abs: path29.resolve(promptFilePath),
+          prompt_file: path31.relative(projectRoot, promptFilePath),
+          prompt_file_abs: path31.resolve(promptFilePath),
           judge_prompt: prompt
         },
         null,
@@ -22075,10 +22609,10 @@ async function evaluateRecord(runId, opts) {
   const { projectRoot, runDirPath } = resolved;
   sendLivePhase(projectRoot, runId, "judging").catch(() => {
   });
-  const canonicalPath = path29.join(runDirPath, "canonical.json");
+  const canonicalPath = path31.join(runDirPath, "canonical.json");
   let canonical;
   try {
-    const raw = await fs29.readFile(canonicalPath, "utf8");
+    const raw = await fs31.readFile(canonicalPath, "utf8");
     canonical = JSON.parse(raw);
   } catch {
     commandError(`No canonical.json for run: ${runId}`, opts);
@@ -22100,7 +22634,7 @@ async function evaluateRecord(runId, opts) {
       }
       raw = Buffer.concat(chunks).toString("utf8");
     } else {
-      raw = await fs29.readFile(opts.file, "utf8");
+      raw = await fs31.readFile(opts.file, "utf8");
     }
     parsedFile = JSON.parse(raw);
   } catch (err) {
@@ -22161,8 +22695,8 @@ ${formatIssues(fileResult.error)}`,
     overall: inputVerdicts.overall
   });
   const reportContent = renderCanonicalMarkdown(canonicalForReport);
-  const verdictsPath = path29.join(runDirPath, "verdicts.json");
-  const reportPath = path29.join(runDirPath, "report.md");
+  const verdictsPath = path31.join(runDirPath, "verdicts.json");
+  const reportPath = path31.join(runDirPath, "report.md");
   await Promise.all([
     atomicWriteFile(
       verdictsPath,
@@ -22182,8 +22716,8 @@ ${formatIssues(fileResult.error)}`,
       JSON.stringify(
         {
           runId,
-          verdictsPath: path29.relative(projectRoot, verdictsPath),
-          reportPath: path29.relative(projectRoot, reportPath),
+          verdictsPath: path31.relative(projectRoot, verdictsPath),
+          reportPath: path31.relative(projectRoot, reportPath),
           verdictsCount: validatedVerdicts.length,
           linkedCount: linked.length,
           ...cloudInfo ? { cloud: cloudInfo } : {}
@@ -22196,18 +22730,18 @@ ${formatIssues(fileResult.error)}`,
   }
   console.log();
   console.log(
-    `  ${symbols.success} Recorded ${validatedVerdicts.length} verdicts for run ${chalk32.cyan(runId)}`
+    `  ${symbols.success} Recorded ${validatedVerdicts.length} verdicts for run ${chalk34.cyan(runId)}`
   );
   if (linked.length > 0) {
     console.log(
-      `  ${chalk32.dim("linked:")}  ${linked.length} finding${linked.length === 1 ? "" : "s"} to the human test${linked.length === 1 ? "" : "s"} citing ${linked.length === 1 ? "it" : "them"}`
+      `  ${chalk34.dim("linked:")}  ${linked.length} finding${linked.length === 1 ? "" : "s"} to the human test${linked.length === 1 ? "" : "s"} citing ${linked.length === 1 ? "it" : "them"}`
     );
   }
   console.log(
-    `  ${chalk32.dim("verdicts:")} ${path29.relative(projectRoot, verdictsPath)}`
+    `  ${chalk34.dim("verdicts:")} ${path31.relative(projectRoot, verdictsPath)}`
   );
   console.log(
-    `  ${chalk32.dim("report:")}  ${path29.relative(projectRoot, reportPath)}`
+    `  ${chalk34.dim("report:")}  ${path31.relative(projectRoot, reportPath)}`
   );
   printCloudRunInfo(cloudInfo);
   await promptViewResults(projectRoot, { ...opts, runId });
@@ -22272,9 +22806,9 @@ __export(complete_exports, {
   screenshotSizeWarning: () => screenshotSizeWarning,
   validateCanonicalWalkthrough: () => validateCanonicalWalkthrough
 });
-import { promises as fs30 } from "fs";
-import path30 from "path";
-import chalk33 from "chalk";
+import { promises as fs32 } from "fs";
+import path32 from "path";
+import chalk35 from "chalk";
 async function complete(runId, opts) {
   const run = await loadRun(runId, opts);
   if (!run) return;
@@ -22286,7 +22820,7 @@ async function complete(runId, opts) {
   }
   if (!opts?.json) {
     console.log();
-    console.log(chalk33.bold("  Assembling canonical JSON\u2026"));
+    console.log(chalk35.bold("  Assembling canonical JSON\u2026"));
   }
   const provenanceAudit = auditStepProvenance(
     await readStepsForRun(run.projectRoot, runId)
@@ -22299,8 +22833,8 @@ async function complete(runId, opts) {
   const walkerSummary = await readWalkerSummary(run.runDirPath);
   let judgeReported;
   try {
-    const verdictsRaw = await fs30.readFile(
-      path30.join(run.runDirPath, "verdicts.json"),
+    const verdictsRaw = await fs32.readFile(
+      path32.join(run.runDirPath, "verdicts.json"),
       "utf8"
     );
     const parsed = JSON.parse(verdictsRaw);
@@ -22322,9 +22856,11 @@ async function complete(runId, opts) {
     ...durationSec != null ? { total_duration_sec: durationSec } : {},
     ...velocitySec != null ? { velocity_sec_per_step: velocitySec } : {}
   };
+  const { blocked: _previousBlock, ...manifestRest } = run.manifest;
   run.manifest = {
-    ...run.manifest,
-    models: updatedModels
+    ...manifestRest,
+    models: updatedModels,
+    ...walkerSummary.blocked ? { blocked: walkerSummary.blocked } : {}
   };
   const assembled = await assembleRun(
     run.projectRoot,
@@ -22352,16 +22888,16 @@ async function loadRun(runId, opts) {
   if (!resolved) return null;
   const { projectRoot, runDirPath } = resolved;
   try {
-    await fs30.access(runDirPath);
+    await fs32.access(runDirPath);
   } catch {
     commandError(`Run not found: ${runId}`, opts);
     return null;
   }
-  const manifestPath = path30.join(runDirPath, "walkthrough.json");
+  const manifestPath = path32.join(runDirPath, "walkthrough.json");
   let manifest;
   try {
     manifest = JSON.parse(
-      await fs30.readFile(manifestPath, "utf8")
+      await fs32.readFile(manifestPath, "utf8")
     );
   } catch {
     commandError(`No walkthrough.json found for run: ${runId}`, opts);
@@ -22373,8 +22909,8 @@ async function reportAlreadyCompleted(run, opts) {
   const { runId, manifest } = run;
   if (opts?.json) {
     try {
-      const raw = await fs30.readFile(
-        path30.join(run.runDirPath, "canonical.json"),
+      const raw = await fs32.readFile(
+        path32.join(run.runDirPath, "canonical.json"),
         "utf8"
       );
       console.log(raw.trim());
@@ -22394,18 +22930,18 @@ async function reportAlreadyCompleted(run, opts) {
     return;
   }
   console.log();
-  console.log(chalk33.bold("  Run: ") + chalk33.cyan(runId));
-  console.log(`  status     ${chalk33.green("completed")}`);
+  console.log(chalk35.bold("  Run: ") + chalk35.cyan(runId));
+  console.log(`  status     ${chalk35.green("completed")}`);
   if (manifest.completed_at) {
-    console.log(`  completed  ${chalk33.dim(manifest.completed_at)}`);
+    console.log(`  completed  ${chalk35.dim(manifest.completed_at)}`);
   }
   const viewUrl = await pushedRunUrl(run.projectRoot, runId);
   if (viewUrl) {
-    console.log(`  view       ${chalk33.underline(viewUrl)}`);
+    console.log(`  view       ${chalk35.underline(viewUrl)}`);
   }
   console.log();
   console.log(
-    chalk33.dim(
+    chalk35.dim(
       "  Already completed \u2014 nothing to do. Use --force to reassemble the report."
     )
   );
@@ -22421,13 +22957,13 @@ function reportStrictProvenanceFailure(audit, opts) {
   }
   console.error();
   console.error(
-    chalk33.red(`  ${symbols.error} Strict provenance audit failed:`)
+    chalk35.red(`  ${symbols.error} Strict provenance audit failed:`)
   );
   for (const w of audit.warnings) {
-    console.error(chalk33.red(`    \u2022 ${w}`));
+    console.error(chalk35.red(`    \u2022 ${w}`));
   }
   console.error(
-    chalk33.dim(
+    chalk35.dim(
       "  Run was flagged as synthetic / scripted. Remove --strict-provenance to complete anyway."
     )
   );
@@ -22468,41 +23004,48 @@ function completeJsonPayload(canonical, extras) {
 function printCompletionSummary(run, completedAt, assembled, extras, provenanceAudit) {
   const { runId, projectRoot, manifest } = run;
   const { canonical } = assembled;
-  const count = (n) => n === 0 ? chalk33.dim("0") : chalk33.cyan(String(n));
-  console.log(chalk33.bold("  Run: ") + chalk33.cyan(runId));
-  console.log(`  scenario   ${chalk33.dim(manifest.scenario_slug)}`);
-  console.log(`  url        ${chalk33.dim(manifest.target_url)}`);
+  const count = (n) => n === 0 ? chalk35.dim("0") : chalk35.cyan(String(n));
+  console.log(chalk35.bold("  Run: ") + chalk35.cyan(runId));
+  console.log(`  scenario   ${chalk35.dim(manifest.scenario_slug)}`);
+  console.log(`  url        ${chalk35.dim(manifest.target_url)}`);
   if (manifest.environment) {
-    console.log(`  env        ${chalk33.dim(manifest.environment)}`);
+    console.log(`  env        ${chalk35.dim(manifest.environment)}`);
   }
   if (manifest.build) {
-    console.log(`  build      ${chalk33.dim(formatBuild(manifest.build))}`);
+    console.log(`  build      ${chalk35.dim(formatBuild(manifest.build))}`);
   }
   if (manifest.viewport) {
-    console.log(`  device     ${chalk33.dim(formatViewport(manifest.viewport))}`);
+    console.log(`  device     ${chalk35.dim(formatViewport(manifest.viewport))}`);
+  }
+  if (manifest.blocked) {
+    console.log(
+      `  status     ${chalk35.yellow("blocked")} ${chalk35.dim("\u2014 the walk could not start as set up")}`
+    );
+    console.log(`  reason     ${manifest.blocked.reason}`);
+  } else {
+    console.log(`  status     ${chalk35.green("completed")}`);
   }
-  console.log(`  status     ${chalk33.green("completed")}`);
   console.log(`  findings   ${count(canonical.findings.length)}`);
   console.log(`  steps      ${count(canonical.steps.length)}`);
-  console.log(`  started    ${chalk33.dim(manifest.created_at)}`);
-  console.log(`  completed  ${chalk33.dim(completedAt)}`);
+  console.log(`  started    ${chalk35.dim(manifest.created_at)}`);
+  console.log(`  completed  ${chalk35.dim(completedAt)}`);
   const models = manifest.models;
   if (models?.velocity_sec_per_step != null) {
     console.log(
-      `  velocity   ${chalk33.cyan(`~${models.velocity_sec_per_step}s/step`)} ${chalk33.dim(`(${models.total_duration_sec}s total)`)}`
+      `  velocity   ${chalk35.cyan(`~${models.velocity_sec_per_step}s/step`)} ${chalk35.dim(`(${models.total_duration_sec}s total)`)}`
     );
   }
   if (models && (models.walker || models.judge || models.matcher)) {
     const w = models.walker_reported ? `${models.walker} (${models.walker_reported})` : models.walker ?? "fast";
     const j = models.judge_reported ? `${models.judge} (${models.judge_reported})` : models.judge ?? "thorough";
-    console.log(`  models     ${chalk33.dim(`walker: ${w} \xB7 judge: ${j}`)}`);
+    console.log(`  models     ${chalk35.dim(`walker: ${w} \xB7 judge: ${j}`)}`);
   }
   console.log();
   console.log(
-    `  ${chalk33.dim("canonical:")} ${chalk33.dim(path30.relative(projectRoot, assembled.canonicalPath))}`
+    `  ${chalk35.dim("canonical:")} ${chalk35.dim(path32.relative(projectRoot, assembled.canonicalPath))}`
   );
   console.log(
-    `  ${chalk33.dim("report:")}    ${chalk33.dim(path30.relative(projectRoot, assembled.reportPath))}`
+    `  ${chalk35.dim("report:")}    ${chalk35.dim(path32.relative(projectRoot, assembled.reportPath))}`
   );
   if (extras.viewportWarning) {
     console.log();
@@ -22510,25 +23053,36 @@ function printCompletionSummary(run, completedAt, assembled, extras, provenanceA
   }
   if (extras.codeWarning) {
     console.log();
-    console.log(`  ${chalk33.yellow("!")} ${extras.codeWarning}`);
+    console.log(`  ${chalk35.yellow("!")} ${extras.codeWarning}`);
   }
   if (extras.revisit) printRevisit(extras.revisit);
   if (assembled.verification) printVerification(assembled.verification);
   if (assembled.journeyDiff) printJourneyDiff(assembled.journeyDiff);
   printProvenanceWarnings(provenanceAudit);
   printCloudRunInfo(extras.cloudInfo);
+  if (manifest.blocked) {
+    console.log();
+    console.log(
+      `  ${symbols.warning} ${chalk35.yellow("Not compared with earlier runs.")} Fix the setup (iamu set scenario ${manifest.scenario_slug} \u2026, or the persona's access) and run the scenario again.`
+    );
+    if (canonical.findings.length > 0) {
+      console.log(
+        `  ${symbols.warning} ${chalk35.yellow(`Walk recorded ${canonical.findings.length} finding(s) before being blocked.`)} Because setup was incomplete, these findings will not be verified against future runs.`
+      );
+    }
+  }
 }
 function printProvenanceWarnings(audit) {
   if (audit.warnings.length === 0) return;
   console.log();
   console.log(
-    `  ${symbols.warning} ${chalk33.yellow("Step provenance audit flagged suspicious timing:")}`
+    `  ${symbols.warning} ${chalk35.yellow("Step provenance audit flagged suspicious timing:")}`
   );
   for (const w of audit.warnings) {
-    console.log(`    ${chalk33.dim("\u2022")} ${w}`);
+    console.log(`    ${chalk35.dim("\u2022")} ${w}`);
   }
   console.log(
-    chalk33.dim(
+    chalk35.dim(
       "    Run appears to be programmatically batch-generated rather than an interactive walkthrough."
     )
   );
@@ -22560,17 +23114,17 @@ function screenshotFitsViewport(width, expected) {
 }
 async function screenshotSizeWarning(runDirPath, viewport) {
   if (!viewport) return null;
-  const dir = path30.join(runDirPath, "screenshots");
+  const dir = path32.join(runDirPath, "screenshots");
   let first;
   try {
-    first = (await fs30.readdir(dir)).filter((f) => f.toLowerCase().endsWith(".png")).sort((a, b) => a.localeCompare(b, void 0, { numeric: true }))[0];
+    first = (await fs32.readdir(dir)).filter((f) => f.toLowerCase().endsWith(".png")).sort((a, b) => a.localeCompare(b, void 0, { numeric: true }))[0];
   } catch {
     return null;
   }
   if (!first) return null;
   let size = null;
   try {
-    const handle = await fs30.open(path30.join(dir, first), "r");
+    const handle = await fs32.open(path32.join(dir, first), "r");
     try {
       const head = Buffer.alloc(24);
       const { bytesRead } = await handle.read(head, 0, 24, 0);
@@ -22587,14 +23141,16 @@ async function screenshotSizeWarning(runDirPath, viewport) {
 async function readWalkerSummary(runDirPath) {
   try {
     const data = JSON.parse(
-      await fs30.readFile(path30.join(runDirPath, "summary.json"), "utf8")
+      await fs32.readFile(path32.join(runDirPath, "summary.json"), "utf8")
     );
     const strings = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string" && x.trim() !== "") : void 0;
     const model = typeof data.model === "string" && data.model.trim() !== "" ? data.model.trim() : void 0;
+    const reason = data.blocked?.reason;
     return {
       what_worked: strings(data.what_worked),
       open_questions: strings(data.open_questions),
-      model
+      model,
+      ...typeof reason === "string" && reason.trim() !== "" ? { blocked: { reason: reason.trim() } } : {}
     };
   } catch {
     return {};
@@ -22696,7 +23252,7 @@ function validateCanonicalWalkthrough(canonical) {
 async function applyRecordedVerdicts(canonical, runDirPath) {
   try {
     const recorded = JSON.parse(
-      await fs30.readFile(path30.join(runDirPath, "verdicts.json"), "utf8")
+      await fs32.readFile(path32.join(runDirPath, "verdicts.json"), "utf8")
     );
     if (Array.isArray(recorded.verdicts)) {
       return applyVerdicts(canonical, recorded);
@@ -22706,7 +23262,7 @@ async function applyRecordedVerdicts(canonical, runDirPath) {
   return canonical;
 }
 async function persistCanonical(runDirPath, canonical) {
-  const canonicalPath = path30.join(runDirPath, "canonical.json");
+  const canonicalPath = path32.join(runDirPath, "canonical.json");
   await atomicWriteFile(
     canonicalPath,
     `${JSON.stringify(canonical, null, 2)}
@@ -22715,7 +23271,7 @@ async function persistCanonical(runDirPath, canonical) {
   return canonicalPath;
 }
 async function persistReport(runDirPath, canonical) {
-  const reportPath = path30.join(runDirPath, "report.md");
+  const reportPath = path32.join(runDirPath, "report.md");
   await atomicWriteFile(reportPath, renderCanonicalMarkdown(canonical));
   return reportPath;
 }
@@ -22727,7 +23283,7 @@ async function assembleRun(projectRoot, runId, manifest, completedAt) {
     completedAt,
     await readWalkerSummary(runDirPath)
   );
-  const verification = await compareWithBaseline(
+  const verification = manifest.blocked ? null : await compareWithBaseline(
     projectRoot,
     manifest.scenario_slug,
     runId,
@@ -22815,17 +23371,17 @@ function placeLabel(p) {
 function printRevisit(r) {
   const missed = r.places.filter((p) => !p.reached);
   console.log();
-  const head = `  ${chalk33.bold("Re-check places:")} reached ${r.reached} of ${r.requested}`;
+  const head = `  ${chalk35.bold("Re-check places:")} reached ${r.reached} of ${r.requested}`;
   if (missed.length === 0) {
-    console.log(`${head} ${chalk33.green("\u2713")}`);
+    console.log(`${head} ${chalk35.green("\u2713")}`);
     return;
   }
   console.log(`${head} \u2014 not reached:`);
   for (const p of missed) {
-    console.log(`    ${chalk33.yellow("\u25CB")} ${placeLabel(p)}`);
+    console.log(`    ${chalk35.yellow("\u25CB")} ${placeLabel(p)}`);
   }
   console.log(
-    chalk33.dim(
+    chalk35.dim(
       "    Fixes there stay awaiting a re-run until a walk gets there."
     )
   );
@@ -22833,7 +23389,7 @@ function printRevisit(r) {
 function printVerification(verification) {
   console.log();
   console.log(
-    chalk33.bold("  Since this scenario's last run") + chalk33.dim(` (${verification.baseline_run_id.slice(0, 30)}\u2026)`) + chalk33.bold(":")
+    chalk35.bold("  Since this scenario's last run") + chalk35.dim(` (${verification.baseline_run_id.slice(0, 30)}\u2026)`) + chalk35.bold(":")
   );
   if (verification.resolved.length > 0) {
     console.log(
@@ -22842,7 +23398,7 @@ function printVerification(verification) {
   }
   if (verification.not_observed.length > 0) {
     console.log(
-      `    ${symbols.pending} ${verification.not_observed.length} not seen this run ${chalk33.dim("(not evidence of a fix)")}`
+      `    ${symbols.pending} ${verification.not_observed.length} not seen this run ${chalk35.dim("(not evidence of a fix)")}`
     );
   }
   if (verification.persists.length > 0) {
@@ -22884,14 +23440,14 @@ __export(match_exports, {
   match: () => match,
   matchRecord: () => matchRecord
 });
-import { promises as fs31 } from "fs";
-import path31 from "path";
-import chalk34 from "chalk";
+import { promises as fs33 } from "fs";
+import path33 from "path";
+import chalk36 from "chalk";
 async function completedManifest2(runDirPath, runId, opts) {
   let manifest;
   try {
     manifest = JSON.parse(
-      await fs31.readFile(path31.join(runDirPath, "walkthrough.json"), "utf8")
+      await fs33.readFile(path33.join(runDirPath, "walkthrough.json"), "utf8")
     );
   } catch {
     commandError(`Run not found: ${runId}`, opts);
@@ -22918,14 +23474,14 @@ async function match(runId, opts) {
     runId,
     manifest.scenario_slug
   );
-  const needed = input.current.length > 0 && (input.prior.length > 0 || (input.guidance ?? []).length > 0);
+  const needed = !manifest.blocked && input.current.length > 0 && (input.prior.length > 0 || (input.guidance ?? []).length > 0);
   const prompt = needed ? composeMatchPrompt(input) : null;
-  const promptFilePath = opts?.promptFile ?? path31.join(runDirPath, "match_prompt.md");
+  const promptFilePath = opts?.promptFile ?? path33.join(runDirPath, "match_prompt.md");
   if (prompt) {
-    await fs31.writeFile(promptFilePath, prompt, "utf8");
+    await fs33.writeFile(promptFilePath, prompt, "utf8");
   } else {
     try {
-      await fs31.unlink(promptFilePath);
+      await fs33.unlink(promptFilePath);
     } catch {
     }
   }
@@ -22935,8 +23491,9 @@ async function match(runId, opts) {
         {
           ...input,
           needed,
-          prompt_file: prompt ? path31.relative(ctx.projectRoot, promptFilePath) : null,
-          prompt_file_abs: prompt ? path31.resolve(promptFilePath) : null,
+          ...manifest.blocked ? { blocked: manifest.blocked } : {},
+          prompt_file: prompt ? path33.relative(ctx.projectRoot, promptFilePath) : null,
+          prompt_file_abs: prompt ? path33.resolve(promptFilePath) : null,
           match_prompt: prompt
         },
         null,
@@ -22947,7 +23504,7 @@ async function match(runId, opts) {
   }
   if (!prompt) {
     console.log(
-      chalk34.dim(
+      chalk36.dim(
         "  No earlier findings or tester guidance for this scenario to match against \u2014 nothing to do."
       )
     );
@@ -22979,7 +23536,7 @@ async function matchRecord(runId, opts) {
       }
       raw = Buffer.concat(chunks).toString("utf8");
     } else {
-      raw = await fs31.readFile(opts.file, "utf8");
+      raw = await fs33.readFile(opts.file, "utf8");
     }
     answer = JSON.parse(raw);
   } catch (err) {
@@ -23025,17 +23582,17 @@ async function matchRecord(runId, opts) {
   }
   console.log();
   console.log(
-    `  ${chalk34.green("\u2713")} Matched ${result.linked} finding${result.linked === 1 ? "" : "s"} to earlier ones, ${result.new} first seen, ${result.rechecked_fixed} earlier re-checked fixed`
+    `  ${chalk36.green("\u2713")} Matched ${result.linked} finding${result.linked === 1 ? "" : "s"} to earlier ones, ${result.new} first seen, ${result.rechecked_fixed} earlier re-checked fixed`
   );
   if (result.suppressed > 0) {
     console.log(
-      `  ${chalk34.yellow("!")} ${result.suppressed} finding${result.suppressed === 1 ? "" : "s"} match tester guidance (flagged with suppressed_by_guidance \u2014 dismiss them in triage if the rule holds)`
+      `  ${chalk36.yellow("!")} ${result.suppressed} finding${result.suppressed === 1 ? "" : "s"} match tester guidance (flagged with suppressed_by_guidance \u2014 dismiss them in triage if the rule holds)`
     );
   }
   if (verification) printVerification(verification);
   console.log();
   console.log(
-    chalk34.dim("  Run `iamu sync` to push the linked findings to the cloud.")
+    chalk36.dim("  Run `iamu sync` to push the linked findings to the cloud.")
   );
   console.log();
 }
@@ -23057,7 +23614,7 @@ __export(prune_exports, {
   prune: () => prune
 });
 import { confirm, isCancel as isCancel5 } from "@clack/prompts";
-import chalk35 from "chalk";
+import chalk37 from "chalk";
 function formatBytes(bytes) {
   if (bytes <= 0) return "0 B";
   if (bytes < 1024) return `${bytes} B`;
@@ -23103,7 +23660,7 @@ async function prune(opts = {}) {
     });
     if (preview.prunedRuns.length === 0) {
       console.log(
-        chalk35.dim("  No runs match the pruning criteria. Nothing to prune.")
+        chalk37.dim("  No runs match the pruning criteria. Nothing to prune.")
       );
       return preview;
     }
@@ -23112,7 +23669,7 @@ async function prune(opts = {}) {
       message: `Prune ${mode} ${preview.prunedRuns.length} run(s) and reclaim ${formatBytes(preview.totalBytesReclaimed)}?`
     });
     if (isCancel5(confirmed) || !confirmed) {
-      console.log(chalk35.yellow("  Pruning cancelled."));
+      console.log(chalk37.yellow("  Pruning cancelled."));
       return;
     }
   }
@@ -23123,14 +23680,14 @@ async function prune(opts = {}) {
   }
   if (result.dryRun) {
     console.log(
-      chalk35.cyan(
+      chalk37.cyan(
         `
   [DRY RUN] Would prune ${result.prunedRuns.length} of ${result.totalRunsScanned} run(s):`
       )
     );
   } else {
     console.log(
-      chalk35.bold(
+      chalk37.bold(
         `
   ${symbols.success} Pruned ${result.prunedRuns.length} of ${result.totalRunsScanned} run(s):`
       )
@@ -23138,18 +23695,18 @@ async function prune(opts = {}) {
   }
   if (result.prunedRuns.length === 0) {
     console.log(
-      chalk35.dim("    No runs matched the pruning criteria. Nothing pruned.")
+      chalk37.dim("    No runs matched the pruning criteria. Nothing pruned.")
     );
   } else {
     for (const run of result.prunedRuns) {
       const mode = run.fullyDeleted ? "removed" : "screenshots purged";
       const count = run.screenshotsDeleted > 0 ? `${run.screenshotsDeleted} screenshots, ` : "";
       console.log(
-        `    ${chalk35.dim("\u2022")} ${chalk35.bold(run.runId)} ${chalk35.dim(`(${run.scenarioSlug ?? "unknown scenario"})`)}: ${chalk35.yellow(formatBytes(run.bytesReclaimed))} (${count}${mode})`
+        `    ${chalk37.dim("\u2022")} ${chalk37.bold(run.runId)} ${chalk37.dim(`(${run.scenarioSlug ?? "unknown scenario"})`)}: ${chalk37.yellow(formatBytes(run.bytesReclaimed))} (${count}${mode})`
       );
     }
     console.log(
-      chalk35.dim(
+      chalk37.dim(
         `
   Total reclaimed: ${formatBytes(result.totalBytesReclaimed)} (${result.totalScreenshotsDeleted} screenshots deleted)
 `
@@ -23338,9 +23895,9 @@ function registerProjectCommands(program) {
     "after",
     "\nExamples:\n  $ iamu validate --all\n  $ iamu validate --all --fix --dry-run\n  $ iamu validate iamu/personas/maria.md"
   ).action(
-    async (path32, opts) => {
+    async (path34, opts) => {
       const { validate: validate2 } = await Promise.resolve().then(() => (init_validate(), validate_exports));
-      await validate2(path32, opts);
+      await validate2(path34, opts);
     }
   );
   program.command("update").helpGroup("Project:").description("Update and repair agent skills and prompts to latest version").option(
@@ -23392,6 +23949,51 @@ 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)"
+  ).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(
+    "--state-description <text>",
+    "What the world must contain, in domain words (scenario)"
+  ).option(
+    "--state-approximation <text>",
+    "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(
+    "--paths <paths>",
+    "Route prefixes, comma-separated; replaces the list (capability)"
+  ).option("--no-paths", "Clear route prefixes (capability)").option(
+    "--add-path <path>",
+    "Add a route prefix (capability, repeatable)",
+    (val, prev = []) => [...prev, val]
+  ).option(
+    "--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(
+    "--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'
+  ).action(
+    async (type2, slug, opts) => {
+      const { setEntity: setEntity2 } = await Promise.resolve().then(() => (init_set_entity(), set_entity_exports));
+      await setEntity2(type2, slug, opts);
+    }
+  );
+  program.command("edit <type> <slug>").helpGroup("Project:").description(
+    "Open an entity file in your editor ($VISUAL or $EDITOR) and validate on exit"
+  ).option("--json", "Output as JSON").action(
+    async (type2, slug, opts = {}) => {
+      const { editEntity: editEntity2 } = await Promise.resolve().then(() => (init_edit_entity(), edit_entity_exports));
+      await editEntity2(type2, slug, opts);
+    }
+  );
   const explore = program.command("explore").helpGroup("Project:").description(
     "Map the running product with a read-only crawl; compare the map with runs (coverage) or with another map (diff)"
   );
@@ -23593,14 +24195,17 @@ function registerWalkthroughCommands(program) {
     }
   );
   program.command("summary [run-id]").helpGroup("Walkthrough:").description(
-    "Record walker summary (what worked, open questions) atomically"
+    "Record walker summary (what worked, open questions, or that the walk was blocked) atomically"
   ).option("--run <run-id>", "Run ID (or pass as positional argument)").option(
     "--worked <note...>",
     "Things that worked well (can be specified multiple times)"
   ).option(
     "--question <note...>",
     "Open questions that arose (can be specified multiple times)"
-  ).option("--model <name>", "Model identifier (e.g. flash, haiku)").option("--file <path>", "Path to summary JSON file (or - for stdin)").option("--json", "Output as JSON").action(
+  ).option("--model <name>", "Model identifier (e.g. flash, haiku)").option(
+    "--blocked <reason>",
+    "The walk could not start as set up (persona unreachable, world missing): what was missing"
+  ).option("--no-blocked", "Clear the blocked status (if previously set)").option("--file <path>", "Path to summary JSON file (or - for stdin)").option("--json", "Output as JSON").action(
     async (runIdArg, opts) => {
       const { summaryCommand: summaryCommand2 } = await Promise.resolve().then(() => (init_summary(), summary_exports));
       await summaryCommand2(runIdArg, opts);
@@ -23674,7 +24279,7 @@ function registerAllCommands(program) {
 
 // src/ui/panic.ts
 init_logger();
-import chalk36 from "chalk";
+import chalk38 from "chalk";
 var handlersRegistered = false;
 var customSigintHandler = null;
 function registerSigintCleanup(handler) {
@@ -23686,17 +24291,17 @@ function registerSigintCleanup(handler) {
 function logFatalAndExit(title, errOrReason) {
   process.stderr.write("\x1B[?25h");
   if (isVerbose()) {
-    console.error(chalk36.red(`
+    console.error(chalk38.red(`
   ${title}:`));
     console.error(
       errOrReason instanceof Error ? errOrReason.stack || errOrReason : errOrReason
     );
   } else {
     const msg = errOrReason instanceof Error ? errOrReason.message : String(errOrReason);
-    console.error(chalk36.red(`
+    console.error(chalk38.red(`
   Fatal Error: ${msg}`));
     console.error(
-      chalk36.dim(
+      chalk38.dim(
         "  Run with --verbose or DEBUG=1 to view the full stack trace.\n"
       )
     );
@@ -23715,7 +24320,7 @@ function setupProcessHandlers() {
       }
       process.exit(130);
     } else {
-      console.error(chalk36.dim("\n  Operation cancelled."));
+      console.error(chalk38.dim("\n  Operation cancelled."));
       process.exit(130);
     }
   });