@catalyst-cloud/cli 0.13.0 → 0.14.0

package/skills/catalyst-onboard/scripts/where-am-i.mjs

@@ -7,13 +7,26 @@
 // owner's name on it, never as something the person at this keyboard can fix by running anything.
 //
 // Every count and every name below is read off what a verb printed. Nothing here is written down.
-import { cliTarget, CONNECT_LINE, parseFlags, printHelp, runCli, tryJson, tryLoadConfig } from "./lib/cli.mjs";
+import {
+  cliTarget,
+  CONNECT_LINE,
+  parseFlags,
+  printHelp,
+  runCli,
+  tryJson,
+  tryLoadConfig,
+} from "./lib/cli.mjs";
+import { projectCoverageLines } from "./lib/project-coverage.mjs";
 import { spawnSync } from "node:child_process";
 import { runLocalSync } from "./local-sync.mjs";
 
 const SPEC = {
   next: { help: "print only the single next step" },
   json: { help: "one JSON document instead of the report" },
+  repo: {
+    value: true,
+    help: "a checkout of a mapped repository on this machine: its agent setup (AGENTS.md block, portable layout) is read and reported, never changed",
+  },
 };
 const NOTES = [
   "Reads, in this order: `status` (machine), `ready --json` (machine checks and project checks, kept apart),",
@@ -22,6 +35,8 @@ const NOTES = [
   "`contract --path codingAccounts` and `accounts --json` (coding accounts, and which one needs a new credential), and each",
   "project's hosts_current check with its fixedWhere (host), and each project's environment_declared check with its per-repository notes (repository declarations). The teams read is refreshed, so a mapping just saved reads back mapped.",
   "Reads `capabilities --json` once: when the installed CLI can run a step for this person's role (`team check`, `team map`), the next step is that command; otherwise the page, with who can.",
+  "Reads `legacy --json` when the CLI has the verb: leftovers of the old local Catalyst runtime become a machine line and a note; removing them is the person's yes.",
+  "With --repo <path>, reads `repo agent-setup <path> --json` (a read; nothing changes) and adds a `repository agent setup` part that never blocks: the Catalyst block in AGENTS.md and the portable layout, with the writes named for the person to approve.",
   "Also runs `gh repo view <owner>/thoughts` for each registered repository's owner, as a note: it shows the repository exists, never that the GitHub App can reach it.",
   "When the tenant serves a contract version this CLI refuses, runs `npm view @catalyst-cloud/cli version` once to say whether a newer CLI is published.",
   "Writes nothing and changes nothing. Runs before this machine is connected — that is one of the states it reports.",
@@ -29,7 +44,11 @@ const NOTES = [
 
 const { help, flags, positionals } = parseFlags(process.argv.slice(2), SPEC);
 if (help) {
-  printHelp("node scripts/where-am-i.mjs [--next] [--json]", SPEC, NOTES);
+  printHelp(
+    "node scripts/where-am-i.mjs [--next] [--json] [--repo <path>]",
+    SPEC,
+    NOTES,
+  );
   process.exit(0);
 }
 if (positionals.length > 0) {
@@ -52,13 +71,32 @@ let repositoryRegistered = false;
 let capabilities = null;
 let personRole = null;
 const canManage = () => personRole === "admin" || personRole === "owner";
-const capability = (verb) => (Array.isArray(capabilities) ? capabilities.find((c) => c && c.verb === verb) : undefined);
-const verbAvailable = (verb) => { const c = capability(verb); return c?.availability === "available" && (c.needs === "member" || canManage()); };
-const verbAdminOnly = (verb) => { const c = capability(verb); return c?.availability === "available" && c.needs === "admin" && !canManage(); };
+const capability = (verb) =>
+  Array.isArray(capabilities)
+    ? capabilities.find((c) => c && c.verb === verb)
+    : undefined;
+const verbAvailable = (verb) => {
+  const c = capability(verb);
+  return (
+    c?.availability === "available" && (c.needs === "member" || canManage())
+  );
+};
+const verbAdminOnly = (verb) => {
+  const c = capability(verb);
+  return c?.availability === "available" && c.needs === "admin" && !canManage();
+};
 // `blocking` is false for a finding that is real and reportable but does not stop the next step —
 // an unmatched Linear identity is the one that matters: it must be said, and it must not become the
 // thing the person is told to go and do before they can map a project.
-const add = (part, instrument, verdict, lines, owner = null, where = null, blocking = true) => {
+const add = (
+  part,
+  instrument,
+  verdict,
+  lines,
+  owner = null,
+  where = null,
+  blocking = true,
+) => {
   const p = { part, instrument, verdict, lines, owner, where, blocking };
   parts.push(p);
   return p;
@@ -70,8 +108,12 @@ const add = (part, instrument, verdict, lines, owner = null, where = null, block
 let contractMismatch = null;
 const noteMismatch = (text) => {
   const m =
-    (text ?? "").match(/serves contract version (\S+) but this bundle accepts (\S+)/) ??
-    (text ?? "").match(/contract: version (\S+) is outside this bundle's range (\S+)/);
+    (text ?? "").match(
+      /serves contract version (\S+) but this bundle accepts (\S+)/,
+    ) ??
+    (text ?? "").match(
+      /contract: version (\S+) is outside this bundle's range (\S+)/,
+    );
   if (m !== null) contractMismatch ??= { served: m[1], accepts: m[2] };
   return m !== null;
 };
@@ -85,10 +127,15 @@ const readContract = (args) => {
 const status = runCli(["status"]);
 if (!status.ran) {
   process.stderr.write(`${status.stderr}\n`);
-  process.stderr.write(`the catalyst CLI could not be started. Install it, then run this again.\n`);
+  process.stderr.write(
+    `the catalyst CLI could not be started. Install it, then run this again.\n`,
+  );
   process.exit(2);
 }
-const statusLines = status.stdout.split("\n").map((l) => l.trim()).filter(Boolean);
+const statusLines = status.stdout
+  .split("\n")
+  .map((l) => l.trim())
+  .filter(Boolean);
 const field = (name) => {
   const line = statusLines.find((l) => l.startsWith(`${name}:`));
   return line ? line.slice(name.length + 1).trim() : null;
@@ -99,9 +146,12 @@ const connected = tenant !== null && tryLoadConfig() !== null;
 // The app and the API share an origin; the base URL is whatever this machine was connected to, so
 // no page link in this report is a host anyone typed from memory.
 const cloud = api === null ? null : api.split(" ")[0].replace(/\/+$/, "");
-const link = (path) => (cloud === null ? `<your cloud>${path}` : `${cloud}${path}`);
+const link = (path) =>
+  cloud === null ? `<your cloud>${path}` : `${cloud}${path}`;
 
-const machineLines = connected ? statusLines : [statusLines[0] ?? "status printed nothing"];
+const machineLines = connected
+  ? statusLines
+  : [statusLines[0] ?? "status printed nothing"];
 let machineVerdict = connected ? "ok" : "unfinished";
 
 // `ready` is ONE verdict over two parts; split it by check id before anything is reported. A check
@@ -114,19 +164,30 @@ if (connected) {
   const report = tryJson(ready.stdout);
   const checks = Array.isArray(report?.checks) ? report.checks : null;
   if (checks === null) {
-    machineLines.push(`ready: could not be read (${(ready.stderr || ready.stdout).trim().split("\n")[0] ?? "no output"})`);
+    machineLines.push(
+      `ready: could not be read (${(ready.stderr || ready.stdout).trim().split("\n")[0] ?? "no output"})`,
+    );
     machineVerdict = "unfinished";
   } else {
-    projectChecks = checks.filter((c) => typeof c.id === "string" && c.id.startsWith("team:"));
-    const machineChecks = checks.filter((c) => !(typeof c.id === "string" && c.id.startsWith("team:")));
+    projectChecks = checks.filter(
+      (c) => typeof c.id === "string" && c.id.startsWith("team:"),
+    );
+    const machineChecks = checks.filter(
+      (c) => !(typeof c.id === "string" && c.id.startsWith("team:")),
+    );
     const failed = machineChecks.filter((c) => !c.ok && !c.note);
     // A refused contract version is printed without the CLI's "update" fix: whether an update exists
     // is checked below, once, against what npm has published.
     const refused = (c) => !c.ok && !c.note && noteMismatch(c.line);
-    for (const c of machineChecks) machineLines.push(`${c.note ? "note" : c.ok ? "ok  " : "FAIL"} ${c.line}${!c.ok && !c.note && c.fix && !refused(c) ? ` — fix: ${c.fix}` : ""}`);
+    for (const c of machineChecks)
+      machineLines.push(
+        `${c.note ? "note" : c.ok ? "ok  " : "FAIL"} ${c.line}${!c.ok && !c.note && c.fix && !refused(c) ? ` — fix: ${c.fix}` : ""}`,
+      );
     if (failed.length > 0) {
       machineVerdict = "unfinished";
-      machineFix = failed.find((c) => typeof c.fix === "string" && !refused(c))?.fix ?? null;
+      machineFix =
+        failed.find((c) => typeof c.fix === "string" && !refused(c))?.fix ??
+        null;
     }
   }
   // Supplemental only: local caches are optional and do not change setup completion or --next.
@@ -136,7 +197,11 @@ if (connected) {
   );
 } else {
   localSync = {
-    assessment: { verdict: "unknown", current: false, reason: "connect this machine before local freshness can be checked" },
+    assessment: {
+      verdict: "unknown",
+      current: false,
+      reason: "connect this machine before local freshness can be checked",
+    },
     started: false,
     recovery: "catalyst login",
   };
@@ -149,40 +214,88 @@ add(
   "you, on this machine",
   // The keyless login alone: a person who holds a personal key already knows the key form. A machine
   // that holds the CLI is told its own command; only one with no CLI at all gets the npx line.
-  connected ? null : cliTarget().recorded ? "catalyst login" : CONNECT_LINE.split(" (or")[0],
+  connected
+    ? null
+    : cliTarget().recorded
+      ? "catalyst login"
+      : CONNECT_LINE.split(" (or")[0],
 );
 if (connected) {
   const capDoc = tryJson(runCli(["capabilities", "--json"]).stdout);
-  capabilities = Array.isArray(capDoc?.capabilities) ? capDoc.capabilities : null;
+  capabilities = Array.isArray(capDoc?.capabilities)
+    ? capDoc.capabilities
+    : null;
+}
+// Leftovers of the old local Catalyst runtime (its plugin, jobs, commands, state), from the CLI's own
+// fixed list. Reported on the machine part and as a note; removal is the person's yes, never this script's.
+let legacyNote = null;
+if (verbAvailable("legacy")) {
+  const legacyDoc = tryJson(runCli(["legacy", "--json"]).stdout);
+  const found = Array.isArray(legacyDoc?.found) ? legacyDoc.found : [];
+  if (found.length > 0) {
+    const machine = parts.find((p) => p.part === "machine");
+    const names = found.map((f) => `${f.kind} ${f.name}`);
+    machine?.lines.push(
+      `note leftovers of the old local Catalyst runtime (${found.length}): ${names.slice(0, 6).join(", ")}${found.length > 6 ? ", …" : ""}; removing them is strongly recommended: catalyst legacy --remove (the data folders are a separate yes, --data)`,
+    );
+    legacyNote = `this machine still carries ${found.length} piece${found.length === 1 ? "" : "s"} of the old local Catalyst runtime (${names.slice(0, 4).join(", ")}${found.length > 4 ? ", …" : ""}); offer catalyst legacy --remove once, strongly recommended, then --data as a separate question`;
+  }
 }
 
 // ── person ────────────────────────────────────────────────────────────────────────────────────────
 if (!connected) {
-  add("person", "catalyst me", "unreadable", ["not readable until this machine is connected"], null, null);
+  add(
+    "person",
+    "catalyst me",
+    "unreadable",
+    ["not readable until this machine is connected"],
+    null,
+    null,
+  );
 } else {
   const me = runCli(["me", "--json"]);
   const doc = tryJson(me.stdout);
-  const user = doc && typeof doc.user === "object" && doc.user !== null ? doc.user : null;
+  const user =
+    doc && typeof doc.user === "object" && doc.user !== null ? doc.user : null;
   if (doc === null) {
-    add("person", "catalyst me", "unreadable", [`me could not be read (${(me.stderr || me.stdout).trim().split("\n")[0] ?? "no output"})`], null, null).next =
+    add(
+      "person",
+      "catalyst me",
+      "unreadable",
+      [
+        `me could not be read (${(me.stderr || me.stdout).trim().split("\n")[0] ?? "no output"})`,
+      ],
+      null,
+      null,
+    ).next =
       "run this again; catalyst me could not be read, so no step after it can be named yet";
   } else if (user === null) {
     add(
       "person",
       "catalyst me",
       "unfinished",
-      ["this credential names no person — it is a host credential, so nothing an agent writes will carry a name"],
+      [
+        "this credential names no person — it is a host credential, so nothing an agent writes will carry a name",
+      ],
       "you: connect again with your own login",
       CONNECT_LINE,
     );
   } else {
-    const matched = typeof user.linearUserId === "string" && user.linearUserId !== "";
+    const matched =
+      typeof user.linearUserId === "string" && user.linearUserId !== "";
     personRole = typeof user.role === "string" ? user.role : null;
     const grantLines = [];
     for (const provider of ["linear", "github"]) {
-      const read = runCli(["connections", "personal", provider, "status", "--json"]);
+      const read = runCli([
+        "connections",
+        "personal",
+        provider,
+        "status",
+        "--json",
+      ]);
       const result = tryJson(read.stdout);
-      const outcome = typeof result?.outcome === "string" ? result.outcome : "unreadable";
+      const outcome =
+        typeof result?.outcome === "string" ? result.outcome : "unreadable";
       personalConnections[provider] = outcome;
       if (outcome === "connected") {
         grantLines.push(`personal ${provider}: connected`);
@@ -190,23 +303,43 @@ if (!connected) {
         personalGrantIncomplete = true;
         if (provider === "linear") personalLinearIncomplete = true;
         else personalGithubIncomplete = true;
-        grantLines.push(`personal ${provider}: ${outcome === "absent" ? "not connected" : "expired"}`);
-        if (provider === "linear") personalNext ??= "connect your personal linear account";
+        grantLines.push(
+          `personal ${provider}: ${outcome === "absent" ? "not connected" : "expired"}`,
+        );
+        if (provider === "linear")
+          personalNext ??= "connect your personal linear account";
       } else {
         personalGrantIncomplete = true;
         if (provider === "linear") personalLinearIncomplete = true;
         else personalGithubIncomplete = true;
-        grantLines.push(`personal ${provider}: ${outcome === "unavailable" ? "temporarily unavailable; grant state unknown" : "could not be checked; update the catalyst CLI or inspect its status output"}`);
-        if (provider === "linear") personalNext ??= "re-check your personal linear connection";
+        grantLines.push(
+          `personal ${provider}: ${outcome === "unavailable" ? "temporarily unavailable; grant state unknown" : "could not be checked; update the catalyst CLI or inspect its status output"}`,
+        );
+        if (provider === "linear")
+          personalNext ??= "re-check your personal linear connection";
       }
     }
     add(
       "person",
       "catalyst me, and catalyst connections personal <provider> status --json",
       matched && !personalGrantIncomplete ? "ok" : "unfinished",
-      [`${user.label ?? "(unnamed)"} (${user.role ?? "role unknown"})`, matched ? "Linear identity matched" : "Linear identity NOT matched — asks assigned to you cannot be told apart from everyone else's. It blocks nothing below. Run catalyst identity linear options for self-service recovery; personal Linear consent normally binds its viewer automatically.", ...grantLines],
-      personalGrantIncomplete ? "you" : matched ? null : "a workspace owner or admin",
-      personalGrantIncomplete ? "catalyst connections personal <provider> start or status" : matched ? null : link("/settings/account"),
+      [
+        `${user.label ?? "(unnamed)"} (${user.role ?? "role unknown"})`,
+        matched
+          ? "Linear identity matched"
+          : "Linear identity NOT matched — asks assigned to you cannot be told apart from everyone else's. It blocks nothing below. Run catalyst identity linear options for self-service recovery; personal Linear consent normally binds its viewer automatically.",
+        ...grantLines,
+      ],
+      personalGrantIncomplete
+        ? "you"
+        : matched
+          ? null
+          : "a workspace owner or admin",
+      personalGrantIncomplete
+        ? "catalyst connections personal <provider> start or status"
+        : matched
+          ? null
+          : link("/settings/account"),
       false,
     );
   }
@@ -214,15 +347,38 @@ if (!connected) {
 
 // ── account ───────────────────────────────────────────────────────────────────────────────────────
 if (!connected) {
-  add("account", "catalyst contract --path account", "unreadable", ["not readable until this machine is connected"], null, null);
+  add(
+    "account",
+    "catalyst contract --path account",
+    "unreadable",
+    ["not readable until this machine is connected"],
+    null,
+    null,
+  );
 } else {
   const acct = readContract(["contract", "--path", "account", "--json"]);
   const doc = tryJson(acct.stdout);
   if (doc === null) {
-    add("account", "catalyst contract --path account", "unreadable", ["the account block could not be read — try: catalyst contract --refresh"], null, null).next =
+    add(
+      "account",
+      "catalyst contract --path account",
+      "unreadable",
+      [
+        "the account block could not be read — try: catalyst contract --refresh",
+      ],
+      null,
+      null,
+    ).next =
       "refresh the contract (catalyst contract --refresh), then run this again; the account could not be read, so no step after it can be named yet";
   } else {
-    const workspace = typeof doc.linearWorkspaceSlug === "string" && doc.linearWorkspaceSlug !== "" ? doc.linearWorkspaceSlug : typeof doc.linearWorkspaceId === "string" && doc.linearWorkspaceId !== "" ? doc.linearWorkspaceId : null;
+    const workspace =
+      typeof doc.linearWorkspaceSlug === "string" &&
+      doc.linearWorkspaceSlug !== ""
+        ? doc.linearWorkspaceSlug
+        : typeof doc.linearWorkspaceId === "string" &&
+            doc.linearWorkspaceId !== ""
+          ? doc.linearWorkspaceId
+          : null;
     workspaceResolved = workspace !== null;
     // The declaration is the one part of the account a key can also READ — and it is the one part a
     // key can WRITE, so it is reported here rather than left to the settings page like the rest.
@@ -230,14 +386,29 @@ if (!connected) {
     const env = runCli(["environment", "read", "--json"]);
     const envDoc = tryJson(env.stdout);
     if (envDoc === null) {
-      envLines.push(`environment: not readable (${(env.stderr || env.stdout).trim().split("\n")[0] ?? "no output"})`);
+      envLines.push(
+        `environment: not readable (${(env.stderr || env.stdout).trim().split("\n")[0] ?? "no output"})`,
+      );
     } else if (envDoc.current === null || envDoc.current === undefined) {
-      envLines.push("environment: nothing declared yet — declare it with `catalyst environment propose --file <path> --approve`");
+      envLines.push(
+        "environment: nothing declared yet — declare it with `catalyst environment propose --file <path> --approve`",
+      );
     } else {
-      envLines.push(`environment: revision ${envDoc.current.revision} (${envDoc.current.canonicalHash}), ${envDoc.isApproved ? "approved" : "NOT approved — a proposal nobody approved changes nothing"}`);
-      envLines.push(envDoc.delivered ? `environment delivered to phases: revision ${envDoc.delivered.revision}` : "environment delivered to phases: nothing yet");
-      const unresolved = Array.isArray(envDoc.unresolvedReferences) ? envDoc.unresolvedReferences : [];
-      if (unresolved.length > 0) envLines.push(`environment names values this tenant does not carry yet: ${unresolved.join(", ")}`);
+      envLines.push(
+        `environment: revision ${envDoc.current.revision} (${envDoc.current.canonicalHash}), ${envDoc.isApproved ? "approved" : "NOT approved — a proposal nobody approved changes nothing"}`,
+      );
+      envLines.push(
+        envDoc.delivered
+          ? `environment delivered to phases: revision ${envDoc.delivered.revision}`
+          : "environment delivered to phases: nothing yet",
+      );
+      const unresolved = Array.isArray(envDoc.unresolvedReferences)
+        ? envDoc.unresolvedReferences
+        : [];
+      if (unresolved.length > 0)
+        envLines.push(
+          `environment names values this tenant does not carry yet: ${unresolved.join(", ")}`,
+        );
     }
     add(
       "account",
@@ -245,7 +416,9 @@ if (!connected) {
       workspace === null ? "unfinished" : "ok",
       [
         `${doc.name ?? "(unnamed tenant)"} (${doc.slug ?? "?"})`,
-        workspace === null ? "no Linear workspace resolved on this contract" : `Linear workspace resolved: ${workspace}`,
+        workspace === null
+          ? "no Linear workspace resolved on this contract"
+          : `Linear workspace resolved: ${workspace}`,
         "the GitHub App install is NOT carried here — the connections page is the only place that shows it",
         ...envLines,
       ],
@@ -262,12 +435,14 @@ let teamRows = null;
 let readinessMetaCache;
 const readinessMeta = () => {
   if (readinessMetaCache === undefined) {
-    const m = tryJson(readContract(["contract", "--path", "readinessChecks", "--json"]).stdout);
+    const m = tryJson(
+      readContract(["contract", "--path", "readinessChecks", "--json"]).stdout,
+    );
     readinessMetaCache = Array.isArray(m) ? m : [];
   }
   return readinessMetaCache;
 };
-// Linear's own Git automation rules, by check id, as the Settings → Workflow → Git automation screen
+// Linear's own Git automation rules, by check id, as the Settings → Teams → <team> → Workflow → Workflows & automations screen
 // names them. A rule that moves a card is a conflict with the stage Catalyst manages, and no Catalyst
 // key can change a Linear automation rule: the fix is in Linear, by a Linear admin.
 const LINEAR_AUTOMATION_RULES = {
@@ -280,27 +455,49 @@ let blockedProjects = [];
 
 // ── projects (a project is one Linear team) ───────────────────────────────────────────────────────
 if (!connected) {
-  add("projects", "catalyst contract --path teams", "unreadable", ["not readable until this machine is connected"], null, null);
+  add(
+    "projects",
+    "catalyst contract --path teams",
+    "unreadable",
+    ["not readable until this machine is connected"],
+    null,
+    null,
+  );
 } else {
   // The mapping write updates the cloud before the cached contract's dispatchGate projection.
   // Revalidate this one read so a successful save does not appear unmapped on the next step.
-  const teams = readContract(["contract", "--refresh", "--path", "teams", "--json"]);
+  const teams = readContract([
+    "contract",
+    "--refresh",
+    "--path",
+    "teams",
+    "--json",
+  ]);
   const doc = tryJson(teams.stdout);
   const rows = Array.isArray(doc) ? doc : null;
   teamRows = rows;
   if (rows === null) {
-    add("projects", "catalyst contract --path teams", "unreadable", ["the project list could not be read — try: catalyst contract --refresh"], null, null).next =
+    add(
+      "projects",
+      "catalyst contract --path teams",
+      "unreadable",
+      ["the project list could not be read — try: catalyst contract --refresh"],
+      null,
+      null,
+    ).next =
       "refresh the contract (catalyst contract --refresh), then run this again; the project list could not be read, so no step after it can be named yet";
   } else {
-    const lines = [`${rows.length} mapped`];
-    for (const t of rows) {
-      const key = t.key ?? t.id ?? "(unkeyed)";
-      const readiness = t.readiness ?? {};
-      const bad = Array.isArray(readiness.checks) ? readiness.checks.filter((c) => c.state !== "pass") : [];
-      lines.push(`${key}: ${readiness.status ?? "unknown"}${bad.length ? ` — ${bad.map((c) => `${c.id} ${c.state}`).join(", ")}` : ""}`);
-    }
-    for (const c of projectChecks) lines.push(`${c.ok ? "note" : "FAIL"} ${c.line}${c.who ? ` — who: ${c.who}` : ""}`);
-    lines.push("MAPPED projects only. An empty list means nothing is mapped yet, NOT that there are no projects. Run catalyst team list to inspect the live list without checking readiness.");
+    const inventory = runCli(["project", "list", "--json"]);
+    const projects = tryJson(inventory.stdout);
+    const lines = Array.isArray(projects)
+      ? projectCoverageLines(projects, rows).lines
+      : [
+          `the full project inventory could not be read (${(inventory.stderr || inventory.stdout).trim().split("\n")[0] ?? "no output"})`,
+        ];
+    for (const c of projectChecks)
+      lines.push(
+        `${c.ok ? "note" : "FAIL"} ${c.line}${c.who ? ` — who: ${c.who}` : ""}`,
+      );
     // A project is set up when its dispatch gate is open (its stages are mapped), or when its
     // readiness reads ready. Readiness alone kept `--next` on "map its stages" for a tenant whose
     // gates were open: readiness stays "unchecked" until someone presses Re-check, and a new team
@@ -308,34 +505,77 @@ if (!connected) {
     // ⛔ A team whose readiness reads `blocked` is NOT set up, whatever its gate says: a blocking
     // check (a Linear automation that moves cards off Catalyst's stages, a missing OAuth scope) breaks
     // every run in it. The step is that check's own fix, by its own owner, then a re-check.
-    const isBlocking = (c) => readinessMeta().length === 0 || readinessMeta().find((r) => r.id === c.id)?.severity === "blocking";
+    const isBlocking = (c) =>
+      readinessMeta().length === 0 ||
+      readinessMeta().find((r) => r.id === c.id)?.severity === "blocking";
     for (const t of rows.filter((r) => r.readiness?.status === "blocked")) {
       const key = t.key ?? t.id ?? "(unkeyed)";
-      const fails = (Array.isArray(t.readiness?.checks) ? t.readiness.checks : []).filter((c) => c.state === "fail" && isBlocking(c));
+      const fails = (
+        Array.isArray(t.readiness?.checks) ? t.readiness.checks : []
+      ).filter((c) => c.state === "fail" && isBlocking(c));
       const ids = fails.map((c) => c.id);
-      const rules = ids.filter((id) => id in LINEAR_AUTOMATION_RULES).map((id) => LINEAR_AUTOMATION_RULES[id]);
+      const rules = ids
+        .filter((id) => id in LINEAR_AUTOMATION_RULES)
+        .map((id) => LINEAR_AUTOMATION_RULES[id]);
       const others = ids.filter((id) => !(id in LINEAR_AUTOMATION_RULES));
-      const ownerRow = fails.map((c) => readinessMeta().find((r) => r.id === c.id)).find((r) => r && typeof r.fixedByLine === "string");
-      const owner = ownerRow ? ownerRow.fixedByLine : "a workspace owner or admin";
+      const ownerRow = fails
+        .map((c) => readinessMeta().find((r) => r.id === c.id))
+        .find((r) => r && typeof r.fixedByLine === "string");
+      const owner = ownerRow
+        ? ownerRow.fixedByLine
+        : "a workspace owner or admin";
       const how = [
-        rules.length > 0 ? `in Linear, open Settings → Teams → ${key} → Workflow → Git automation and set ${rules.join(", ")} to No action (no Catalyst key can change a Linear automation rule)` : null,
+        rules.length > 0
+          ? `in Linear, open Settings → Teams → ${key} → Workflow → Workflows & automations → Pull request and commit automations and set ${rules.join(", ")} to No action (Catalyst does not yet offer to change these rules)`
+          : null,
         others.length > 0 ? `${others.join(", ")}: ${owner}` : null,
-      ].filter(Boolean).join("; ");
-      lines.push(`${key}: BLOCKED — ${ids.length > 0 ? ids.join(", ") : "a blocking check failed"}; ${how || `owner: ${owner}`}`);
-      blockedProjects.push({ key, action: `fix ${key}'s blocking check${ids.length === 1 ? "" : "s"} (${ids.join(", ") || "see the projects lines"}): ${how || owner}; then run catalyst team check ${key} (or press Re-check) and run this again`, owner });
+      ]
+        .filter(Boolean)
+        .join("; ");
+      lines.push(
+        `${key}: BLOCKED — ${ids.length > 0 ? ids.join(", ") : "a blocking check failed"}; ${how || `owner: ${owner}`}`,
+      );
+      blockedProjects.push({
+        key,
+        action: `fix ${key}'s blocking check${ids.length === 1 ? "" : "s"} (${ids.join(", ") || "see the projects lines"}): ${how || owner}; then run catalyst team check ${key} (or press Re-check) and run this again`,
+        owner,
+      });
     }
-    const setUp = (t) => t.readiness?.status !== "blocked" && (t.dispatchGate?.status === "open" || (t.readiness?.status ?? "unchecked") === "ready");
+    const setUp = (t) =>
+      t.readiness?.status !== "blocked" &&
+      (t.dispatchGate?.status === "open" ||
+        (t.readiness?.status ?? "unchecked") === "ready");
     for (const t of rows) {
-      if (t.dispatchGate?.status === "open" && (t.readiness?.status ?? "unchecked") === "unchecked") {
-        lines.push(`${t.key ?? t.id ?? "(unkeyed)"}: stages mapped; readiness not checked yet: run catalyst team check ${t.key ?? t.id} to see the rest`);
+      if (
+        t.dispatchGate?.status === "open" &&
+        (t.readiness?.status ?? "unchecked") === "unchecked"
+      ) {
+        lines.push(
+          `${t.key ?? t.id ?? "(unkeyed)"}: stages mapped; readiness not checked yet: run catalyst team check ${t.key ?? t.id} to see the rest`,
+        );
       }
     }
-    const ready = rows.length > 0 && rows.every(setUp);
-    const mapOwner = verbAvailable("team map") ? "you, with your own login" : "a workspace owner or admin";
-    const mapWhere = verbAvailable("team map") ? "catalyst team list" : link("/settings/linear-teams");
-    const projectOwner = blockedProjects.length > 0 ? blockedProjects[0].owner : mapOwner;
+    const mappedRows = rows.filter(
+      (team) => team.stages && Object.keys(team.stages).length > 0,
+    );
+    const ready = mappedRows.length > 0 && mappedRows.every(setUp);
+    const mapOwner = verbAvailable("team map")
+      ? "you, with your own login"
+      : "a workspace owner or admin";
+    const mapWhere = verbAvailable("team map")
+      ? "catalyst team list"
+      : link("/settings/linear-teams");
+    const projectOwner =
+      blockedProjects.length > 0 ? blockedProjects[0].owner : mapOwner;
     const projectWhere = blockedProjects.length > 0 ? null : mapWhere;
-    add("projects", "catalyst contract --path teams, and the team: checks of ready", ready ? "ok" : "unfinished", lines, projectOwner, projectWhere);
+    add(
+      "projects",
+      "catalyst contract --path teams, and the team: checks of ready",
+      ready ? "ok" : "unfinished",
+      lines,
+      projectOwner,
+      projectWhere,
+    );
   }
 }
 
@@ -345,27 +585,75 @@ if (!connected) {
 // reach it, so this note never claims that, and it never changes a verdict.
 function thoughtsNote(owner) {
   const repo = `${owner}/thoughts`;
-  const res = spawnSync("gh", ["repo", "view", repo, "--json", "name"], { encoding: "utf8", timeout: 15_000, env: { ...process.env, GH_PROMPT_DISABLED: "1" } });
-  if (res.error) return `note ${repo}: not checked (the gh command could not run here). Confirm it exists on GitHub (step 5a).`;
-  if (res.status === 0) return `note ${repo}: exists; App access not verifiable from here. Confirm the GitHub App installation includes it (step 5a).`;
-  const why = (res.stderr || res.stdout).trim().split("\n")[0] || `gh exited ${res.status}`;
+  const res = spawnSync("gh", ["repo", "view", repo, "--json", "name"], {
+    encoding: "utf8",
+    timeout: 15_000,
+    env: { ...process.env, GH_PROMPT_DISABLED: "1" },
+  });
+  if (res.error)
+    return `note ${repo}: not checked (the gh command could not run here). Confirm it exists on GitHub (step 5a).`;
+  if (res.status === 0)
+    return `note ${repo}: exists; App access not verifiable from here. Confirm the GitHub App installation includes it (step 5a).`;
+  const why =
+    (res.stderr || res.stdout).trim().split("\n")[0] ||
+    `gh exited ${res.status}`;
   return `note ${repo}: gh could not see it (${why}). It does not exist, or this GitHub login cannot see it. Create or confirm it (step 5a).`;
 }
 if (!connected) {
-  add("repositories", "catalyst contract --path merge.repositories", "unreadable", ["not readable until this machine is connected"], null, null);
+  add(
+    "repositories",
+    "catalyst contract --path merge.repositories",
+    "unreadable",
+    ["not readable until this machine is connected"],
+    null,
+    null,
+  );
 } else {
-  const repos = readContract(["contract", "--path", "merge.repositories", "--json"]);
+  const repos = readContract([
+    "contract",
+    "--path",
+    "merge.repositories",
+    "--json",
+  ]);
   const doc = tryJson(repos.stdout);
   const rows = Array.isArray(doc) ? doc : null;
   if (rows === null) {
-    add("repositories", "catalyst contract --path merge.repositories", "unreadable", ["the repository list could not be read — try: catalyst contract --refresh"], null, null).next =
+    add(
+      "repositories",
+      "catalyst contract --path merge.repositories",
+      "unreadable",
+      [
+        "the repository list could not be read — try: catalyst contract --refresh",
+      ],
+      null,
+      null,
+    ).next =
       "refresh the contract (catalyst contract --refresh), then run this again; the repository list could not be read, so no step after it can be named yet";
   } else {
-    const lines = [`${rows.length} registered`, ...rows.map((r) => `${r.owner ?? "?"}/${r.name ?? "?"}`)];
+    const lines = [
+      `${rows.length} registered`,
+      ...rows.map((r) => `${r.owner ?? "?"}/${r.name ?? "?"}`),
+    ];
     repositoryRegistered = rows.length > 0;
-    lines.push("⛔ REGISTRATION only. This carries no status and no project attachment, so it never proves a repository can be dispatched into.");
-    for (const owner of [...new Set(rows.map((r) => r.owner).filter((o) => typeof o === "string" && o !== ""))]) lines.push(thoughtsNote(owner));
-    add("repositories", "catalyst contract --path merge.repositories", rows.length > 0 ? "ok" : "unfinished", lines, "a workspace owner or admin", link("/settings/repositories"));
+    lines.push(
+      "⛔ REGISTRATION only. This carries no status and no project attachment, so it never proves a repository can be dispatched into.",
+    );
+    for (const owner of [
+      ...new Set(
+        rows
+          .map((r) => r.owner)
+          .filter((o) => typeof o === "string" && o !== ""),
+      ),
+    ])
+      lines.push(thoughtsNote(owner));
+    add(
+      "repositories",
+      "catalyst contract --path merge.repositories",
+      rows.length > 0 ? "ok" : "unfinished",
+      lines,
+      "a workspace owner or admin",
+      link("/settings/projects"),
+    );
   }
 }
 
@@ -388,19 +676,30 @@ const CREDENTIAL_ERROR_CODES = new Set(["no_access_token", "no_credential"]);
 const CREDENTIAL_FAILURE_STREAK = 3;
 // A cancelled subscription or an ended account is not a credential problem: no token brings it
 // back. It is kept for reporting, never re-credentialed, and it does not make setup unfinished.
-const isRetirable = (a) => a?.renewalStatus === "canceled" || a?.status === "ended" || a?.declaredState === "ended";
+const isRetirable = (a) =>
+  a?.renewalStatus === "canceled" ||
+  a?.status === "ended" ||
+  a?.declaredState === "ended";
 const credentialProblem = (a) => {
   if (isRetirable(a)) return null;
   if (typeof a?.needsCredential === "boolean") {
     if (!a.needsCredential) return null;
-    if (a.quarantined === true) return `quarantined${typeof a.quarantineReason === "string" && a.quarantineReason !== "" ? `: ${a.quarantineReason}` : ""}`;
+    if (a.quarantined === true)
+      return `quarantined${typeof a.quarantineReason === "string" && a.quarantineReason !== "" ? `: ${a.quarantineReason}` : ""}`;
     if (a.status === "expired-or-revoked") return "expired or revoked";
-    return typeof a.lastPollErrorCode === "string" ? `its last ${a.pollFailureCount} polls failed with ${a.lastPollErrorCode}` : "the cloud says it needs a new credential";
+    return typeof a.lastPollErrorCode === "string"
+      ? `its last ${a.pollFailureCount} polls failed with ${a.lastPollErrorCode}`
+      : "the cloud says it needs a new credential";
   }
   if (a?.status === "ended" || (a?.revokedAtMs ?? null) !== null) return null;
-  if (a?.quarantined === true) return `quarantined${typeof a.quarantineReason === "string" && a.quarantineReason !== "" ? `: ${a.quarantineReason}` : ""}`;
+  if (a?.quarantined === true)
+    return `quarantined${typeof a.quarantineReason === "string" && a.quarantineReason !== "" ? `: ${a.quarantineReason}` : ""}`;
   if (a?.status === "expired-or-revoked") return "expired or revoked";
-  if (CREDENTIAL_ERROR_CODES.has(a?.lastPollErrorCode) && typeof a?.pollFailureCount === "number" && a.pollFailureCount >= CREDENTIAL_FAILURE_STREAK) {
+  if (
+    CREDENTIAL_ERROR_CODES.has(a?.lastPollErrorCode) &&
+    typeof a?.pollFailureCount === "number" &&
+    a.pollFailureCount >= CREDENTIAL_FAILURE_STREAK
+  ) {
     return `its last ${a.pollFailureCount} polls failed with ${a.lastPollErrorCode}`;
   }
   return null;
@@ -408,11 +707,28 @@ const credentialProblem = (a) => {
 const readAccountRows = () => {
   const acc = runCli(["accounts", "--json"]);
   const doc = tryJson(acc.stdout);
-  const rows = Array.isArray(doc) ? doc : Array.isArray(doc?.accounts) ? doc.accounts : null;
-  return { rows, error: rows === null ? (acc.stderr || acc.stdout).trim().split("\n")[0] || "no output" : null };
+  const rows = Array.isArray(doc)
+    ? doc
+    : Array.isArray(doc?.accounts)
+      ? doc.accounts
+      : null;
+  return {
+    rows,
+    error:
+      rows === null
+        ? (acc.stderr || acc.stdout).trim().split("\n")[0] || "no output"
+        : null,
+  };
 };
 if (!connected) {
-  add("coding accounts", "codingAccounts in catalyst contract", "unreadable", ["not readable until this machine is connected"], null, null);
+  add(
+    "coding accounts",
+    "codingAccounts in catalyst contract",
+    "unreadable",
+    ["not readable until this machine is connected"],
+    null,
+    null,
+  );
 } else {
   const res = readContract(["contract", "--path", "codingAccounts", "--json"]);
   const ca = tryJson(res.stdout);
@@ -420,76 +736,203 @@ if (!connected) {
   const INSTRUMENT = "codingAccounts in catalyst contract";
   if (ca !== null && typeof ca === "object" && typeof ca.state === "string") {
     const line = typeof ca.line === "string" ? ca.line : `state ${ca.state}`;
-    const owner = typeof ca.enrolledByLine === "string" ? ca.enrolledByLine : null;
+    const owner =
+      typeof ca.enrolledByLine === "string" ? ca.enrolledByLine : null;
     const where = typeof ca.page === "string" ? link(ca.page) : null;
     if (ca.state === "enrolled" || ca.state === "needs_credential") {
       const DETAIL = `${INSTRUMENT}, and catalyst accounts`;
       const head = [line, `${ca.activeCount ?? "?"} active`];
       const { rows, error } = readAccountRows();
-      const dead = rows === null ? [] : rows.filter((a) => credentialProblem(a) !== null);
+      const dead =
+        rows === null ? [] : rows.filter((a) => credentialProblem(a) !== null);
       const retirable = rows === null ? [] : rows.filter(isRetirable);
-      const who = (a) => [a.label, a.email].find((v) => typeof v === "string" && v !== "");
-      const retireLine = retirable.length === 0 ? [] : [`${retirable.length} account(s) cancelled or ended (${retirable.map((a) => `${who(a) ?? a.displayName ?? a.accountSlot ?? "?"} (${a.provider ?? "unknown provider"})`).join(", ")}): kept for reporting, not used, and not counted here. Never replace their credential; reactivate one on the AI accounts page only if its subscription is live again.`];
+      const who = (a) =>
+        [a.label, a.email].find((v) => typeof v === "string" && v !== "");
+      const retireLine =
+        retirable.length === 0
+          ? []
+          : [
+              `${retirable.length} account(s) cancelled or ended (${retirable.map((a) => `${who(a) ?? a.displayName ?? a.accountSlot ?? "?"} (${a.provider ?? "unknown provider"})`).join(", ")}): kept for reporting, not used, and not counted here. Never replace their credential; reactivate one on the AI accounts page only if its subscription is live again.`,
+            ];
       retireNote = retireLine[0] ?? null;
       if (rows === null) {
-        accountsNext = "read the coding accounts again; each account's credential could not be checked";
-        add("coding accounts", DETAIL, "unreadable", [...head, `coding accounts could not be checked in detail (${error}). Whether each one still has a working credential is unknown. Do not enroll one on this reading.`], null, null);
+        accountsNext =
+          "read the coding accounts again; each account's credential could not be checked";
+        add(
+          "coding accounts",
+          DETAIL,
+          "unreadable",
+          [
+            ...head,
+            `coding accounts could not be checked in detail (${error}). Whether each one still has a working credential is unknown. Do not enroll one on this reading.`,
+          ],
+          null,
+          null,
+        );
       } else if (dead.length > 0) {
-        const name = (a) => `${a.provider ?? "unknown provider"} account ${a.accountSlot ?? "?"}${who(a) ? ` (${who(a)})` : ""}`;
+        const name = (a) =>
+          `${a.provider ?? "unknown provider"} account ${a.accountSlot ?? "?"}${who(a) ? ` (${who(a)})` : ""}`;
         const more = dead.length > 1 ? ` (and ${dead.length - 1} more)` : "";
         accountsNext = `${name(dead[0])} needs a new credential${more}. Replace it on the AI accounts page (Settings → AI accounts → the account → Replace credential). Do not enroll another account.`;
         add(
           "coding accounts",
           DETAIL,
           "unfinished",
-          [...head, ...dead.map((a) => `${name(a)} needs a new credential: ${credentialProblem(a)}`), "Replace its credential on its own page, with a credential minted from THAT account: check the login you mint from matches the account named here first. Do not enroll another account. The steps are in references/replacing-a-credential.md.", ...retireLine],
+          [
+            ...head,
+            ...dead.map(
+              (a) =>
+                `${name(a)} needs a new credential: ${credentialProblem(a)}`,
+            ),
+            "Replace its credential on its own page, with a credential minted from THAT account: check the login you mint from matches the account named here first. Do not enroll another account. The steps are in references/replacing-a-credential.md.",
+            ...retireLine,
+          ],
           owner,
           where,
         );
       } else if (ca.state === "needs_credential") {
-        accountsNext = "replace the credential of the coding account the page marks; do not enroll another account";
-        add("coding accounts", DETAIL, "unfinished", [...head, "The contract says an account needs a new credential, and the account list does not say which. Open the page and look for it."], owner, where);
+        accountsNext =
+          "replace the credential of the coding account the page marks; do not enroll another account";
+        add(
+          "coding accounts",
+          DETAIL,
+          "unfinished",
+          [
+            ...head,
+            "The contract says an account needs a new credential, and the account list does not say which. Open the page and look for it.",
+          ],
+          owner,
+          where,
+        );
       } else {
-        add("coding accounts", DETAIL, "ok", [...head, `${rows.length} checked, none needs a new credential`, ...retireLine]);
+        add("coding accounts", DETAIL, "ok", [
+          ...head,
+          `${rows.length} checked, none needs a new credential`,
+          ...retireLine,
+        ]);
       }
     } else if (ca.state === "inactive") {
-      accountsNext = "reactivate a coding account that is out of rotation; do not enroll another one";
-      add("coding accounts", INSTRUMENT, "unfinished", [line, "Every account is out of rotation. Reactivate one. Do not enroll another account."], owner, where);
+      accountsNext =
+        "reactivate a coding account that is out of rotation; do not enroll another one";
+      add(
+        "coding accounts",
+        INSTRUMENT,
+        "unfinished",
+        [
+          line,
+          "Every account is out of rotation. Reactivate one. Do not enroll another account.",
+        ],
+        owner,
+        where,
+      );
     } else if (ca.state === "none_enrolled") {
-      add("coding accounts", INSTRUMENT, "unfinished", [line, "no phase can start until one is enrolled"], owner, where);
+      add(
+        "coding accounts",
+        INSTRUMENT,
+        "unfinished",
+        [line, "no phase can start until one is enrolled"],
+        owner,
+        where,
+      );
     } else {
       // `unread`, or a state this bundle does not know: could not look is not the same as none there.
-      accountsNext = "read the coding accounts again; the cloud could not read them this time";
-      add("coding accounts", INSTRUMENT, "unreadable", [line, "This is not a missing account. Do not enroll one on this reading. Run this again later."], null, null);
+      accountsNext =
+        "read the coding accounts again; the cloud could not read them this time";
+      add(
+        "coding accounts",
+        INSTRUMENT,
+        "unreadable",
+        [
+          line,
+          "This is not a missing account. Do not enroll one on this reading. Run this again later.",
+        ],
+        null,
+        null,
+      );
     }
   } else if (older) {
     const { rows, error } = readAccountRows();
-    const olderLine = "this cloud is older than the bundle: its contract does not say whether a coding account is enrolled, so the account list is read instead";
+    const olderLine =
+      "this cloud is older than the bundle: its contract does not say whether a coding account is enrolled, so the account list is read instead";
     if (rows === null) {
-      accountsNext = "read the coding accounts again; the account list could not be read this time";
-      add("coding accounts", "catalyst accounts", "unreadable", [olderLine, `coding accounts could not be read (${error})`], null, null);
+      accountsNext =
+        "read the coding accounts again; the account list could not be read this time";
+      add(
+        "coding accounts",
+        "catalyst accounts",
+        "unreadable",
+        [olderLine, `coding accounts could not be read (${error})`],
+        null,
+        null,
+      );
     } else {
       // An expired or revoked slot, or a quarantined one, cannot take work until an admin acts on it.
-      const usable = rows.filter((a) => a?.status !== "expired-or-revoked" && a?.quarantined !== true);
-      const lines = [olderLine, `${rows.length} enrolled, ${usable.length} able to take work`];
-      for (const a of rows) lines.push(`${a.accountSlot ?? "?"}: ${a.provider ?? "?"}, ${a.status ?? "status unknown"}${a.quarantined ? ", quarantined" : ""}`);
-      if (usable.length === 0) lines.push("no phase can start until one is enrolled and able to take work");
-      add("coding accounts", "catalyst accounts", usable.length > 0 ? "ok" : "unfinished", lines, "a workspace owner or admin", link("/settings/coding-accounts"));
+      const usable = rows.filter(
+        (a) => a?.status !== "expired-or-revoked" && a?.quarantined !== true,
+      );
+      const lines = [
+        olderLine,
+        `${rows.length} enrolled, ${usable.length} able to take work`,
+      ];
+      for (const a of rows)
+        lines.push(
+          `${a.accountSlot ?? "?"}: ${a.provider ?? "?"}, ${a.status ?? "status unknown"}${a.quarantined ? ", quarantined" : ""}`,
+        );
+      if (usable.length === 0)
+        lines.push(
+          "no phase can start until one is enrolled and able to take work",
+        );
+      add(
+        "coding accounts",
+        "catalyst accounts",
+        usable.length > 0 ? "ok" : "unfinished",
+        lines,
+        "a workspace owner or admin",
+        link("/settings/coding-accounts"),
+      );
     }
   } else {
-    accountsNext = "read the coding accounts again; the contract could not be read";
-    add("coding accounts", INSTRUMENT, "unreadable", [`the contract could not be read (${(res.stderr || res.stdout).trim().split("\n").pop() || "no output"}); try: catalyst contract --refresh`], null, null);
+    accountsNext =
+      "read the coding accounts again; the contract could not be read";
+    add(
+      "coding accounts",
+      INSTRUMENT,
+      "unreadable",
+      [
+        `the contract could not be read (${(res.stderr || res.stdout).trim().split("\n").pop() || "no output"}); try: catalyst contract --refresh`,
+      ],
+      null,
+      null,
+    );
   }
 }
 
 // the Re-check step, as a command when this person can run it, else as the page with the
 // person who can. `team check` is the CLI twin of the page's Re-check button (admin or owner).
-const mappedKeys = () => (teamRows ?? []).map((t) => t.key ?? t.id).filter((k) => typeof k === "string" && k !== "");
+const mappedKeys = () =>
+  (teamRows ?? [])
+    .map((t) => t.key ?? t.id)
+    .filter((k) => typeof k === "string" && k !== "");
 const recheckStep = () => {
   const cmds = mappedKeys().map((k) => `catalyst team check ${k}`);
-  if (cmds.length > 0 && verbAvailable("team check")) return { action: `run ${cmds.join(" and ")}, then run this again`, owner: "you, the assistant: run it now with the person's login, without asking", where: cmds[0] };
-  if (cmds.length > 0 && verbAdminOnly("team check")) return { action: `a workspace owner or admin runs ${cmds.join(" and ")} (or presses Re-check on the projects page); then run this again`, owner: "a workspace owner or admin", where: link("/settings/linear-teams") };
-  return { action: "press Re-check on the projects page, then run this again", owner: "a workspace owner or admin", where: link("/settings/linear-teams") };
+  if (cmds.length > 0 && verbAvailable("team check"))
+    return {
+      action: `run ${cmds.join(" and ")}, then run this again`,
+      owner:
+        "you, the assistant: run it now with the person's login, without asking",
+      where: cmds[0],
+    };
+  if (cmds.length > 0 && verbAdminOnly("team check"))
+    return {
+      action: `a workspace owner or admin runs ${cmds.join(" and ")} (or presses Re-check on the projects page); then run this again`,
+      owner: "a workspace owner or admin",
+      where: link("/settings/linear-teams"),
+    };
+  return {
+    action: "press Re-check on the projects page, then run this again",
+    owner: "a workspace owner or admin",
+    where: link("/settings/linear-teams"),
+  };
 };
 
 // ── host ──────────────────────────────────────────────────────────────────────────────────────────
@@ -497,34 +940,83 @@ const recheckStep = () => {
 // contract says who owns it. The check is account-wide, so any one project's reading is the answer.
 // A tenant that runs no host of its own reads `pass` here, and then nothing is asked of anyone.
 if (!connected) {
-  add("host", "hosts_current in catalyst contract --path teams", "unreadable", ["not readable until this machine is connected"], null, null);
+  add(
+    "host",
+    "hosts_current in catalyst contract --path teams",
+    "unreadable",
+    ["not readable until this machine is connected"],
+    null,
+    null,
+  );
 } else {
-  const checks = (teamRows ?? []).flatMap((t) => (Array.isArray(t.readiness?.checks) ? t.readiness.checks : []).filter((c) => c.id === "hosts_current").map((c) => ({ ...c, team: t.key ?? t.id ?? "(unkeyed)" })));
+  const checks = (teamRows ?? []).flatMap((t) =>
+    (Array.isArray(t.readiness?.checks) ? t.readiness.checks : [])
+      .filter((c) => c.id === "hosts_current")
+      .map((c) => ({ ...c, team: t.key ?? t.id ?? "(unkeyed)" })),
+  );
   const row = readinessMeta().find((r) => r.id === "hosts_current") ?? null;
-  const hc = checks.find((c) => c.state === "fail") ?? checks.find((c) => c.state === "unknown") ?? checks[0] ?? null;
+  const hc =
+    checks.find((c) => c.state === "fail") ??
+    checks.find((c) => c.state === "unknown") ??
+    checks[0] ??
+    null;
   // The contract's printed line for this owner is written for a host that is behind. When no host is
   // connected there is nothing behind, so the owner is named by its id instead of by that sentence.
-  const owner = row?.fixedBy === undefined
-    ? "the contract names no owner for hosts_current"
-    : hc?.state === "fail" && typeof row.fixedByLine === "string"
-      ? row.fixedByLine
-      : `the host operator (the contract's owner for hosts_current: ${row.fixedBy})`;
+  const owner =
+    row?.fixedBy === undefined
+      ? "the contract names no owner for hosts_current"
+      : hc?.state === "fail" && typeof row.fixedByLine === "string"
+        ? row.fixedByLine
+        : `the host operator (the contract's owner for hosts_current: ${row.fixedBy})`;
   // Where the owner acts comes from the contract's `fixedWhere`. Null (every fixer today, and absent on
   // an older cloud) means no page exists, so the owner sentence is printed alone and no page is made up.
-  const fw = row?.fixedWhere && typeof row.fixedWhere.page === "string" ? row.fixedWhere : null;
+  const fw =
+    row?.fixedWhere && typeof row.fixedWhere.page === "string"
+      ? row.fixedWhere
+      : null;
   const how = fw === null ? null : link(fw.page);
   const howLines = fw?.command ? [`the owner runs: ${fw.command}`] : [];
   if (hc === null) {
     const step = recheckStep();
-    add("host", "hosts_current in catalyst contract --path teams", "unreadable", [teamRows === null ? "the project list could not be read, so the host check cannot be either" : "no project has a readiness check yet, so whether a host is connected cannot be read."], teamRows === null ? "a workspace owner or admin" : step.owner, teamRows === null ? link("/settings/linear-teams") : step.where).next =
+    add(
+      "host",
+      "hosts_current in catalyst contract --path teams",
+      "unreadable",
+      [
+        teamRows === null
+          ? "the project list could not be read, so the host check cannot be either"
+          : "no project has a readiness check yet, so whether a host is connected cannot be read.",
+      ],
+      teamRows === null ? "a workspace owner or admin" : step.owner,
+      teamRows === null ? link("/settings/linear-teams") : step.where,
+    ).next =
       teamRows === null
         ? "refresh the contract (catalyst contract --refresh), then run this again; the project list could not be read, so the host check cannot be either"
         : step.action;
   } else if (hc.state === "pass") {
-    add("host", "hosts_current in catalyst contract --path teams", "ok", [`hosts_current pass (read on ${hc.team})`]);
+    add("host", "hosts_current in catalyst contract --path teams", "ok", [
+      `hosts_current pass (read on ${hc.team})`,
+    ]);
   } else {
-    const detail = hc.reason === "no_host_connected" ? "no Catalyst host is connected" : hc.reason === "hosts_behind" ? "a connected host runs an older mapping" : hc.reason === "hosts_unreported" ? "a host is connected but has not reported what it loaded" : `state ${hc.state}`;
-    add("host", "hosts_current in catalyst contract --path teams", "unfinished", [`hosts_current ${hc.state}${hc.reason ? ` (${hc.reason})` : ""} on ${hc.team}: ${detail}`, ...howLines], owner, how);
+    const detail =
+      hc.reason === "no_host_connected"
+        ? "no Catalyst host is connected"
+        : hc.reason === "hosts_behind"
+          ? "a connected host runs an older mapping"
+          : hc.reason === "hosts_unreported"
+            ? "a host is connected but has not reported what it loaded"
+            : `state ${hc.state}`;
+    add(
+      "host",
+      "hosts_current in catalyst contract --path teams",
+      "unfinished",
+      [
+        `hosts_current ${hc.state}${hc.reason ? ` (${hc.reason})` : ""} on ${hc.team}: ${detail}`,
+        ...howLines,
+      ],
+      owner,
+      how,
+    );
   }
 }
 
@@ -533,37 +1025,107 @@ if (!connected) {
 // default repository has one in effect is the contract's `environment_declared` check; the project's
 // other repositories appear under that check's `repos`. Names only: nothing here reads a value, and
 // nothing here reads a file on this machine. A cloud that sends no such check has nothing to read.
-const DECL_INSTRUMENT = "environment_declared in catalyst contract --path teams";
+const DECL_INSTRUMENT =
+  "environment_declared in catalyst contract --path teams";
 const DECL_REASONS = {
-  no_team_repo_default: { text: "no repository is the project's default yet: register one and make it the default", who: "a workspace owner or admin", page: "/settings/repositories" },
-  no_environment_declaration: { text: "no .catalyst/catalyst.toml on its default branch yet: write it with the person (names only, never a value), open a pull request, merge it", who: "the person, in the repository, with your help", page: null },
-  declaration_invalid: { text: "the committed .catalyst/catalyst.toml did not validate: fix the file (the ingest names the error) and merge the fix", who: "the person, in the repository, with your help", page: null },
-  declaration_read_failed: { text: "the committed .catalyst/catalyst.toml could not be read: fix the file (the ingest names the error) and merge the fix", who: "the person, in the repository, with your help", page: null },
-  declaration_awaiting_approval: { text: "the declaration is proposed and waits for approval: Settings → Repositories → the repository → Environment → Setup declaration → Approve this revision", who: "a workspace owner or admin", page: "/settings/repositories" },
+  no_team_repo_default: {
+    text: "no repository is the project's default yet: register one and make it the default",
+    who: "a workspace owner or admin",
+    page: "/settings/projects",
+  },
+  no_environment_declaration: {
+    text: "no .catalyst/catalyst.toml on its default branch yet: write it with the person (names only, never a value), open a pull request, merge it",
+    who: "the person, in the repository, with your help",
+    page: null,
+  },
+  declaration_invalid: {
+    text: "the committed .catalyst/catalyst.toml did not validate: fix the file (the ingest names the error) and merge the fix",
+    who: "the person, in the repository, with your help",
+    page: null,
+  },
+  declaration_read_failed: {
+    text: "the committed .catalyst/catalyst.toml could not be read: fix the file (the ingest names the error) and merge the fix",
+    who: "the person, in the repository, with your help",
+    page: null,
+  },
+  declaration_awaiting_approval: {
+    text: "the declaration is proposed and waits for approval: Settings → Your projects → the project → Repositories → the repository → Environment → Setup declaration → Approve this revision",
+    who: "a workspace owner or admin",
+    page: "/settings/projects",
+  },
 };
-const DECL_DO = "write .catalyst/catalyst.toml with references/declaring-a-repository.md, then open a pull request";
-let declNext = "commit .catalyst/catalyst.toml to the repository and have an owner or admin approve it";
+const DECL_DO =
+  "write .catalyst/catalyst.toml with references/declaring-a-repository.md, then open a pull request";
+let declNext =
+  "commit .catalyst/catalyst.toml to the repository and have an owner or admin approve it";
 if (!connected) {
-  add("repository declarations", DECL_INSTRUMENT, "unreadable", ["not readable until this machine is connected"], null, null);
+  add(
+    "repository declarations",
+    DECL_INSTRUMENT,
+    "unreadable",
+    ["not readable until this machine is connected"],
+    null,
+    null,
+  );
 } else if (teamRows === null) {
-  add("repository declarations", DECL_INSTRUMENT, "unreadable", ["the project list could not be read, so no repository declaration can be either"], null, null).next =
+  add(
+    "repository declarations",
+    DECL_INSTRUMENT,
+    "unreadable",
+    [
+      "the project list could not be read, so no repository declaration can be either",
+    ],
+    null,
+    null,
+  ).next =
     "refresh the contract (catalyst contract --refresh), then run this again; the project list could not be read, so no repository declaration can be either";
 } else if (teamRows.length === 0) {
-  add("repository declarations", DECL_INSTRUMENT, "unreadable", ["no project is mapped yet, so there is no repository whose declaration could be read"], null, null).next =
-    "map a project first; a repository declaration is read per project";
-} else if (teamRows.every((t) => !Array.isArray(t.readiness?.checks) || t.readiness.checks.length === 0)) {
+  add(
+    "repository declarations",
+    DECL_INSTRUMENT,
+    "unreadable",
+    [
+      "no project is mapped yet, so there is no repository whose declaration could be read",
+    ],
+    null,
+    null,
+  ).next = "map a project first; a repository declaration is read per project";
+} else if (
+  teamRows.every(
+    (t) =>
+      !Array.isArray(t.readiness?.checks) || t.readiness.checks.length === 0,
+  )
+) {
   // Mapped, never checked: the contract carries no checks at all until someone presses Re-check, and
   // that silence is not "nothing to declare".
   const step = recheckStep();
-  add("repository declarations", DECL_INSTRUMENT, "unreadable", ["no project has a readiness check yet, so whether its repository is declared cannot be read."], step.owner, step.where).next = step.action;
+  add(
+    "repository declarations",
+    DECL_INSTRUMENT,
+    "unreadable",
+    [
+      "no project has a readiness check yet, so whether its repository is declared cannot be read.",
+    ],
+    step.owner,
+    step.where,
+  ).next = step.action;
 } else {
-  const found = teamRows.flatMap((t) => (Array.isArray(t.readiness?.checks) ? t.readiness.checks : []).filter((c) => c.id === "environment_declared").map((c) => ({ ...c, team: t.key ?? t.id ?? "(unkeyed)" })));
+  const found = teamRows.flatMap((t) =>
+    (Array.isArray(t.readiness?.checks) ? t.readiness.checks : [])
+      .filter((c) => c.id === "environment_declared")
+      .map((c) => ({ ...c, team: t.key ?? t.id ?? "(unkeyed)" })),
+  );
   const lines = [];
   let verdict = "ok";
   let owner = null;
   let where = null;
   let unknown = false;
-  const describe = (reason) => DECL_REASONS[reason] ?? { text: `environment_declared ${reason ?? "failed"} (a reason this bundle does not know; read it on the page)`, who: "a workspace owner or admin", page: "/settings/repositories" };
+  const describe = (reason) =>
+    DECL_REASONS[reason] ?? {
+      text: `environment_declared ${reason ?? "failed"} (a reason this bundle does not know; read it on the page)`,
+      who: "a workspace owner or admin",
+      page: "/settings/projects",
+    };
   const flag = (team, repo, reason) => {
     const r = describe(reason);
     lines.push(`${team}${repo ? `, ${repo}` : ""}: ${r.text}`);
@@ -573,23 +1135,136 @@ if (!connected) {
     where ??= r.page === null ? DECL_DO : link(r.page);
   };
   if (found.length === 0) {
-    lines.push("this cloud reports no repository declaration check for the mapped projects, so there is nothing to read here; the repository's Environment page is where one would show");
+    lines.push(
+      "this cloud reports no repository declaration check for the mapped projects, so there is nothing to read here; the repository's Environment page is where one would show",
+    );
   }
   for (const c of found) {
-    if (c.state === "pass") lines.push(`${c.team}: a declaration is in effect for the project's default repository`);
+    if (c.state === "pass")
+      lines.push(
+        `${c.team}: a declaration is in effect for the project's default repository`,
+      );
     else if (c.state === "fail") flag(c.team, null, c.reason);
     else {
       unknown = true;
-      lines.push(`${c.team}: environment_declared could not be read${c.reason ? ` (${c.reason})` : ""}; a re-check is needed`);
+      lines.push(
+        `${c.team}: environment_declared could not be read${c.reason ? ` (${c.reason})` : ""}; a re-check is needed`,
+      );
     }
-    for (const note of Array.isArray(c.repos) ? c.repos : []) if (typeof note?.repo === "string" && note.reason) flag(c.team, note.repo, note.reason);
+    for (const note of Array.isArray(c.repos) ? c.repos : [])
+      if (typeof note?.repo === "string" && note.reason)
+        flag(c.team, note.repo, note.reason);
   }
   if (unknown && verdict === "ok") {
     const step = recheckStep();
-    add("repository declarations", DECL_INSTRUMENT, "unreadable", lines, step.owner, step.where).next = step.action;
+    add(
+      "repository declarations",
+      DECL_INSTRUMENT,
+      "unreadable",
+      lines,
+      step.owner,
+      step.where,
+    ).next = step.action;
   } else {
-    if (verdict !== "ok") lines.push("Names only: a value never passes through this script or the file. The person enters values on the repository's Environment page.");
-    add("repository declarations", DECL_INSTRUMENT, verdict, lines, verdict === "ok" ? null : owner, verdict === "ok" ? null : where);
+    if (verdict !== "ok")
+      lines.push(
+        "Names only: a value never passes through this script or the file. The person enters values on the repository's Environment page.",
+      );
+    add(
+      "repository declarations",
+      DECL_INSTRUMENT,
+      verdict,
+      lines,
+      verdict === "ok" ? null : owner,
+      verdict === "ok" ? null : where,
+    );
+  }
+}
+
+// ── repository agent setup (only with --repo) ─────────────────────────────────────────────────────
+// A checkout the person named. Read through the CLI's own verb, never by this script opening files:
+// the verb is the one place that knows the block's words and the portable layout. Never blocking:
+// a repository that is not portable still runs; this is an offer, and the writes wait for a yes.
+let repoNote = null;
+let repoNext = null;
+if (typeof flags.repo === "string" && flags.repo !== "") {
+  const REPO_INSTRUMENT = `repo agent-setup ${flags.repo} --json`;
+  if (!connected) {
+    add(
+      "repository agent setup",
+      REPO_INSTRUMENT,
+      "unreadable",
+      ["not readable until this machine is connected"],
+      null,
+      null,
+      false,
+    );
+  } else if (!verbAvailable("repo agent-setup")) {
+    add(
+      "repository agent setup",
+      REPO_INSTRUMENT,
+      "unreadable",
+      [
+        "this CLI has no repo agent-setup verb; update the CLI to read a checkout's agent setup",
+      ],
+      null,
+      null,
+      false,
+    ).next =
+      "update the CLI (it lacks repo agent-setup); the checkout's agent setup cannot be read until then (does not block anything)";
+  } else {
+    const res = runCli(["repo", "agent-setup", flags.repo, "--json"]);
+    const doc = tryJson(res.stdout);
+    if (doc === null) {
+      add(
+        "repository agent setup",
+        REPO_INSTRUMENT,
+        "unreadable",
+        [
+          `the checkout could not be read (${(res.stderr || res.stdout).trim().split("\n")[0] || "no output"})`,
+        ],
+        null,
+        null,
+        false,
+      ).next =
+        `run this again with the checkout's real path; ${flags.repo} could not be read`;
+    } else {
+      const block = doc.agentsMd?.block ?? "unknown";
+      const verdict = doc.verdict ?? "unknown";
+      const ok = verdict === "portable" && block === "current";
+      const lines = [
+        `AGENTS.md: ${doc.agentsMd?.present ? `present; Catalyst block ${block}` : "absent"}`,
+        `CLAUDE.md: ${doc.claudeMd?.present ? (doc.claudeMd.importsAgentsMd ? "imports AGENTS.md" : `${doc.claudeMd.otherLines ?? "?"} lines of its own guidance, no @AGENTS.md import`) : "absent"}`,
+        `layout: ${verdict}${Array.isArray(doc.plan) && doc.plan.length ? ` — ${doc.plan.join("; ")}` : ""}${Array.isArray(doc.blockers) && doc.blockers.length ? ` — by hand: ${doc.blockers.join("; ")}` : ""}`,
+      ];
+      const offers = [];
+      if (block !== "current")
+        offers.push(
+          `the Catalyst block for AGENTS.md (catalyst repo agents-block ${flags.repo} --write)`,
+        );
+      if (verdict === "convertible")
+        offers.push(
+          `the portable layout (catalyst repo agent-setup ${flags.repo} --apply)`,
+        );
+      if (verdict === "needs_hand_merge")
+        offers.push("a hand merge first (the layout line names what)");
+      repoNext = ok
+        ? null
+        : `say in one clause what the checkout holds, then offer ${offers.join(" and ")}, each after a yes, on a branch for the pull request the person opens`;
+      add(
+        "repository agent setup",
+        REPO_INSTRUMENT,
+        ok ? "ok" : "unfinished",
+        lines,
+        ok
+          ? null
+          : "you, after the person's yes, in their checkout; the pull request is theirs",
+        ok ? null : `catalyst repo agent-setup ${flags.repo}`,
+        false,
+      );
+      if (!ok)
+        repoNote = `repository ${flags.repo}: Catalyst block ${block}, layout ${verdict} — offer ${offers.join(" and ")} after a yes (references/repository-agent-setup.md)`;
+    }
   }
 }
 
@@ -609,17 +1284,21 @@ const NEXT = {
       : personalGithubIncomplete
         ? "install the tenant GitHub App and register its repository before connecting your personal GitHub account"
         : "get this person's seat and Linear identity sorted",
-  account: "connect the Linear integration on the Connections page (the GitHub App comes later, with the repository)",
-  projects: blockedProjects.length > 0
-    ? blockedProjects.map((b) => b.action).join("; and ")
-    : verbAvailable("team map")
-    ? "pick ONE project: run catalyst team list, then catalyst team map <KEY> (or team adopt <KEY>) and approve its preview"
-    : verbAdminOnly("team map")
-      ? "a workspace owner or admin maps ONE project: catalyst team map <KEY>, or Map my stages on the projects page"
-      : "pick ONE project and map its stages (or adopt the Catalyst workflow)",
-  repositories: "install the GitHub App on the Connections page, granting it the repository you want worked; registering that repository on the Repositories page, attached to the project, is the step right after",
+  account:
+    "connect the Linear integration on the Integrations page (the GitHub App comes later, with the repository)",
+  projects:
+    blockedProjects.length > 0
+      ? blockedProjects.map((b) => b.action).join("; and ")
+      : verbAvailable("team map")
+        ? "pick ONE project: run catalyst team list, then catalyst team map <KEY> (or team adopt <KEY>) and approve its preview"
+        : verbAdminOnly("team map")
+          ? "a workspace owner or admin maps ONE project: catalyst team map <KEY>, or Map my stages on the projects page"
+          : "pick ONE project and map its stages (or adopt the Catalyst workflow)",
+  repositories:
+    "install the GitHub App on the Integrations page, granting it the repository you want worked; register it on Your projects and attach it to the project before continuing",
   "coding accounts": accountsNext,
   "repository declarations": declNext,
+  "repository agent setup": repoNext ?? "read the checkout's agent setup again",
   host: "connect a Catalyst host",
 };
 // The parts are read in the order their data allows and reported in the order a person can act on
@@ -627,7 +1306,17 @@ const NEXT = {
 // workspace's Linear integration, the project, the GitHub App with its repository, the person's own
 // connected accounts (personal GitHub after the repository proves the App), the repository's
 // declaration, and last the host. `--next` is the first unfinished part in this order.
-const ORDER = ["machine", "coding accounts", "account", "projects", "repositories", "person", "repository declarations", "host"];
+const ORDER = [
+  "machine",
+  "coding accounts",
+  "account",
+  "projects",
+  "repositories",
+  "person",
+  "repository declarations",
+  "repository agent setup",
+  "host",
+];
 parts.sort((a, b) => ORDER.indexOf(a.part) - ORDER.indexOf(b.part));
 // A personal Linear grant cannot start until the tenant's Linear workspace exists. Once that account
 // connection is present, a missing personal grant becomes the next member step before project setup.
@@ -636,7 +1325,9 @@ const personPart = parts.find((p) => p.part === "person");
 // GitHub grant is sequenced after the tenant GitHub App: successful repository registration is the
 // onboarding path's existing proof that the App installation is usable.
 if (personPart && personalGrantIncomplete && workspaceResolved) {
-  personPart.blocking = personalLinearIncomplete || (personalGithubIncomplete && repositoryRegistered);
+  personPart.blocking =
+    personalLinearIncomplete ||
+    (personalGithubIncomplete && repositoryRegistered);
 }
 const blocked = parts.filter((p) => p.verdict !== "ok" && p.blocking);
 const stuck = blocked[0] ?? parts.find((p) => p.verdict !== "ok") ?? null;
@@ -646,45 +1337,92 @@ const stuck = blocked[0] ?? parts.find((p) => p.verdict !== "ok") ?? null;
 // their own unreadable step in `accountsNext`.
 const actionFor = (p) =>
   p.verdict === "unreadable" && p.part !== "coding accounts"
-    ? (p.next ?? `run this again; the ${p.part} part could not be read, so no step after it can be named yet`)
+    ? (p.next ??
+      `run this again; the ${p.part} part could not be read, so no step after it can be named yet`)
     : NEXT[p.part];
 let next =
   stuck === null
     ? null
-    : { part: stuck.part, action: actionFor(stuck), owner: stuck.owner, where: stuck.where, blocking: stuck.blocking };
+    : {
+        part: stuck.part,
+        action: actionFor(stuck),
+        owner: stuck.owner,
+        where: stuck.where,
+        blocking: stuck.blocking,
+      };
 
 // A refused contract version outranks every step above: each of them was read from, or waits on, a
 // contract this CLI would not accept. Whether an update exists is asked of npm, once, and only here.
 function versionAdvice() {
   const semver = (t) => (t ?? "").match(/\b(\d+)\.(\d+)\.(\d+)\b/);
   const installed = semver(field("Bundle"));
-  const npm = spawnSync("npm", ["view", "@catalyst-cloud/cli", "version"], { encoding: "utf8", timeout: 10_000, shell: process.platform === "win32" });
+  const npm = spawnSync("npm", ["view", "@catalyst-cloud/cli", "version"], {
+    encoding: "utf8",
+    timeout: 10_000,
+    shell: process.platform === "win32",
+  });
   const latest = npm.error || npm.status !== 0 ? null : semver(npm.stdout);
   // The installer is the update path, not `catalyst install`. Its command is on the app's
   // setup page; this names the script it fetches rather than composing the request here.
   const reinstall = `re-run the install command from the app's setup page (it installs from ${link("/install.sh")})`;
   if (installed === null || latest === null) {
-    return { text: `Whether a newer Catalyst CLI is published could not be checked. You can ${reinstall}; if this still appears afterwards, tell the Catalyst team.`, owner: null };
+    return {
+      text: `Whether a newer Catalyst CLI is published could not be checked. You can ${reinstall}; if this still appears afterwards, tell the Catalyst team.`,
+      owner: null,
+    };
   }
-  const order = [1, 2, 3].map((i) => Math.sign(Number(installed[i]) - Number(latest[i]))).find((d) => d !== 0) ?? 0;
+  const order =
+    [1, 2, 3]
+      .map((i) => Math.sign(Number(installed[i]) - Number(latest[i])))
+      .find((d) => d !== 0) ?? 0;
   return order >= 0
-    ? { text: "A newer Catalyst CLI isn't published yet. Tell the Catalyst team; nothing on this machine needs to change.", owner: "the Catalyst team" }
+    ? {
+        text: "A newer Catalyst CLI isn't published yet. Tell the Catalyst team; nothing on this machine needs to change.",
+        owner: "the Catalyst team",
+      }
     : { text: `Update the CLI: ${reinstall}.`, owner: "you, on this machine" };
 }
 if (contractMismatch !== null && stuck !== null) {
   const advice = versionAdvice();
   const line = `the tenant serves contract ${contractMismatch.served} and this CLI accepts ${contractMismatch.accepts}. ${advice.text}`;
   stuck.lines.push(line);
-  next = { part: stuck.part, action: line, owner: advice.owner, where: null, blocking: true };
+  next = {
+    part: stuck.part,
+    action: line,
+    owner: advice.owner,
+    where: null,
+    blocking: true,
+  };
 }
 const finished = parts.every((p) => p.verdict === "ok");
 
 if (flags.json) {
-  console.log(JSON.stringify({ cli: via, connected, cloud, personalConnections, parts, localSync, next, finished, notes: retireNote === null ? [] : [retireNote] }));
+  console.log(
+    JSON.stringify({
+      cli: via,
+      connected,
+      cloud,
+      personalConnections,
+      parts,
+      localSync,
+      next,
+      finished,
+      notes: [retireNote, repoNote, legacyNote].filter((n) => n !== null),
+    }),
+  );
 } else if (flags.next) {
-  process.on("exit", () => { if (retireNote !== null) console.log(`note: ${retireNote}`); });
-  if (next === null) console.log("nothing left: every part is finished, a coding account is enrolled and the host check passes. Move one card into the project's start stage (usually Todo).");
-  else console.log(`${next.part}: ${next.action}${next.blocking ? "" : " (does not block the steps below)"}${next.owner ? ` — who: ${next.owner}` : ""}${next.where ? ` — ${next.where.startsWith("http") ? "where" : "do"}: ${next.where}` : ""}`);
+  process.on("exit", () => {
+    for (const n of [retireNote, repoNote, legacyNote])
+      if (n !== null) console.log(`note: ${n}`);
+  });
+  if (next === null)
+    console.log(
+      "nothing left: every part is finished, a coding account is enrolled and the host check passes. Move one card into the project's start stage (usually Todo).",
+    );
+  else
+    console.log(
+      `${next.part}: ${next.action}${next.blocking ? "" : " (does not block the steps below)"}${next.owner ? ` — who: ${next.owner}` : ""}${next.where ? ` — ${next.where.startsWith("http") ? "where" : "do"}: ${next.where}` : ""}`,
+    );
 } else {
   for (const p of parts) {
     console.log(`${p.part}  [${p.verdict}]`);
@@ -693,9 +1431,16 @@ if (flags.json) {
     if (p.verdict !== "ok" && p.owner) console.log(`  who: ${p.owner}`);
     // A page gets "where"; a command gets "do". Labelling a command "where" is how a person ends up
     // looking for a settings page that is actually a line to run.
-    if (p.verdict !== "ok" && p.where) console.log(`  ${p.where.startsWith("http") ? "where" : "do"}: ${p.where}`);
+    if (p.verdict !== "ok" && p.where)
+      console.log(
+        `  ${p.where.startsWith("http") ? "where" : "do"}: ${p.where}`,
+      );
     console.log("");
   }
-  console.log(next === null ? "next: nothing left — move one card into the project's start stage (usually Todo) and watch." : `next: ${next.part} — ${next.action}${next.owner ? ` (${next.owner})` : ""}${next.where ? ` — ${next.where}` : ""}`);
+  console.log(
+    next === null
+      ? "next: nothing left — move one card into the project's start stage (usually Todo) and watch."
+      : `next: ${next.part} — ${next.action}${next.owner ? ` (${next.owner})` : ""}${next.where ? ` — ${next.where}` : ""}`,
+  );
 }
 process.exit(finished ? 0 : 1);