@catalyst-cloud/cli 0.9.2 → 0.9.4

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

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
-// where-am-i.mjs — how far has setup got? SEVEN PARTS, EACH READ BY THE INSTRUMENT THAT OWNS IT, and
+// where-am-i.mjs — how far has setup got? EIGHT PARTS, EACH READ BY THE INSTRUMENT THAT OWNS IT, and
+// reported in the order a person can act on them (coding account first, then the integrations, the
+// project, its repository, the person's own connected accounts, the repository's declaration, the host);
 // each finding labelled with the part it belongs to. The whole point of this script is that no part
 // answers for another: a project that is not ready is reported as a project finding with a tenant
 // owner's name on it, never as something the person at this keyboard can fix by running anything.
@@ -18,8 +20,9 @@ const NOTES = [
   "`replica status --probe --json` and `events status --probe --json` (optional local freshness),",
   "`me --json` and personal connection statuses (person), `contract --path …` for the account, the projects and the repositories,",
   "`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).",
+  "project's hosts_current check with its fixedWhere (host), and each project's environment_declared check with its per-repository notes (repository declarations).",
   "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.",
 ];
 
@@ -45,8 +48,28 @@ let repositoryRegistered = false;
 // `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) =>
-  parts.push({ part, instrument, verdict, lines, owner, where, blocking });
+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;
+};
+
+// A tenant contract outside this CLI's range makes every contract read fail the same way. When that
+// happens, no part read from the contract can back a next step, and the only honest next step is the
+// version itself. The CLI's own hint says to update, which is wrong when no newer CLI is published.
+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+)/);
+  if (m !== null) contractMismatch ??= { served: m[1], accepts: m[2] };
+  return m !== null;
+};
+const readContract = (args) => {
+  const r = runCli(args);
+  noteMismatch(r.stderr);
+  return r;
+};
 
 // ── machine ───────────────────────────────────────────────────────────────────────────────────────
 const status = runCli(["status"]);
@@ -87,10 +110,13 @@ if (connected) {
     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);
