@catalyst-cloud/catalyst-skills 0.1.1 → 0.2.0

package/skills/catalyst-linear/scripts/comment.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// comment.mjs — post a comment on a ticket as the tenant's app actor through the agent proxy.
+// A bookkeeping comment (a machine record, not a turn in a conversation) takes --bookkeeping, which
+// prefixes the marker the contract's vocabulary names.
+import { readFileSync } from "node:fs";
+import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wantsHelp } from "./lib/cli.mjs";
+
+const HELP = `Usage: node scripts/comment.mjs <ticket> (--body <text> | --stdin) [--parent <commentId>] [--bookkeeping] [--as-user] [--json]
+
+Posts one comment on a ticket. Wraps: catalyst-skills write comment. Spends one unit of the tenant's
+daily write budget.
+
+  <ticket>               the Linear identifier, e.g. KEY-123
+  --body <text>          the comment body
+  --stdin                read the body from stdin instead
+  --parent <commentId>   reply under this comment (reply where the message arrived)
+  --bookkeeping          this is a machine record: prefix the contract's bookkeeping marker so it
+                         never reads as a human turn
+  --as-user              post with the personal identity instead of the app actor (rare; then a
+                         record needs --bookkeeping to avoid waking an agent)
+  --json                 print the CLI's JSON result
+
+Exit 0 posted, 1 on a usage error, 2 when this machine is not connected to a tenant or the write
+was refused (the daily budget is spent, the ticket is unknown, the route is missing; the line
+says which).`;
+
+const argv = process.argv.slice(2);
+if (wantsHelp(argv)) {
+  console.log(HELP);
+  process.exit(0);
+}
+const { flags, positionals } = parseFlags(argv, {
+  bool: ["stdin", "bookkeeping", "as-user", "json"],
+  value: ["body", "parent"],
+});
+const ticket = positionals[0];
+if (!ticket) usage("comment needs a ticket identifier (see --help)");
+if (!flags.body && !flags.stdin) usage("comment needs --body <text> or --stdin (see --help)");
+if (flags.body && flags.stdin) usage("give --body or --stdin, not both");
+
+let stdin;
+const args = ["write", "comment", ticket, "--json"];
+if (flags.stdin) {
+  stdin = readFileSync(0, "utf8");
+  if (!stdin.trim()) usage("stdin was empty");
+  args.push("--stdin");
+} else {
+  args.push("--body", flags.body);
+}
+if (flags.parent) args.push("--parent", flags.parent);
+if (flags.bookkeeping) args.push("--bookkeeping");
+if (flags["as-user"]) args.push("--as-user");
+
+const r = runCli(args, { stdin });
+exitOnFailure(r);
+relayStderr(r);
+const result = parseJson(r.stdout);
+if (flags.json) console.log(JSON.stringify(result ?? {}));
+else console.log(`comment posted on ${ticket}${result && result.id ? ` (${result.id})` : ""}`);

package/skills/catalyst-linear/scripts/create-ticket.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// create-ticket.mjs — file a new ticket on a team as the app actor. The team is named by its key;
+// the CLI resolves the team id from the contract. A decision for a human is NOT a ticket filed here:
+// that is an ask, raised through the what-needs-me skill so it carries options, a default and blocks.
+import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wantsHelp } from "./lib/cli.mjs";
+
+const HELP = `Usage: node scripts/create-ticket.mjs --team <key> --title <text> [--label <name|id>]... [--priority <0-4>] [--as-user] [--json]
+
+Creates one ticket. Wraps: catalyst-skills write create. Spends one unit of the daily write budget.
+
+  --team <key>          the team key (the prefix of its ticket identifiers)
+  --title <text>        the ticket title
+  --label <name|id>     a label to apply (repeatable); Catalyst label names resolve via the contract
+  --priority <0-4>      Linear priority: 0 none, 1 urgent, 2 high, 3 medium, 4 low
+  --as-user             create with the personal identity instead of the app actor (rare)
+  --json                print the CLI's JSON result (carries the new identifier)
+
+Never cite the new ticket's identifier until this script has printed it. Do not use this to ask a
+human a question: raise an ask instead (what-needs-me), or the question will look like work.
+
+Exit 0 created, 1 on a usage error, 2 when this machine is not connected to a tenant or the write
+was refused (an unknown team key, the daily budget spent; the line says which).`;
+
+const argv = process.argv.slice(2);
+if (wantsHelp(argv)) {
+  console.log(HELP);
+  process.exit(0);
+}
+const { flags } = parseFlags(argv, { bool: ["as-user", "json"], value: ["team", "title", "priority"], repeat: ["label"] });
+if (!flags.team || !flags.title) usage("create-ticket needs --team <key> and --title <text> (see --help)");
+
+const args = ["write", "create", "--team", flags.team, "--title", flags.title, "--json"];
+for (const l of flags.label ?? []) args.push("--label", l);
+if (flags.priority !== undefined) args.push("--priority", flags.priority);
+if (flags["as-user"]) args.push("--as-user");
+const r = runCli(args);
+exitOnFailure(r);
+relayStderr(r);
+const result = parseJson(r.stdout);
+if (flags.json) console.log(JSON.stringify(result ?? {}));
+else {
+  const ident = result && (result.identifier ?? result.id);
+  console.log(`created${ident ? ` ${ident}` : ""} on team ${flags.team}: ${flags.title}`);
+}

