@catalyst-cloud/catalyst-skills 0.4.0 → 0.7.0

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

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+// where-am-i.mjs — how far has setup got? FIVE 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), and `contract --path …` for the account, the projects and the repositories.",
+  "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"),
+    );
+  }
+}
+
+// ── 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;
+  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.");
+    const ready = rows.length > 0 && rows.every((t) => (t.readiness?.status ?? "unchecked") === "ready");
+    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"));
+  }
+}
+
+// ── 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",
+};
+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 this machine can read is finished. 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

@@ -1,10 +1,10 @@
 ---
 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 ten 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.
+  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 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.7.0 — written in this repository for customer tenants -->
 
 # Am I set up?
 
@@ -26,7 +26,7 @@ You answer one question with one verdict and one list. The verdict is READY or N
 - 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: `CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login`, with the person's own key from Settings → API keys. Never guess a tenant; the key is the only selector.
+- 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.
 - 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/references/what-each-check-means.md

@@ -1,12 +1,14 @@
 # What each check means
 
-This page restates invariants: the ten per-team readiness checks the cloud runs, what each proves, its fix and who can click it; the machine checks the CLI adds; and the four replica verdicts. The live values are never restated: each check's severity and whether it needs a human's answer come from the contract's `readinessChecks[]`, each team's current states from `teams[].readiness`, and the people who can answer from `humans[]`. `node scripts/check.mjs` prints all of it; this page is how to read what it printed.
+This page restates invariants: the per-team readiness checks the cloud runs, what each proves, its fix and who can click it; the machine checks the CLI adds; and the four replica verdicts. The live values are never restated: each check's severity and whether it needs a human's answer come from the contract's `readinessChecks[]`, each team's current states from `teams[].readiness`, and the people who can answer from `humans[]`. `node scripts/check.mjs` prints all of it; this page is how to read what it printed.
 
 ## How a team's readiness is scored
 
-A team's status is one of `ready`, `degraded`, `blocked` or `unchecked`. The engine always reports all eleven checks; a check it could not run is `unknown`, never `pass`. Any failing check the contract marks as blocking makes the team blocked; any unknown, and any failing check marked degrading, makes it degraded. Unchecked means no readiness pass has run for that team yet, which is a note, not a failure. Readiness is stamped with the account-wide mapping revision it was computed against, so a stale verdict is visible as such.
+A team's status is one of `ready`, `degraded`, `blocked` or `unchecked`. The engine always reports every check the contract lists; a check it could not run is `unknown`, never `pass`. Any failing check the contract marks as blocking makes the team blocked; any unknown, and any failing check marked degrading, makes it degraded. Unchecked means no readiness pass has run for that team yet, which is a note, not a failure. Readiness is stamped with the account-wide mapping revision it was computed against, so a stale verdict is visible as such.
 
-## The eleven checks
+## The checks
+
+The contract's `readinessChecks[]` is the list of record. A check that appears there and not here is newer than this page; `node scripts/check.mjs` still prints it with its own severity, fix and owner, so read the printed line and say you did.
 
 | check id | proves | when it fails, the fix | who clicks |
 | -- | -- | -- | -- |
@@ -20,9 +22,12 @@ A team's status is one of `ready`, `degraded`, `blocked` or `unchecked`. The eng
 | `writes_land` | Catalyst has written to this team successfully | "no write observed" is waiting, not failing: it clears the first time Catalyst moves a ticket. "Write refused" means Linear rejected the last write: check the connection and the team's permissions | owner or admin when refused; otherwise nobody |
 | `webhook_covers_team` | events for this team are arriving | confirmed once a repository is registered and events flow; "no delivery observed" is waiting | owner or admin, by registering the repository |
 | `hosts_current` | no connected host runs an older mapping revision | a host that is behind re-loads the mapping on its next connect; a host that did not report its revision is flagged rather than assumed current; "no host connected" is waiting | whoever runs that host |