-    for (const c of machineChecks) machineLines.push(`${c.note ? "note" : c.ok ? "ok  " : "FAIL"} ${c.line}${!c.ok && !c.note && c.fix ? ` — fix: ${c.fix}` : ""}`);
+    // 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}` : ""}`);
     if (failed.length > 0) {
       machineVerdict = "unfinished";
-      machineFix = failed.find((c) => typeof c.fix === "string")?.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.
@@ -111,7 +137,8 @@ add(
   machineVerdict,
   machineLines,
   "you, on this machine",
-  connected ? null : CONNECT_LINE,
+  // The keyless login alone: a person who holds a personal key already knows the key form.
+  connected ? null : CONNECT_LINE.split(" (or")[0],
 );
 
 // ── person ────────────────────────────────────────────────────────────────────────────────────────
@@ -122,7 +149,8 @@ if (!connected) {
   const doc = tryJson(me.stdout);
   const user = doc && typeof doc.user === "object" && doc.user !== null ? doc.user : null;
   if (doc === null) {
-    add("person", "catalyst-skills me", "unreadable", [`me could not be read (${(me.stderr || me.stdout).trim().split("\n")[0] ?? "no output"})`], null, null);
+    add("person", "catalyst-skills me", "unreadable", [`me could not be read (${(me.stderr || me.stdout).trim().split("\n")[0] ?? "no output"})`], null, null).next =
+      "run this again; catalyst-skills me could not be read, so no step after it can be named yet";
   } else if (user === null) {
     add(
       "person",
@@ -161,7 +189,7 @@ if (!connected) {
       "catalyst-skills me, and catalyst-skills 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-skills identity linear options for self-service recovery; personal Linear consent normally binds its viewer automatically.", ...grantLines],
-      personalGrantIncomplete ? "you" : matched ? null : "a tenant owner or admin",
+      personalGrantIncomplete ? "you" : matched ? null : "a workspace owner or admin",
       personalGrantIncomplete ? "catalyst-skills connections personal <provider> start or status" : matched ? null : link("/settings/account"),
       false,
     );
@@ -172,10 +200,11 @@ if (!connected) {
 if (!connected) {
   add("account", "catalyst-skills contract --path account", "unreadable", ["not readable until this machine is connected"], null, null);
 } else {
-  const acct = runCli(["contract", "--path", "account", "--json"]);
+  const acct = readContract(["contract", "--path", "account", "--json"]);
   const doc = tryJson(acct.stdout);
   if (doc === null) {
-    add("account", "catalyst-skills contract --path account", "unreadable", ["the account block could not be read — try: catalyst-skills contract --refresh"], null, null);
+    add("account", "catalyst-skills contract --path account", "unreadable", ["the account block could not be read — try: catalyst-skills contract --refresh"], null, null).next =
+      "refresh the contract (catalyst-skills 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;
     workspaceResolved = workspace !== null;
@@ -204,7 +233,7 @@ if (!connected) {
         "the GitHub App install is NOT carried here — the connections page is the only place that shows it",
         ...envLines,
       ],
-      "a tenant owner or admin",
+      "a workspace owner or admin",
       link("/settings/connections"),
     );
   }
@@ -216,12 +245,13 @@ let teamRows = null;
 if (!connected) {
   add("projects", "catalyst-skills contract --path teams", "unreadable", ["not readable until this machine is connected"], null, null);
 } else {
-  const teams = runCli(["contract", "--path", "teams", "--json"]);
+  const teams = readContract(["contract", "--path", "teams", "--json"]);
   const doc = tryJson(teams.stdout);
   const rows = Array.isArray(doc) ? doc : null;
   teamRows = rows;
   if (rows === null) {
-    add("projects", "catalyst-skills contract --path teams", "unreadable", ["the project list could not be read — try: catalyst-skills contract --refresh"], null, null);
+    add("projects", "catalyst-skills contract --path teams", "unreadable", ["the project list could not be read — try: catalyst-skills contract --refresh"], null, null).next =
+      "refresh the contract (catalyst-skills 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) {
@@ -243,7 +273,7 @@ if (!connected) {
       }
     }
     const ready = rows.length > 0 && rows.every(setUp);
-    add("projects", "catalyst-skills contract --path teams, and the team: checks of ready", ready ? "ok" : "unfinished", lines, "a tenant owner or admin", link("/settings/linear-teams"));
+    add("projects", "catalyst-skills contract --path teams, and the team: checks of ready", ready ? "ok" : "unfinished", lines, "a workspace owner or admin", link("/settings/linear-teams"));
   }
 }
 
@@ -262,17 +292,18 @@ function thoughtsNote(owner) {
 if (!connected) {
   add("repositories", "catalyst-skills contract --path merge.repositories", "unreadable", ["not readable until this machine is connected"], null, null);
 } else {
-  const repos = runCli(["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-skills contract --path merge.repositories", "unreadable", ["the repository list could not be read — try: catalyst-skills contract --refresh"], null, null);
+    add("repositories", "catalyst-skills contract --path merge.repositories", "unreadable", ["the repository list could not be read — try: catalyst-skills contract --refresh"], null, null).next =
+      "refresh the contract (catalyst-skills 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 ?? "?"}`)];
     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-skills contract --path merge.repositories", rows.length > 0 ? "ok" : "unfinished", lines, "a tenant owner or admin", link("/settings/repositories"));
+    add("repositories", "catalyst-skills contract --path merge.repositories", rows.length > 0 ? "ok" : "unfinished", lines, "a workspace owner or admin", link("/settings/repositories"));
   }
 }
 
@@ -282,13 +313,29 @@ if (!connected) {
 // The contract says the state, its sentence, who enrolls one and on which page. An older cloud's
 // contract has no `codingAccounts`, and only then is the owner assumed.
 let accountsNext = "enrol a coding account a phase can run on";
+// A note --next prints beside the next step: an ended or cancelled account is not unfinished, but the
+// person must hear that it is kept for reporting and never re-tokened, before anyone reaches for a setup token.
+let retireNote = null;
 // The contract counts accounts by declared rotation, so one healthy account can hide another whose
 // credential is dead. When it says `enrolled`, each account is read as well. An account needs a new
 // credential when it is quarantined, expired or revoked, or when its last polls failed on the
-// credential itself. The poll fields are read only when the cloud sends them.
-const CREDENTIAL_ERROR_CODES = new Set(["no_access_token", "no_credential", "http_401", "http_403", "usage_unauthorized", "usage_forbidden"]);
+// credential itself. The cloud's own verdict, `needsCredential`, wins when it is sent:
+// it leaves out ended and revoked accounts and usage-endpoint refusals, which are not verdicts on the
+// credential. Older clouds send only the poll fields, read with the same narrowed code list.
+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 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.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";
+  }
+  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?.status === "expired-or-revoked") return "expired or revoked";
   if (CREDENTIAL_ERROR_CODES.has(a?.lastPollErrorCode) && typeof a?.pollFailureCount === "number" && a.pollFailureCount >= CREDENTIAL_FAILURE_STREAK) {
@@ -305,7 +352,7 @@ const readAccountRows = () => {
 if (!connected) {
   add("coding accounts", "codingAccounts in catalyst-skills contract", "unreadable", ["not readable until this machine is connected"], null, null);
 } else {
-  const res = runCli(["contract", "--path", "codingAccounts", "--json"]);
+  const res = readContract(["contract", "--path", "codingAccounts", "--json"]);
   const ca = tryJson(res.stdout);
   const older = ca === null && /has nothing at/.test(res.stderr ?? "");
   const INSTRUMENT = "codingAccounts in catalyst-skills contract";
@@ -318,18 +365,22 @@ if (!connected) {
       const head = [line, `${ca.activeCount ?? "?"} active`];
       const { rows, error } = readAccountRows();
       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.`];
+      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);
       } else if (dead.length > 0) {
-        const name = (a) => `${a.provider ?? "unknown provider"} account ${a.accountSlot ?? "?"}`;
+        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. Do not enroll another account. The steps are in references/replacing-a-credential.md."],
+          [...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,
         );
@@ -337,7 +388,7 @@ if (!connected) {
         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`]);
+        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";
@@ -353,6 +404,7 @@ if (!connected) {
     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";
     if (rows === null) {
+      accountsNext = "read the coding accounts again; the account list could not be read this time";
       add("coding accounts", "catalyst-skills 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.
@@ -360,7 +412,7 @@ if (!connected) {
       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-skills accounts", usable.length > 0 ? "ok" : "unfinished", lines, "a tenant owner or admin", link("/settings/coding-accounts"));
+      add("coding accounts", "catalyst-skills 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";
@@ -376,7 +428,7 @@ if (!connected) {
   add("host", "hosts_current in catalyst-skills 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 meta = tryJson(runCli(["contract", "--path", "readinessChecks", "--json"]).stdout);
+  const meta = tryJson(readContract(["contract", "--path", "readinessChecks", "--json"]).stdout);
   const row = Array.isArray(meta) ? meta.find((r) => r.id === "hosts_current") : 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
@@ -392,7 +444,10 @@ if (!connected) {
   const how = fw === null ? null : link(fw.page);
   const howLines = fw?.command ? [`the owner runs: ${fw.command}`] : [];
   if (hc === null) {
-    add("host", "hosts_current in catalyst-skills 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. Press Re-check on the projects page."], "a tenant owner or admin", link("/settings/linear-teams"));
+    add("host", "hosts_current in catalyst-skills 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. Press Re-check on the projects page."], "a workspace owner or admin", link("/settings/linear-teams")).next =
+      teamRows === null
+        ? "refresh the contract (catalyst-skills contract --refresh), then run this again; the project list could not be read, so the host check cannot be either"
+        : "press Re-check on the projects page, then run this again";
   } else if (hc.state === "pass") {
     add("host", "hosts_current in catalyst-skills contract --path teams", "ok", [`hosts_current pass (read on ${hc.team})`]);
   } else {
@@ -401,6 +456,70 @@ if (!connected) {
   }
 }
 
+// ── repository declarations ───────────────────────────────────────────────────────────────────────
+// A repository's own settings live in its committed `.catalyst/catalyst.toml`. Whether the project's
+// 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-skills 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" },
+};
+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);
+} 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 =
+    "refresh the contract (catalyst-skills 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)) {
+  // Mapped, never checked: the contract carries no checks at all until someone presses Re-check, and
+  // that silence is not "nothing to declare".
+  add("repository declarations", DECL_INSTRUMENT, "unreadable", ["no project has a readiness check yet, so whether its repository is declared cannot be read. Press Re-check on the projects page."], "a workspace owner or admin", link("/settings/linear-teams")).next =
+    "press Re-check on the projects page, then run this again";
+} 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 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 flag = (team, repo, reason) => {
+    const r = describe(reason);
+    lines.push(`${team}${repo ? `, ${repo}` : ""}: ${r.text}`);
+    if (verdict === "ok") declNext = `${repo ? `${repo}: ` : ""}${r.text}`;
+    verdict = "unfinished";
+    owner ??= r.who;
+    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");
+  }
+  for (const c of found) {
+    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})` : ""}; press Re-check on the projects page`);
+    }
+    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") {
+    add("repository declarations", DECL_INSTRUMENT, "unreadable", lines, "a workspace owner or admin", link("/settings/linear-teams")).next = "press Re-check on the projects page, then run this again";
+  } 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);
+  }
+}
+
 // ── the single next step ──────────────────────────────────────────────────────────────────────────
 // The machine's next action is not one sentence: an unconnected machine needs the login, and a
 // connected one needs whatever check failed — and `ready` already printed that check's own fix, so
