@catalyst-cloud/catalyst-skills 0.5.0 → 0.8.0

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

@@ -1,164 +0,0 @@
-#!/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";
-import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
-
-export const PACKAGE = "@catalyst-cloud/catalyst-skills";
-export const CONNECT_HINT = CONNECT_COMMAND;
-
-/** ~/.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 (!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) {
-    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/lib/credential.mjs

@@ -1,29 +0,0 @@
-#!/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-linear/scripts/move.mjs

@@ -1,41 +0,0 @@
-#!/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

@@ -1,93 +0,0 @@
-#!/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

@@ -1,49 +0,0 @@
-#!/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

@@ -1,32 +0,0 @@
----
-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 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.
-- 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

@@ -1,6 +0,0 @@
-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

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

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

@@ -1,66 +0,0 @@
-# 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 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.
-
-## The eleven 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 |
-| `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 |
-
-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 | `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 |
-| `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 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/check.mjs

@@ -1,75 +0,0 @@
-#!/usr/bin/env node
-// check.mjs — "am I set up?" in one verdict: the machine checks the CLI runs (Node, the connection,
-// the cached contract, the CLI path, the skills, the SDK, the optional replica) plus every team's
-// readiness vector from the tenant contract, then the list of who can click what. Wraps
-// `catalyst-skills ready --json`; reports, never repairs. Exit 0 READY, 1 NOT READY, 2 not connected.
-import { parseJson, runCli } from "./lib/cli.mjs";
-
-const HELP = `Usage: node scripts/check.mjs [--json]
-
-Prints one line per check (ok / note / FAIL), the fix and who can apply it for every failure, the
-verdict, and a "who can click what" list grouped by the person or role each fix needs.
-A note never flips the verdict (the replica is optional; an informational readiness check is a note).
-
---json prints the CLI's report document {ready, checks[]} unchanged.
-Exit 0 READY, 1 NOT READY, 2 this machine is not connected to a tenant yet.`;
-
-const args = process.argv.slice(2);
-if (args.includes("--help") || args.includes("-h")) {
-  console.log(HELP);
-  process.exit(0);
-}
-const unknown = args.filter((a) => a !== "--json");
-if (unknown.length > 0) {
-  console.error(`unknown argument: ${unknown.join(" ")}`);
-  console.log(HELP);
-  process.exit(1);
-}
-
-const res = runCli(["ready", "--json"]);
-if (res.code === 2) {
-  console.error(res.stderr.trim() || "catalyst-skills ready refused");
-  process.exit(2);
-}
-const report = parseJson(res.stdout);
-if (!report || !Array.isArray(report.checks)) {
-  console.error(res.stderr.trim() || res.stdout.trim() || "catalyst-skills ready printed no report");
-  process.exit(res.code === 0 ? 1 : res.code);
-}
-if (args.includes("--json")) {
-  console.log(JSON.stringify(report));
-  process.exit(report.ready ? 0 : 1);
-}
-
-const failures = [];
-for (const c of report.checks) {
-  const tag = c.note ? "note" : c.ok ? "ok  " : "FAIL";
-  console.log(`${tag}  ${c.line}`);
-  if (!c.ok && !c.note) {
-    if (c.fix) console.log(`      fix: ${c.fix}`);
-    if (c.who) console.log(`      who: ${c.who}`);
-    failures.push(c);
-  }
-}
-console.log(report.ready ? "READY" : "NOT READY");
-
-if (failures.length > 0) {
-  console.log("");
-  console.log("Who can click what:");
-  const byWho = new Map();
-  for (const c of failures) {
-    const who = c.who ?? "unknown (the check named nobody)";
-    if (!byWho.has(who)) byWho.set(who, []);
-    byWho.get(who).push(c);
-  }
-  for (const [who, list] of byWho) {
-    console.log(`  ${who}:`);
-    for (const c of list) console.log(`    - ${c.id}: ${c.fix ?? c.line}`);
-  }
-}
-const notes = report.checks.filter((c) => c.note && !c.ok);
-if (notes.length > 0) {
-  console.log("");
-  console.log(`Notes that do not block: ${notes.map((c) => c.id).join(", ")} — see references/what-each-check-means.md`);
-}
-process.exit(report.ready ? 0 : 1);