-| `environment_declared` | a committed environment declaration for the team's default repository is in effect (`.catalyst/environment.json` was ingested, is valid, and its latest proposal is approved) | `no_team_repo_default`: register a repository and make it the team's default; `no_environment_declaration`: commit the declaration file to that repository; `declaration_invalid` / `declaration_read_failed`: fix the file (the ingest names the error); `declaration_awaiting_approval`: an owner or admin approves the proposal in Settings → Environment |
+| `environment_declared` | a committed environment declaration for the team's default repository is in effect (`catalyst.env.json` at the repository root was ingested, is valid, and its latest proposal is approved) | `no_team_repo_default`: register a repository and make it the team's default; `no_environment_declaration`: commit the declaration file to that repository; `declaration_invalid` / `declaration_read_failed`: fix the file (the ingest names the error); `declaration_awaiting_approval`: an owner or admin approves the proposal in Settings → Environment | owner or admin, except committing the file, which is whoever can push to the repository |
+| `tools_resolvable` | every MCP server and CLI the team's approved environment declaration names can be resolved for that team's repository | `tool_reference_unresolved`: the declaration names a vault secret that does not exist — add it at the right scope or correct the declaration; `toolchain_cli_missing`: a declared CLI is not in the runner image, which is not self-service; `tool_declarations_unread` reads as `unknown` and clears itself | owner or admin, in the declaration or Settings → Environment |
+| `reviewer_required` | this team's repository can merge under its own merge policy with the reviewers configured | it fails only under a strict merge policy with no reviewer — configure one at Settings → Repositories → Code reviews, or change the repository's merge policy; work still runs, only the merge waits | owner or admin, in settings |
+| `reviewer_configured` | a code reviewer is configured for this team's repository at all, whatever the current policy requires | a *failing* `reviewer_configured` never blocks or degrades a team — with no reviewer, pull requests merge on green checks and resolved threads alone; configure one at Settings → Repositories → Code reviews. An `unknown` one (`merge_reviewer_unread`: the reviewer registry could not be read) still degrades the team, like any unknown | owner or admin, in settings; nobody is required when it fails |
 
-Three checks are informational by design (labels, event delivery, host currency): they degrade a team but never block it. Which are which is served on `readinessChecks[].severity`; do not memorise the split.
+Some checks degrade a team without ever blocking it, and one is informational only — informational means a *fail* never moves the verdict, not that the check cannot: an unknown still degrades. Which check is which is served on `readinessChecks[].severity`; do not memorise the split.
 
 ## Reasons that look like failures and are not
 
@@ -37,10 +42,13 @@ Three checks are informational by design (labels, event delivery, host currency)
 | id | proves | fix |
 | -- | -- | -- |
 | `node` | Node 22 or newer, which the SDK's built-in SQLite engine needs | install Node 22+ |
-| `config` | this machine is connected: `customer.json` exists and loads | `CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login`; the person mints the key at Settings → API keys |
+| `config` | this machine is connected: `customer.json` exists and loads | `npx @catalyst-cloud/catalyst-skills login` (keyless: the person approves in their browser); or, with a personal key minted at Settings → API keys, the same command prefixed with `CATALYST_CLOUD_TOKEN=<your personal key>` |
 | `contract` | the tenant contract is cached and its major version is one this bundle accepts | `catalyst-skills contract --refresh`; a version outside the range means update the bundle. A 403 naming an older cloud means the cloud has not yet deployed personal-key access |
+| `bundle` | the installed CLI is at least the version this tenant requires | `npm install -g @catalyst-cloud/catalyst-skills@latest && catalyst-skills login`; a note, never a failure |
 | `cliPath` | the CLI path recorded at login still exists, so skill scripts can spawn it | re-run login |
 | `skills` | every skill of this bundle is present where the CLI installed them | `catalyst-skills install` |
+| `cliRelease` | the installed CLI is not behind the newest published release | the same upgrade command as `bundle`; a note, never a failure |
+| `skillsRelease` | the installed skill files are not behind the newest published bundle | `npx skills update -y`; a note, never a failure. A line saying the check could not run means the registry was unreachable, not that anything is wrong |
 | `sdk` | the SDK loads, so the replica and the watch are available | run under Node 22.15 or newer; every read still works through the API meanwhile |
 | `replica` | the optional replica is fresh | a note, never a failure; see below |
 