@@ -417,12 +536,20 @@ 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 Linear, and install the GitHub App",
+  account: "connect the Linear integration on the Connections page (the GitHub App comes later, with the repository)",
   projects: "pick ONE project and map its stages (or adopt the Catalyst workflow)",
-  repositories: "register the repository, attaching it to the project you mapped",
+  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",
   "coding accounts": accountsNext,
+  "repository declarations": declNext,
   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
+// them: the coding account first (nothing runs without one, and it needs no other step), then the
+// 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"];
+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.
 const personPart = parts.find((p) => p.part === "person");
@@ -434,16 +561,50 @@ if (personPart && personalGrantIncomplete && workspaceResolved) {
 }
 const blocked = parts.filter((p) => p.verdict !== "ok" && p.blocking);
 const stuck = blocked[0] ?? parts.find((p) => p.verdict !== "ok") ?? null;
-const next =
+// ⛔ AN UNREADABLE PART NEVER BORROWS ITS "UNFINISHED" ACTION. NEXT holds what to do when a part was
+// read and is not done. A part that could not be read has no such basis: its step is reading it
+// again, and the parts after it depend on it, so none of theirs is named either. Coding accounts set
+// 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`)
+    : NEXT[p.part];
+let next =
   stuck === null
     ? null
-    : { part: stuck.part, action: NEXT[stuck.part], 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 latest = npm.error || npm.status !== 0 ? null : semver(npm.stdout);
+  // The installer is the update path, not `catalyst-skills 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 };
+  }
+  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: `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 };
+}
 const finished = parts.every((p) => p.verdict === "ok");
 
 if (flags.json) {
-  console.log(JSON.stringify({ cli: via, connected, cloud, personalConnections, parts, localSync, next, finished }));
+  console.log(JSON.stringify({ cli: via, connected, cloud, personalConnections, parts, localSync, next, finished, notes: retireNote === null ? [] : [retireNote] }));
 } else if (flags.next) {
-  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 dispatch stage.");
+  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}` : ""}`);
 } else {
   for (const p of parts) {
@@ -456,6 +617,6 @@ if (flags.json) {
     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 dispatch stage 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);

package/skills/catalyst-setup/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Am I set up? Machine readiness (Node, the tenant connection, the cached contract, the CLI path, the skills, the SDK, the optional replica) plus tenant readiness from the contract's per-team checks, in one verdict: what passes, what is blocked, what is merely waiting, and who can click what. Use when someone asks "am I set up", "what is missing", "why does nothing happen", "is the replica running", or right after connecting a new machine. Reports; never repairs.
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.2 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.4 — written in this repository for customer tenants -->
 
 # Am I set up?
 

package/skills/connect-me/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.2 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.4 — written in this repository for customer tenants -->
 
 # Connect me
 

package/skills/how-catalyst-works/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   How Catalyst Cloud runs a ticket on the customer's own tenant, as facts an agent loads on demand: the eight-phase ladder and what each phase produces, the eleven board slots and this team's live stage map, what happens when a phase fails (retry, backoff, Remediate, park), how the queue is ordered and routed and every reason a ticket is excluded, and the coding-account model. Use when a person asks "how does this work?", "why did it do that?", "why is this stuck?", "what runs next?" or "how does it prioritise?". Read-only; its scripts explain one ticket's eligibility in plain English, show what is running and queued, and print the tenant's stage map and thresholds straight from the contract.
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.2 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.4 — written in this repository for customer tenants -->
 
 # How Catalyst works
 

package/skills/run-this-project/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.2 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.4 — written in this repository for customer tenants -->
 
 # Run this project
 

package/skills/unstick/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.2 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.4 — written in this repository for customer tenants -->
 
 # Unstick
 

package/skills/what-needs-me/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.2 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.4 — written in this repository for customer tenants -->
 
 # What needs me
 

package/skills/whats-happening/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   The desk for a Catalyst Cloud tenant. Use when the person asks "what's happening?", "where are we?", "why is that stuck?", "what closed?", "what's next?", or asks for something to be done rather than known. Reads the tenant contract, what is running and queued, the eligibility explainer and the open asks through the catalyst-skills CLI, and answers in one reply with ticket ids. Routes work to a project owner and decisions to what-needs-me. Never composes a URL, never polls, never answers as the human.
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.2 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.4 — written in this repository for customer tenants -->
 
 # What's happening