package/skills/catalyst-linear/scripts/label.mjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// label.mjs — add or remove labels on a ticket. A Catalyst label name (ask, hold, release) resolves
+// to the id the contract lists for this team; anything else is passed through as a label id.
+import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wantsHelp } from "./lib/cli.mjs";
+
+const HELP = `Usage: node scripts/label.mjs <ticket> [--add <name|id>]... [--remove <name|id>]... [--json]
+
+Adds and/or removes labels. Wraps: catalyst-skills write label. One write-budget unit per call
+direction (add, remove), whatever the label count.
+
+  <ticket>              the Linear identifier, e.g. KEY-123
+  --add <name|id>       a label to add (repeatable)
+  --remove <name|id>    a label to remove (repeatable)
+  --json                print the CLI's JSON result
+
+Names the contract knows (the ask marker, the hold label, the release label) resolve to this team's
+label id; a name the workspace lacks is refused rather than guessed. Any other value is sent as a
+label id unchanged.
+
+Exit 0 written, 1 on a usage error, 2 when this machine is not connected to a tenant or the write
+was refused (a Catalyst label the workspace lacks, the daily budget spent; the line says which).`;
+
+const argv = process.argv.slice(2);
+if (wantsHelp(argv)) {
+  console.log(HELP);
+  process.exit(0);
+}
+const { flags, positionals } = parseFlags(argv, { bool: ["json"], repeat: ["add", "remove"] });
+const ticket = positionals[0];
+if (!ticket) usage("label needs a ticket identifier (see --help)");
+const add = flags.add ?? [];
+const remove = flags.remove ?? [];
+if (add.length === 0 && remove.length === 0) usage("label needs --add and/or --remove (see --help)");
+
+const args = ["write", "label", ticket, "--json"];
+for (const a of add) args.push("--add", a);
+for (const x of remove) args.push("--remove", x);
+const r = runCli(args);
+exitOnFailure(r);
+relayStderr(r);
+const result = parseJson(r.stdout);
+if (flags.json) console.log(JSON.stringify(result ?? {}));
+else {
+  const bits = [];
+  if (add.length) bits.push(`added ${add.join(", ")}`);
+  if (remove.length) bits.push(`removed ${remove.join(", ")}`);
+  console.log(`${ticket}: ${bits.join("; ")}`);
+}

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

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: it spawns the catalyst-skills CLI
+// this machine connected with (the path recorded in customer.json, else npx) and hands back its
+// output. Scripts import it; a person runs it with --help to see what it does. No dependencies.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+export const PACKAGE = "@catalyst-cloud/catalyst-skills";
+export const CONNECT_HINT = `CATALYST_CLOUD_TOKEN=<account key> npx ${PACKAGE} login`;
+
+/** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME (used by tests) over HOME. */
+export function configPath() {
+  const home = process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? process.env.USERPROFILE ?? "";
+  return join(home, ".config", "catalyst-cloud", "customer.json");
+}
+
+/** The config, or a one-line reason it could not be read. Never throws. */
+export function loadConfig() {
+  const path = configPath();
+  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` };
+    }
+    return { ok: true, cfg, path };
+  } catch (err) {
+    return { ok: false, reason: `${path} is unreadable: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+
+/** Exit 2 with the one line every script prints when this machine is not connected to a tenant. */
+export function notConfigured(reason) {
+  console.error(`not connected to a Catalyst Cloud tenant (${reason}) — run: ${CONNECT_HINT}`);
+  process.exit(2);
+}
+
+/**
+ * Run one catalyst-skills verb. Returns { code, stdout, stderr }. The CLI is `node <cliPath>` when
+ * the config recorded one that still exists, else `npx @catalyst-cloud/catalyst-skills`.
+ * Exits 2 (not configured) before spawning anything when the config is absent or unreadable.
+ */
+export function runCli(args, { stdin } = {}) {
+  const loaded = loadConfig();
+  if (!loaded.ok) notConfigured(loaded.reason);
+  const { cfg } = loaded;
+  let cmd;
+  let argv;
+  let shell = false;
+  if (typeof cfg.cliPath === "string" && existsSync(cfg.cliPath)) {
+    cmd = process.execPath;
+    argv = [cfg.cliPath, ...args];
+  } else {
+    cmd = process.platform === "win32" ? "npx.cmd" : "npx";
+    argv = [PACKAGE, ...args];
+    shell = process.platform === "win32";
+  }
+  const r = spawnSync(cmd, argv, {
+    encoding: "utf8",
+    input: stdin,
+    env: process.env,
+    shell,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (r.error) {
+    console.error(`could not run ${cmd}: ${r.error.message} — re-run ${CONNECT_HINT} to record the CLI path`);
+    process.exit(2);
+  }
+  return { code: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+}
+
+/** Print the CLI's stderr (the source line, the contract line, any refusal) on our stderr. */
+export function relayStderr(r) {
+  const text = r.stderr.trimEnd();
+  if (text) console.error(text);
+}
+
+/** A non-zero CLI result ends the script with the same code, its stdout shown so nothing is lost. */
+export function exitOnFailure(r) {
+  if (r.code === 0) return;
+  relayStderr(r);
+  const out = r.stdout.trimEnd();
+  if (out) console.log(out);
+  process.exit(r.code);
+}
+
+export function parseJson(text) {
+  try {
+    return JSON.parse(text.trim());
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A small flag parser: `spec.value` names flags that take a value, `spec.bool` boolean flags,
+ * `spec.repeat` value flags that may repeat (collected into arrays). Unknown flags are a usage error.
+ */
+export function parseFlags(argv, spec = {}) {
+  const value = new Set(spec.value ?? []);
+  const bool = new Set(spec.bool ?? []);
+  const repeat = new Set(spec.repeat ?? []);
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--") {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+    if (!a.startsWith("--")) {
+      positionals.push(a);
+      continue;
+    }
+    let name = a.slice(2);
+    let inline;
+    const eq = name.indexOf("=");
+    if (eq !== -1) {
+      inline = name.slice(eq + 1);
+      name = name.slice(0, eq);
+    }
+    if (bool.has(name)) {
+      flags[name] = true;
+    } else if (value.has(name) || repeat.has(name)) {
+      const v = inline ?? argv[++i];
+      if (v === undefined || v === "") usage(`--${name} needs a value`);
+      if (repeat.has(name)) (flags[name] ??= []).push(v);
+      else flags[name] = v;
+    } else {
+      usage(`unknown option --${name}`);
+    }
+  }
+  return { flags, positionals };
+}
+
+export function usage(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+export function wantsHelp(argv) {
+  return argv.includes("--help") || argv.includes("-h");
+}
+
+const runDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (runDirectly) {
+  if (wantsHelp(process.argv.slice(2)) || process.argv.length <= 2) {
+    console.log(
+      [
+        "lib/cli.mjs — shared helper for this skill's scripts (not a command of its own)",
+        "",
+        "Reads ~/.config/catalyst-cloud/customer.json and runs the catalyst-skills CLI recorded there",
+        `(or npx ${PACKAGE} when no path is recorded). Exit 2 when the machine is not connected.`,
+        "",
+        `Connect first with: ${CONNECT_HINT}`,
+        `Config in use: ${configPath()}`,
+      ].join("\n"),
+    );
+    process.exit(0);
+  }
+}

package/skills/catalyst-linear/scripts/move.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// move.mjs — move a card by SLOT, never by stage name: the CLI resolves the slot to this team's
+// live state id from the contract and refuses a slot that is unmapped or whose state is gone.
+import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wantsHelp } from "./lib/cli.mjs";
+
+const HELP = `Usage: node scripts/move.mjs <ticket> (--slot <slot> | --state-type <type>) [--json]
+
+Moves a ticket's card. Wraps: catalyst-skills write state. Spends one unit of the daily write budget.
+
+  <ticket>              the Linear identifier, e.g. KEY-123
+  --slot <slot>         one of the eleven slots: dispatch, intake, research, plan, implement,
+                        remediate, verify, review, pr, done, canceled. Moving to dispatch is how
+                        work is dispatched.
+  --state-type <type>   the team's first state of this Linear type, resolved from its live
+                        workflow states; use "backlog" to park a card (Backlog is not a slot)
+  --json                print the CLI's JSON result
+
+Exit 0 moved, 1 on a usage error, 2 when this machine is not connected to a tenant or the move
+was refused (the slot is unmapped for the team, its state no longer exists in Linear, the daily
+budget is spent; the line says which).`;
+
+const argv = process.argv.slice(2);
+if (wantsHelp(argv)) {
+  console.log(HELP);
+  process.exit(0);
+}
+const { flags, positionals } = parseFlags(argv, { bool: ["json"], value: ["slot", "state-type"] });
+const ticket = positionals[0];
+if (!ticket) usage("move needs a ticket identifier (see --help)");
+if (!flags.slot && !flags["state-type"]) usage("move needs --slot <slot> or --state-type <type> (see --help)");
+if (flags.slot && flags["state-type"]) usage("give --slot or --state-type, not both");
+
+const args = ["write", "state", ticket, "--json"];
+if (flags.slot) args.push("--slot", flags.slot);
+else args.push("--state-type", flags["state-type"]);
+const r = runCli(args);
+exitOnFailure(r);
+relayStderr(r);
+const result = parseJson(r.stdout);
+if (flags.json) console.log(JSON.stringify(result ?? {}));
+else console.log(`${ticket} moved to ${flags.slot ? `slot ${flags.slot}` : `the team's ${flags["state-type"]} state`}`);

package/skills/catalyst-linear/scripts/read-ticket.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// read-ticket.mjs — one ticket with its comments, relations, labels, linked pull requests and agent
+// sessions inline, from the replica when it is fresh, else the origin-fresh API. The source line the
+// CLI prints on stderr is the freshness verdict; it is always shown.
+import { parseFlags, parseJson, relayStderr, runCli, usage, wantsHelp } from "./lib/cli.mjs";
+
+const HELP = `Usage: node scripts/read-ticket.mjs <ticket> [--comments] [--source replica|api] [--json]
+
+Reads one ticket record. Wraps: catalyst-skills query issue.
+
+  <ticket>               the Linear identifier, e.g. KEY-123
+  --comments             also print every comment (id, author, time, body)
+  --source replica|api   force one source; default is the replica when fresh, else the API
+  --json                 print the full record as JSON
+
+The first stderr line names the source ("source: replica (cursor N)" or "source: api (replica
+stale|absent|not configured)"); quote it when the freshness of the answer matters.
+
+Exit 0 found, 1 not found or a usage error, 2 when this machine is not connected to a tenant or the
+cloud refused the read (the line says which).`;
+
+const argv = process.argv.slice(2);
+if (wantsHelp(argv)) {
+  console.log(HELP);
+  process.exit(0);
+}
+const { flags, positionals } = parseFlags(argv, { bool: ["comments", "json"], value: ["source"] });
+const ticket = positionals[0];
+if (!ticket) usage("read-ticket needs a ticket identifier (see --help)");
+
+const args = ["query", "issue", ticket, "--json"];
+if (flags.source) args.push("--source", flags.source);
+const r = runCli(args);
+relayStderr(r);
+if (r.code !== 0) {
+  const out = r.stdout.trimEnd();
+  if (out) console.log(out);
+  process.exit(r.code);
+}
+const row = parseJson(r.stdout);
+if (!row || typeof row !== "object") {
+  console.log(r.stdout.trimEnd());
+  process.exit(1);
+}
+if (flags.json) {
+  console.log(JSON.stringify(row));
+  process.exit(0);
+}
+
+const line = (label, value) => {
+  if (value === undefined || value === null || value === "") return;
+  console.log(`${label}: ${typeof value === "string" ? value : JSON.stringify(value)}`);
+};
+const names = (list, key) => (Array.isArray(list) ? list.map((x) => (x && typeof x === "object" ? (x[key] ?? JSON.stringify(x)) : String(x))) : []);
+
+line("ticket", row.identifier ?? row.id);
+line("title", row.title);
+line("state", row.state);
+line("priority", row.priority_label ?? row.priority);
+line("assignee", row.assignee_name ?? row.assignee);
+line("delegate", row.delegate_name ?? row.delegate);
+line("team", row.team_key ?? row.team_name ?? row.team_id);
+line("project", row.project_name ?? row.project_id);
+line("cycle", row.cycle_name ?? row.cycle_id);
+line("parent", row.parent_identifier);
+line("labels", names(row.labels, "name").join(", "));
+line("url", row.url);
+line("updated", row.updated_at);
+if (Array.isArray(row.relations) && row.relations.length) {
+  console.log(`relations (${row.relations.length}):`);
+  for (const rel of row.relations) console.log(`  ${rel.type ?? "?"}: ${rel.issue_identifier ?? ""} -> ${rel.related_identifier ?? JSON.stringify(rel)}`);
+}
+if (Array.isArray(row.linked_pulls) && row.linked_pulls.length) {
+  console.log(`linked pull requests (${row.linked_pulls.length}):`);
+  for (const pr of row.linked_pulls) console.log(`  #${pr.number ?? "?"} ${pr.repo_id ?? ""} [${pr.node_id ?? ""}]`);
+}
+if (Array.isArray(row.agent_sessions)) line("agent sessions", row.agent_sessions.length);
+if (Array.isArray(row.activity)) line("activity entries", row.activity.length);
+if (Array.isArray(row.comments)) line("comments", row.comments.length);
+if (row.description) {
+  console.log("description:");
+  console.log(String(row.description).trimEnd());
+}
+if (flags.comments && Array.isArray(row.comments)) {
+  console.log(`== comments (${row.comments.length})`);
+  for (const c of row.comments) {
+    const who = c.author_name ?? c.author_id ?? "?";
+    const bot = c.is_bot ? " [bot]" : "";
+    const parent = c.parent_id ? ` reply-to ${c.parent_id}` : "";
+    console.log(`-- ${c.id} · ${who}${bot} · ${c.updated_at ?? c.created_at ?? ""}${parent}`);
+    console.log(String(c.body ?? "").trimEnd());
+  }
+}

package/skills/catalyst-linear/scripts/search.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// search.mjs — tenant search across ticket identifiers and titles, pull-request titles, project and
+// initiative names. Always the origin-fresh API (the replica holds no search view).
+import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wantsHelp } from "./lib/cli.mjs";
+
+const HELP = `Usage: node scripts/search.mjs <terms...> [--limit <n>] [--json]
+
+Searches your tenant for tickets, pull requests, projects and initiatives matching the terms.
+Wraps: catalyst-skills query search.
+
+  <terms>       one or more words; matched against identifiers, titles and names
+  --limit <n>   max rows (default 50)
+  --json        print the rows as JSON
+
+Exit 0 (an empty result is still 0 and prints "no matches"), 1 on a usage error, 2 when this
+machine is not connected to a tenant or the cloud refused the search (the line says which).`;
+
+const argv = process.argv.slice(2);
+if (wantsHelp(argv)) {
+  console.log(HELP);
+  process.exit(0);
+}
+const { flags, positionals } = parseFlags(argv, { bool: ["json"], value: ["limit"] });
+if (positionals.length === 0) usage("search needs at least one term (see --help)");
+
+const args = ["query", "search", ...positionals, "--json"];
+if (flags.limit) args.push("--limit", flags.limit);
+const r = runCli(args);
+exitOnFailure(r);
+relayStderr(r);
+const rows = parseJson(r.stdout);
+if (flags.json) {
+  console.log(JSON.stringify(rows ?? r.stdout.trimEnd()));
+  process.exit(0);
+}
+const list = Array.isArray(rows) ? rows : rows && typeof rows === "object" ? Object.values(rows).flat() : [];
+if (list.length === 0) {
+  console.log("no matches");
+  process.exit(0);
+}
+for (const row of list) {
+  if (!row || typeof row !== "object") {
+    console.log(String(row));
+    continue;
+  }
+  const kind = row.kind ?? (row.identifier ? "issue" : row.number ? "pull" : "row");
+  const id = row.identifier ?? (row.number !== undefined ? `#${row.number}` : row.id ?? "");
+  console.log(`${kind}  ${id}  ${row.title ?? row.name ?? ""}${row.state ? `  (${row.state})` : ""}`);
+}

package/skills/catalyst-setup/SKILL.md

@@ -0,0 +1,32 @@
+---
+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.
+allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
+---
+<!-- vendored-from: @catalyst-cloud/catalyst-skills — 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.
+
+## 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` |
+
+## Rules
+
+- Report, never repair. No tenant-reachable repair verb exists for an account 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=<account key> npx @catalyst-cloud/catalyst-skills login`, with the key from their tenant admin. Never guess a tenant; 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/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]

package/skills/catalyst-setup/references/what-each-check-means.md

@@ -0,0 +1,61 @@
+# 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.
+
+## How a team's readiness is scored
+
+A team's status is one of `ready`, `degraded`, `blocked` or `unchecked`. The engine always reports all ten 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.
+
+## The ten checks
+
+| check id | proves | when it fails, the fix | who clicks |
+| -- | -- | -- | -- |
+| `oauth_scope` | Catalyst holds the Linear permissions it needs | re-authorise the Linear connection to grant the missing scope | a tenant owner or admin, in settings |
+| `token_live` | the Linear connection is accepted right now | reconnect Linear (expired or revoked), or wait and re-check (Linear unreachable). A distinct reason says Linear was never connected at all | owner or admin |
+| `team_visible` | Catalyst can see this team | most often the team was made private: grant Catalyst access in Linear's team settings, then re-check | owner or admin, in Linear |
+| `mapped_states_exist` | every stage Catalyst mapped still exists in Linear | re-map the team; nothing in the workspace was changed. A pending-write reason means a mapping was just saved and the read has not caught up: wait, do not re-map | owner or admin, in settings |
+| `mapping_total` | every stage Catalyst moves tickets into is mapped | map the missing stages. "Absent" means the team was never mapped; "incomplete" means a few of the load-bearing stages are missing | owner or admin, in settings |
+| `types_compatible` | each load-bearing mapped stage is the right kind (dispatch and intake unstarted or backlog, PR started, done completed, canceled canceled) | change the mapping to a stage of the right kind | owner or admin, in settings |
+| `labels_present` | the labels Catalyst uses exist in the workspace | none needed by a person: Catalyst creates them the first time it uses them | nobody |
+| `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 |
+
+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.
+
+## Reasons that look like failures and are not
+
+- `no_write_observed`, `no_delivery_observed`, `no_host_connected`: nothing has happened yet. Expected on a fresh tenant; they clear on their own.
+- `stages_pending_write`: a mapping was saved and the read predates it. Re-check shortly; re-mapping would be a second write for no reason.
+- `unknown` on any check: the engine could not look. It is not a pass and not a fail; say so.
+
+## The machine checks the CLI adds
+
+`catalyst-skills ready` prepends checks about this machine before the tenant's:
+
+| 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=<account key> npx @catalyst-cloud/catalyst-skills login`; the key comes from the tenant admin |
+| `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 refresh needs an account key, not a workstation key |
+| `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` |
+| `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 |
+
+## The replica's four verdicts
+
+`node scripts/replica-status.mjs` needs no network and exits with the verdict:
+
+| exit | verdict | what a skill does with it |
+| -- | -- | -- |
+| 0 | fresh: a live writer, a heartbeat younger than the staleness threshold, a non-empty cursor | reads the replica and says so |
+| 1 | stale: the file exists but the writer is gone, the heartbeat is old, or there is no cursor | reads the API and says so; `catalyst-skills replica start --detach` brings it back |
+| 2 | not connected to a tenant | the connect step first |
+| 3 | absent: no replica file at all | reads the API; the replica is optional and one command away |
+
+`--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.
+
+## 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 tenant-reachable repair verb exists for an account key yet.