@@ -57,6 +65,14 @@ Three checks are informational by design (labels, event delivery, host currency)
 
 `--probe` adds the one network call: it compares the local cursor with the cloud's head and prints how far behind the replica is, the only honest "how stale" number. A skill must never refuse to work because the replica is down, and must never silently read a stale one; both halves are one exit code away.
 
+## The writer stops itself after repeated snapshot failures
+
+`replica start` backs off with jitter after a failed or incomplete snapshot pull, and gives up after five consecutive snapshot failures rather than retrying forever — a writer that keeps failing never hammers the tenant. A snapshot that completes resets the count to zero. Both `catalyst-skills replica status` and `catalyst-skills ready` name the stopped state, the count, the last error, and the command that restarts it. The four exit codes above are unchanged: a stopped writer with a database already on disk still reads stale, since there truly is no live writer.
+
 ## Who can click what
 
 The last block `check.mjs` prints groups every failure by the person it needs. Machine fixes name "you", the person at the keyboard. Tenant fixes name the owner or admin roles the contract lists (as Linear user ids, since that is how the cloud knows them), because the settings page that repairs a mapping, a connection or a label is theirs. A check the contract marks as not needing an answer names nobody: it is informational or self-clearing. This skill reports; it never repairs, because no key-reachable repair verb exists yet.
+
+## Setting up one team at a time
+
+A team starts receiving work only once its stages are saved, and that is done one team at a time: a tenant owner or admin opens Settings → Linear teams, picks the team and presses Map my stages (or Adopt the Catalyst workflow). No other team's stages or tickets change; only the labels Adopt creates are shared across the workspace. Before saving, the screen lists which of that team's tickets would start and which stay where they are. Once saved, the tickets in the team's dispatch stage start; tickets in other stages that Catalyst never worked on stay where they are. To pilot safely, pick a low-stakes team, move anything in its dispatch stage that should not start back to Backlog, and leave the other teams unmapped. `gitAutomation` in the contract plays no part: nothing reads it.

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

@@ -8,9 +8,10 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
 export const PACKAGE = "@catalyst-cloud/catalyst-skills";
