@catalyst-cloud/cli 0.8.0

package/skills/catalyst-onboard/scripts/lib/cli.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: spawn the catalyst-skills CLI.
+// The CLI holds the SDK and the key; this file holds neither. It reads customer.json only to learn
+// where the CLI lives. Run any script beside this one with --help; this file is a library.
+//
+// ⛔ THIS LAUNCHER DOES NOT EXIT ON AN UNCONNECTED MACHINE, and that is deliberate. Every other
+// skill runs against a tenant, so "not connected" is a precondition it refuses on. This skill's job
+// is to REPORT where setup has got to, and "this machine holds no credential" is one of the states
+// it has to be able to report — refusing to run would make the first step of onboarding unreadable.
+// So `tryLoadConfig()` returns null instead of exiting, and the caller decides what that means.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
+
+export const PACKAGE = "@catalyst-cloud/catalyst-skills";
+export const NOT_CONFIGURED_EXIT = 2;
+export const CONNECT_LINE = CONNECT_COMMAND;
+
+export function configPath() {
+  const home = process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? "/";
+  return join(home, ".config", "catalyst-cloud", "customer.json");
+}
+
+/** The stored config, or null when it is absent, unreadable, or holds no credential. Never exits. */
+export function tryLoadConfig() {
+  const path = configPath();
+  if (!existsSync(path)) return null;
+  try {
+    const cfg = JSON.parse(readFileSync(path, "utf8"));
+    return hasCredential(cfg) ? cfg : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Where the CLI is on this machine: the path login recorded when it still exists, else npx. */
+export function cliTarget(cfg = tryLoadConfig()) {
+  const recorded = cfg !== null && typeof cfg.cliPath === "string" && existsSync(cfg.cliPath);
+  return recorded
+    ? { command: process.execPath, prefix: [cfg.cliPath], via: `node ${cfg.cliPath}`, recorded: true }
+    : { command: "npx", prefix: [PACKAGE], via: `npx ${PACKAGE}`, recorded: false };
+}
+
+/**
+ * Run one catalyst-skills verb. Returns {code, stdout, stderr, ran} and never exits: a verb that
+ * refuses because the machine is not connected is a READING, not a failure of this script.
+ * `ran` is false when the CLI could not be started at all.
+ */
+export function runCli(args) {
+  const target = cliTarget();
+  const res = spawnSync(target.command, [...target.prefix, ...args], {
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+    shell: !target.recorded && process.platform === "win32",
+    env: process.env,
+  });
+  if (res.error) return { code: 1, stdout: "", stderr: `could not run ${target.via}: ${res.error.message}`, ran: false };
+  return { code: res.status ?? 1, stdout: res.stdout ?? "", stderr: res.stderr ?? "", ran: true };
+}
+
+/** Parse a verb's --json stdout, or null when it did not answer with JSON. Never exits. */
+export function tryJson(stdout) {
+  try {
+    const value = JSON.parse(stdout.trim());
+    return value === null || typeof value !== "object" ? null : value;
+  } catch {
+    return null;
+  }
+}
+
+/** Minimal flag parsing: --name value, --name=value, --flag. */
+export function parseFlags(argv, spec) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") return { help: true, flags, positionals };
+    if (!a.startsWith("--")) {
+      positionals.push(a);
+      continue;
+    }
+    let name = a.slice(2);
+    let value;
+    const eq = name.indexOf("=");
+    if (eq !== -1) {
+      value = name.slice(eq + 1);
+      name = name.slice(0, eq);
+    }
+    const s = spec[name];
+    if (!s) {
+      process.stderr.write(`unknown option --${name} (try --help)\n`);
+      process.exit(1);
+    }
+    if (s.value) {
+      if (value === undefined) value = argv[++i];
+      if (value === undefined || value === "") {
+        process.stderr.write(`--${name} needs a value\n`);
+        process.exit(1);
+      }
+      flags[name] = value;
+    } else flags[name] = true;
+  }
+  return { help: false, flags, positionals };
+}
+
+export function printHelp(usage, spec, notes = []) {
+  const lines = [`Usage: ${usage}`, ""];
+  const names = Object.keys(spec);
+  if (names.length) {
+    lines.push("Options:");
+    for (const n of names) lines.push(`  --${n}${spec[n].value ? " <value>" : ""}  ${spec[n].help}`);
+    lines.push("");
+  }
+  lines.push(...notes, "", "Exit codes: 0 every readable part is finished · 1 something is unfinished (the report says what and whose) · 2 the CLI could not be run at all");
+  process.stdout.write(lines.join("\n") + "\n");
+}