-export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE} login`;
+export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: ${CONNECT_COMMAND}`;
 
 /** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME before HOME. */
 export function configPath() {
@@ -32,7 +33,7 @@ export function requireCustomerConfig() {
     console.error(`${path} could not be read (${err instanceof Error ? err.message : String(err)}) — ${CONNECT_HINT}`);
     process.exit(2);
   }
-  if (!cfg || typeof cfg !== "object" || typeof cfg.key !== "string" || typeof cfg.baseUrl !== "string") {
+  if (!hasCredential(cfg) || typeof cfg.baseUrl !== "string") {
     console.error(`${path} is missing required fields — ${CONNECT_HINT}`);
     process.exit(2);
   }

package/skills/catalyst-setup/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-setup/scripts/replica-status.mjs

@@ -14,7 +14,7 @@ const HELP = `Usage: node scripts/replica-status.mjs [--probe] [--json]
 Exit codes, passed through from catalyst-skills replica status:
   0  fresh: a live writer, a young heartbeat, a cursor — skills read the replica
   1  stale: the file exists but the writer is gone or behind — skills read the API and say so
-  2  not connected to a tenant — run: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login
+  2  not connected to a tenant — run: npx @catalyst-cloud/catalyst-skills login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login)
   3  absent: no replica file — optional; start one with: catalyst-skills replica start --detach`;
 
 const args = process.argv.slice(2);

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 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.7.0 — written in this repository for customer tenants -->
 
 # Connect me
 

package/skills/connect-me/scripts/lib/cli.mjs

@@ -10,6 +10,7 @@ import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
 export const PACKAGE_NAME = "@catalyst-cloud/catalyst-skills";
 export const NOT_CONFIGURED_EXIT = 2;
@@ -33,7 +34,7 @@ export function loadCustomerConfig() {
   if (!existsSync(path)) return null;
   try {
     const parsed = JSON.parse(readFileSync(path, "utf8"));
-    if (!parsed || typeof parsed !== "object" || typeof parsed.key !== "string" || typeof parsed.account !== "string") return null;
+    if (!hasCredential(parsed) || typeof parsed.account !== "string") return null;
     return parsed;
   } catch {
     return null;
@@ -44,7 +45,7 @@ export function loadCustomerConfig() {
 export function requireConfigured() {
   const cfg = loadCustomerConfig();
   if (cfg) return cfg;
-  console.error(`not connected: ${configPath()} is missing or unreadable — run: CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE_NAME} login`);
+  console.error(`not connected: ${configPath()} is missing or unreadable — run: ${CONNECT_COMMAND}`);
   process.exit(NOT_CONFIGURED_EXIT);
 }
 

package/skills/connect-me/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/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 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.7.0 — written in this repository for customer tenants -->
 
 # How Catalyst works
 

package/skills/how-catalyst-works/references/stages-and-mapping.md

@@ -28,7 +28,7 @@ The contract's `teams[].workflowMode` reports which one a team is in:
 - **mapped**: the team kept its existing stages and a human chose which stage fills each slot.
 - **mixed**: some slots adopted, some hand-chosen.
 
-`teams[].gitAutomation` is a separate switch, off by default, because enabling it can delete a team's own review automation in Linear; it is never bundled into "adopt recommended".
+`teams[].gitAutomation` is a stored consent for a feature that is not built yet (Catalyst managing a team's Linear git automations); nothing reads it, so `off` never stops work and turning it on would start none. What decides whether a team's tickets start is the mapping above: until dispatch, pr, done and canceled each point at a live stage, Catalyst starts nothing in that team, and `explain` says so by name.
 
 ## The state id is the authority; names are display
 
@@ -51,4 +51,4 @@ Reading it for a question:
 
 ## Readiness over the mapping
 
-The contract carries a ten-check readiness vector per team (`teams[].readiness`), including whether every mapped state exists, whether the mapping is total, whether the types are compatible, whether the labels are present, whether writes land and whether the webhook covers the team. A check the cloud could not run is `unknown`, never `pass`. `catalyst-setup` reads this vector; this skill only points at it.
+The contract carries a readiness vector per team (`teams[].readiness`), including whether every mapped state exists, whether the mapping is total, whether the types are compatible, whether the labels are present, whether writes land and whether the webhook covers the team. A check the cloud could not run is `unknown`, never `pass`. `catalyst-setup` reads this vector; this skill only points at it.

package/skills/how-catalyst-works/references/what-runs-next.md

@@ -66,7 +66,7 @@ No survivor is `no_eligible_account_slot` when any candidate was skipped on capa
 
 ## The unknowns (the evaluator fails closed)
 
-When the cloud cannot answer, it says so rather than guessing: `ordering_never_published`, `ordering_stale`, `workflow_mapping_unknown`, `ticket_unknown`, `dependency_snapshot_unknown`, `blocker_unknown`, `label_snapshot_unknown`, `prior_artifact_unknown`, `scope_unknown`, `scope_occupancy_unknown`, `branch_snapshot_unknown`. An unknown is "I could not look", never "it is not there"; report it as inconclusive.
+When the cloud cannot answer, it says so rather than guessing: `ordering_never_published`, `ordering_stale`, `workflow_mapping_unknown`, `ticket_unknown`, `dependency_snapshot_unknown`, `blocker_unknown`, `label_snapshot_unknown`, `prior_artifact_unknown`, `scope_unknown`, `scope_occupancy_unknown`, `branch_snapshot_unknown`. An unknown is "I could not look", never "it is not there"; report it as inconclusive. The exception is a team with no saved stage mapping: `workflow_mapping_unknown` never clears on its own there, `explain` names the missing stages, and the fix is a tenant owner or admin mapping the team.
 
 One advisory gates nothing: `human_addressed_unlabeled_ask_suspect` (assigned to a human with no delegate; possibly an unlabelled ask).
 

package/skills/how-catalyst-works/references/when-a-phase-fails.md

@@ -33,12 +33,12 @@ Which parks release themselves:
 
 | Park | Releases by |
 | -- | -- |
-| repeated failure | an operator, not a clock |
-| remediate round cap reached | an operator, not a clock |
+| repeated failure | a release from the person's own login once its cause is fixed (`catalyst-skills release`), not a clock |
+| remediate round cap reached | the same release, which buys one more round, not a clock |
 | missing branch | its own budgeted release loop |
 | rebase conflict | its own budgeted release loop |
 
-Your key cannot release a park; the repair verbs are operator-only. When a ticket is parked, say so, name the failure class the explainer shows, and hand the release to whoever administers the tenant.
+A person's own key releases a park, and every other hold that a retry can fix, in one step: `catalyst-skills release <ticket> --because <what changed>`. The cloud releases every governor holding the ticket or releases nothing and names what a person must do instead (a person's own pull request, a review that will not converge, the lifetime repair budget). It refuses a cause it cannot see change unless the caller says what changed. The `unstick` skill runs that loop. When a ticket is parked, name the failure class the explainer shows and whether its cause is fixed.
 
 ## Two holds that are not failures
 
@@ -53,5 +53,5 @@ Each attempt posts a phase-outcome comment (complete or FAILED, with phase, atte
 
 1. Run `node scripts/explain-ticket.mjs <ticket>`; the reason names the layer.
 2. `retry_backoff` or `routing_unavailable`: wait; it retries itself. Say when.
-3. `cooling_down`, `remediate_parked`, `no_change_hold`, `validate_class_spent`: name what releases it (an operator, a comment, a push) and who can do that.
+3. `cooling_down`, `remediate_parked`, `no_change_hold`, `validate_class_spent`: name what releases it (a release once the cause is fixed, a comment, a push) and who can do that.
 4. A system-level cause (provider down, runner image breaker, repo paused) is ONE alert, never a per-ticket escalation.

package/skills/how-catalyst-works/scripts/lib/cli.mjs

@@ -6,9 +6,10 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
 export const PACKAGE = "@catalyst-cloud/catalyst-skills";
-export const CONNECT_HINT = `CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE} login`;
+export const CONNECT_HINT = CONNECT_COMMAND;
 
 /** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME (used by tests) over HOME. */
 export function configPath() {
@@ -22,8 +23,8 @@ export function loadConfig() {
   if (!existsSync(path)) return { ok: false, reason: `no config at ${path}` };
   try {
     const cfg = JSON.parse(readFileSync(path, "utf8"));
-    if (!cfg || typeof cfg.key !== "string" || typeof cfg.account !== "string") {
-      return { ok: false, reason: `${path} is missing the key or account` };
+    if (!hasCredential(cfg) || typeof cfg.account !== "string") {
+      return { ok: false, reason: `${path} is missing a key or login, or the account` };
     }
     return { ok: true, cfg, path };
   } catch (err) {

package/skills/how-catalyst-works/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/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 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.7.0 — written in this repository for customer tenants -->
 
 # Run this project
 
@@ -42,4 +42,4 @@ Every script exits 2 when this machine is not connected (run `catalyst-skills lo
 - **Escalate inward.** Instrument, then you, then the desk, then the human as an ask filed through `what-needs-me` with what it blocks. Decide the technical calls yourself; take the sane default and record it; a fleet or provider condition is one note, never one ask per ticket.
 - **Reply where the message arrived,** in-thread, tagged, as the app actor. Never post as the human, never answer someone else's ask. Bookkeeping records take the contract's marker (`catalyst-skills write comment --bookkeeping`).
 - **One status summary,** kept current after every reaction: in flight, blocked and on whom, closed, next, each line with a ticket id. Where a human decision is pending, the line carries the ask's id.
-- **Say what a key cannot see.** A park is released only by an operator, and PR labels and reactions are not mirrored; the CLI says so by name and points at settings. Execution history (`explain --history`) and coding-account status (`accounts`) ARE readable — read them rather than reconstructing them from comments.
+- **Say what a key cannot see.** PR labels and reactions are not mirrored; the CLI says so by name and points at settings. A park or hold is released from the person's own login once its cause is fixed, through the `unstick` skill (`catalyst-skills release`). Execution history (`explain --history`) and coding-account status (`accounts`) ARE readable — read them rather than reconstructing them from comments.