package/skills/catalyst-onboard/scripts/lib/credential.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// lib/credential.mjs — is this machine connected? The ONE place a skill script decides it, vendored
+// byte-identical into every skill's scripts/lib/ from skill-lib/credential.mjs at the package root
+// (`npm run skill-lib:sync`; a test fails on any drift). Skills install one directory at a time, so
+// each carries its own copy. This file is a library — run a sibling script with --help for usage.
+//
+// customer.json carries exactly one credential: a personal key (`key`), or the keyless login's
+// session (`auth`, the recommended rail). A script never reads either for its value: it spawns the
+// catalyst-skills CLI, which authenticates with whichever is present and refreshes a login's token
+// itself. A new credential kind lands here, once.
+
+/** The command that connects this machine, as every not-connected line names it. */
+export const CONNECT_COMMAND =
+  "npx @catalyst-cloud/catalyst-skills login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login)";
+
+/** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
+export function hasCredential(cfg) {
+  if (cfg === null || typeof cfg !== "object") return false;
+  const key = cfg["key"];
+  if (typeof key === "string" && key !== "") return true;
+  const login = cfg["auth"];
+  return (
+    login !== null &&
+    typeof login === "object" &&
+    login["kind"] === "oauth" &&
+    typeof login["refreshToken"] === "string" &&
+    login["refreshToken"] !== ""
+  );
+}

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

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+// where-am-i.mjs — how far has setup got? SEVEN PARTS, EACH READ BY THE INSTRUMENT THAT OWNS IT, and
+// 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.
+//
+// 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";
+
+const SPEC = {
+  next: { help: "print only the single next step" },
+  json: { help: "one JSON document instead of the report" },
+};
+const NOTES = [
+  "Reads, in this order: `status` (machine), `ready --json` (machine checks and project checks, kept apart),",
+  "`me --json` (person), `contract --path …` for the account, the projects and the repositories,",
+  "`contract --path codingAccounts` (coding accounts; `accounts --json` on an older cloud), and each",
+  "project's hosts_current check with its fixedWhere (host).",
+  "Writes nothing and changes nothing. Runs before this machine is connected — that is one of the states it reports.",
+];
+
+const { help, flags, positionals } = parseFlags(process.argv.slice(2), SPEC);
+if (help) {
+  printHelp("node scripts/where-am-i.mjs [--next] [--json]", SPEC, NOTES);
+  process.exit(0);
+}
+if (positionals.length > 0) {
+  process.stderr.write(`unexpected argument: ${positionals[0]} (try --help)\n`);
+  process.exit(1);
+}
+
+const via = cliTarget().via;
+const parts = [];
+// `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 });
+
+// ── machine ───────────────────────────────────────────────────────────────────────────────────────
+const status = runCli(["status"]);
+if (!status.ran) {
+  process.stderr.write(`${status.stderr}\n`);
+  process.stderr.write(`the catalyst-skills 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 field = (name) => {
+  const line = statusLines.find((l) => l.startsWith(`${name}:`));
+  return line ? line.slice(name.length + 1).trim() : null;
+};
+const tenant = field("Tenant");
+const api = field("API");
+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 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
+// whose id begins with "team:" belongs to a project and cannot be moved from this machine.
+let projectChecks = [];
+let machineFix = null;
+if (connected) {
+  const ready = runCli(["ready", "--json"]);
+  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"})`);
+    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:")));
+    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}` : ""}`);
+    if (failed.length > 0) {
+      machineVerdict = "unfinished";
+      machineFix = failed.find((c) => typeof c.fix === "string")?.fix ?? null;
+    }
+  }
+}
+add(
+  "machine",
+  "catalyst-skills status, and the non-team checks of catalyst-skills ready",
+  machineVerdict,
+  machineLines,
+  "you, on this machine",
+  connected ? null : CONNECT_LINE,
+);
+
+// ── person ────────────────────────────────────────────────────────────────────────────────────────
+if (!connected) {
+  add("person", "catalyst-skills 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;
+  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);
+  } else if (user === null) {
+    add(
+      "person",
+      "catalyst-skills me",
+      "unfinished",
+      ["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 !== "";
+    add(
+      "person",
+      "catalyst-skills me",
+      matched ? "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; get it fixed when convenient."],
+      matched ? null : "a tenant owner or admin",
+      matched ? null : link("/settings/account"),
+      false,
+    );
+  }
+}
+
+// ── account ───────────────────────────────────────────────────────────────────────────────────────
+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 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);
+  } else {
+    const workspace = typeof doc.linearWorkspaceSlug === "string" && doc.linearWorkspaceSlug !== "" ? doc.linearWorkspaceSlug : typeof doc.linearWorkspaceId === "string" && doc.linearWorkspaceId !== "" ? doc.linearWorkspaceId : 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.
+    const envLines = [];
+    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"})`);
+    } else if (envDoc.current === null || envDoc.current === undefined) {
+      envLines.push("environment: nothing declared yet — declare it with `catalyst-skills 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(", ")}`);
+    }
+    add(
+      "account",
+      "catalyst-skills contract --path account, and catalyst-skills environment read",
+      workspace === null ? "unfinished" : "ok",
+      [
+        `${doc.name ?? "(unnamed tenant)"} (${doc.slug ?? "?"})`,
+        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,
+      ],
+      "a tenant owner or admin",
+      link("/settings/connections"),
+    );
+  }
+}
+
+// The host part reads the same rows, so they are kept rather than read twice.
+let teamRows = null;
+// ── projects (a project is one Linear team) ───────────────────────────────────────────────────────
+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 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);
+  } 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 — the full list is on the page below.");
+    // 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
+    // stays "degraded" until a repository is attached, which is the step AFTER this one.
+    const setUp = (t) => 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: press Re-check on the page below to see the rest`);
+      }
+    }
+    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"));
+  }
+}
+
+// ── repositories ──────────────────────────────────────────────────────────────────────────────────
+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 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);
+  } else {
+    const lines = [`${rows.length} registered`, ...rows.map((r) => `${r.owner ?? "?"}/${r.name ?? "?"}`)];
+    lines.push("⛔ REGISTRATION only. This carries no status and no project attachment, so it never proves a repository can be dispatched into.");
+    add("repositories", "catalyst-skills contract --path merge.repositories", rows.length > 0 ? "ok" : "unfinished", lines, "a tenant owner or admin", link("/settings/repositories"));
+  }
+}
+
+// ── coding accounts ───────────────────────────────────────────────────────────────────────────────
+// A phase runs on one of the tenant's enrolled coding accounts. With none, every step above can be
+// finished and nothing will ever start, so this part blocks the "ready" line like any other.
+// 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 account list read and the owner assumed.
+let accountsNext = "enrol a coding account a phase can run on";
+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 ca = tryJson(res.stdout);
+  const older = ca === null && /has nothing at/.test(res.stderr ?? "");
+  const INSTRUMENT = "codingAccounts in catalyst-skills 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 where = typeof ca.page === "string" ? link(ca.page) : null;
+    if (ca.state === "enrolled") {
+      add("coding accounts", INSTRUMENT, "ok", [line, `${ca.activeCount ?? "?"} active`]);
+    } 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);
+    } else if (ca.state === "none_enrolled") {
+      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);
+    }
+  } else if (older) {
+    const acc = runCli(["accounts", "--json"]);
+    const doc = tryJson(acc.stdout);
+    const rows = Array.isArray(doc) ? doc : Array.isArray(doc?.accounts) ? doc.accounts : null;
+    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) {
+      add("coding accounts", "catalyst-skills accounts", "unreadable", [olderLine, `coding accounts could not be read (${(acc.stderr || acc.stdout).trim().split("\n")[0] || "no output"})`], 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-skills accounts", usable.length > 0 ? "ok" : "unfinished", lines, "a tenant 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-skills contract --refresh`], null, null);
+  }
+}
+
+// ── host ──────────────────────────────────────────────────────────────────────────────────────────
+// Read off the contract, never assumed: each checked project carries a hosts_current check, and the
+// 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-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 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
+  // 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})`;
+  // 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 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"));
+  } else if (hc.state === "pass") {
+    add("host", "hosts_current in catalyst-skills 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-skills contract --path teams", "unfinished", [`hosts_current ${hc.state}${hc.reason ? ` (${hc.reason})` : ""} on ${hc.team}: ${detail}`, ...howLines], owner, how);
+  }
+}
+
+// ── 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
+// this carries it through rather than inventing a second answer to the same question.
+const machineNext = connected
+  ? `clear the machine check that failed — ${machineFix ?? "see the machine lines above"}`
+  : "connect this machine";
+const NEXT = {
+  machine: machineNext,
+  person: "get this person's seat and Linear identity sorted",
+  account: "connect Linear, and install the GitHub App",
+  projects: "pick ONE project and map its stages (or adopt the Catalyst workflow)",
+  repositories: "register the repository, attaching it to the project you mapped",
+  "coding accounts": accountsNext,
+  host: "connect a Catalyst host",
+};
+const blocked = parts.filter((p) => p.verdict !== "ok" && p.blocking);
+const stuck = blocked[0] ?? parts.find((p) => p.verdict !== "ok") ?? null;
+const next =
+  stuck === null
+    ? null
+    : { part: stuck.part, action: NEXT[stuck.part], owner: stuck.owner, where: stuck.where, blocking: stuck.blocking };
+const finished = parts.every((p) => p.verdict === "ok");
+
+if (flags.json) {
+  console.log(JSON.stringify({ cli: via, connected, cloud, parts, next, finished }));
+} 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.");
+  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}]`);
+    console.log(`  instrument: ${p.instrument}`);
+    for (const l of p.lines) console.log(`  ${l}`);
+    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}`);
+    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}` : ""}`);
+}
+process.exit(finished ? 0 : 1);

package/skills/catalyst-setup/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: catalyst-setup
+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.8.0 — written in this repository for customer tenants -->
+
+# Am I set up?
+
+You answer one question with one verdict and one list. The verdict is READY or NOT READY. The list is who can click what: the fixes only the person at the keyboard can make, the fixes only a tenant owner or admin can make in settings, and the checks that are simply waiting for the first event. The live check ids, severities, states and the people who can answer come from the contract; the scripts print them, you never restate them.
+
+This readiness skill is part of `catalyst-cloud-skills` and checks tenant setup and operation. Coding workflow skills are a separate pack, `catalyst-dev-skills`. Do not direct a person to the deprecated local runtime or its `catalyst-dev@catalyst` plugin.
+
+## Run first
+
+- `node scripts/check.mjs --help` — every machine and tenant check, one line each, the fix and who for each failure, the verdict, then the who-can-click-what list. Exit 1 when NOT READY.
+- `node scripts/replica-status.mjs --help` — the optional replica's verdict with no network (add `--probe` for how far behind it is). Exit 0 fresh, 1 stale, 2 not connected, 3 absent.
+
+## Load on demand
+
+| when | read |
+| -- | -- |
+| any check is red, unknown or waiting and the person asks what it proves, how to fix it, or who can | `references/what-each-check-means.md` |
+| the person asks how to install, update, or migrate Catalyst skills | `../catalyst-onboard/references/skill-sources.md` |
+
+## Rules
+
+- Report, never repair. No tenant-reachable repair verb exists for a key yet; the settings page is where a tenant owner or admin fixes a mapping, a connection or a label, and you say which one.
+- End every answer with the verdict and the who-can-click-what list, in that order.
+- A stale or absent replica is a note, never a failure: every skill reads the API meanwhile and says so. Do not tell the person to start it unless they want local SQL or cheaper repeated reads.
+- Not connected (exit 2) means the connect step, not a retry: `npx @catalyst-cloud/catalyst-skills login`, which logs the person in keyless in their browser; with a personal key from Settings → API keys instead, prefix it with `CATALYST_CLOUD_TOKEN=<your personal key>`. Never guess a tenant; the login (or the key) is the only selector.
+- Waiting is not failing. "No write observed", "no delivery observed" and "no host connected" clear themselves the first time the thing happens; say that instead of raising them.
+- Unknown is not a pass. A check the engine could not run is reported as such, never rounded up.
+- **Give numbers and a time.** Say how many are `pass`, `fail` and `unknown`, and when the team verdicts were computed: `readiness.checkedAt` per team on the contract, null when no pass has run.
+- Never run a check in a loop. If the person wants to know when a waiting check clears, that is the project-running skill's watch.

package/skills/catalyst-setup/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Am I set up?"
+  short_description: "Machine and tenant readiness in one verdict: what passes, what is blocked, and who can click what"
+  default_prompt: "Use $catalyst-setup to tell me whether this machine and my tenant are ready, and what is missing."
+policy:
+  allow_implicit_invocation: true

package/skills/catalyst-setup/agents/portability.yaml

@@ -0,0 +1,4 @@
+identity: { pack: catalyst-cloud-skills, skill: catalyst-setup }
+effects: []
+invocation: implicit
+exposure: [catalog]