@catalyst-cloud/catalyst-skills 0.1.1 → 0.2.1

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.

package/skills/catalyst-setup/scripts/check.mjs

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

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

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// lib/cli.mjs — the one way a skill script reaches the Catalyst Cloud SDK and API: by spawning the
+// catalyst-skills CLI this bundle installed. It reads customer.json to find that CLI and nothing
+// else; it never holds the account key itself. This file is a library — run a sibling script with
+// --help for usage. Identical in every skill of this bundle on purpose (skills install one directory
+// at a time, so nothing shared outside the skill would ever be installed).
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PACKAGE = "@catalyst-cloud/catalyst-skills";
+export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: CATALYST_CLOUD_TOKEN=<account key> npx ${PACKAGE} login`;
+
+/** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME before 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 customer config, or exit 2 with one line naming the connect command. Never throws. */
+export function requireCustomerConfig() {
+  const path = configPath();
+  if (!existsSync(path)) {
+    console.error(CONNECT_HINT);
+    process.exit(2);
+  }
+  let cfg;
+  try {
+    cfg = JSON.parse(readFileSync(path, "utf8"));
+  } catch (err) {
+    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") {
+    console.error(`${path} is missing required fields — ${CONNECT_HINT}`);
+    process.exit(2);
+  }
+  return cfg;
+}
+
+/**
+ * Run one catalyst-skills verb and return {code, stdout, stderr}. Spawns the CLI whose path the
+ * connect step recorded in customer.json; falls back to `npx @catalyst-cloud/catalyst-skills` when
+ * no path is recorded or it no longer exists. Exits 2 when the machine is not connected.
+ */
+export function runCli(args, opts = {}) {
+  const cfg = requireCustomerConfig();
+  const recorded = typeof cfg.cliPath === "string" && existsSync(cfg.cliPath);
+  const command = recorded ? process.execPath : process.platform === "win32" ? "npx.cmd" : "npx";
+  const argv = recorded ? [cfg.cliPath, ...args] : [PACKAGE, ...args];
+  const res = spawnSync(command, argv, {
+    encoding: "utf8",
+    input: opts.stdin,
+    env: process.env,
+    maxBuffer: 64 * 1024 * 1024,
+    shell: !recorded && process.platform === "win32",
+  });
+  if (res.error) {
+    console.error(`could not run ${recorded ? cfg.cliPath : `npx ${PACKAGE}`}: ${res.error.message}`);
+    process.exit(2);
+  }
+  return { code: res.status ?? 1, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
+}
+
+/**
+ * Run a verb that must succeed. On exit 2 (the CLI's "not configured / refused" class) the script
+ * exits 2; on any other non-zero exit it exits 1. The CLI's own stderr is forwarded either way so the
+ * reason is never lost.
+ */
+export function runCliOrExit(args, opts = {}) {
+  const res = runCli(args, opts);
+  if (res.code === 0) return res;
+  const why = res.stderr.trim() || res.stdout.trim() || `catalyst-skills ${args.join(" ")} exited ${res.code}`;
+  console.error(why);
+  process.exit(res.code === 2 ? 2 : 1);
+}
+
+/** Parse the CLI's --json stdout; null when it is not JSON (the caller decides what that means). */
+export function parseJson(stdout) {
+  try {
+    return JSON.parse(stdout);
+  } catch {
+    return null;
+  }
+}
+
+/** Forward the `source: replica|api (...)` line a query verb prints, so the answer names its source. */
+export function forwardSourceLine(res) {
+  for (const line of res.stderr.split("\n")) {
+    if (line.startsWith("source:")) console.error(line);
+  }
+}
+
+/** True for a ticket identifier such as ABC-123; false for a GitHub node id or anything else. */
+export function looksLikeTicket(s) {
+  return /^[A-Za-z][A-Za-z0-9]*-\d+$/.test(s);
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  console.log("lib/cli.mjs is a library used by the scripts beside it; run any of those with --help for usage.");
+}

package/skills/catalyst-setup/scripts/replica-status.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// replica-status.mjs — is the optional local replica alive, and how far behind is it? Wraps
+// `catalyst-skills replica status`, which needs no network (a pidfile, a writer-lock heartbeat and
+// the cursor row); `--probe` adds the one network call that compares the cursor with the cloud's
+// head. The CLI's exit code passes straight through: 0 fresh, 1 present but stale, 2 not connected,
+// 3 absent. A skill reads that code to choose its source; it never refuses to work over it.
+import { runCli } from "./lib/cli.mjs";
+
+const HELP = `Usage: node scripts/replica-status.mjs [--probe] [--json]
+
+  --probe   also fetch the cloud's head cursor and print how far behind the replica is
+  --json    print the CLI's status document {verdict, exitCode, cursor, heartbeatAgeMs, ...}
+
+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=<account 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);
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(HELP);
+  process.exit(0);
+}
+const unknown = args.filter((a) => a !== "--probe" && a !== "--json");
+if (unknown.length > 0) {
+  console.error(`unknown argument: ${unknown.join(" ")}`);
+  console.log(HELP);
+  process.exit(1);
+}
+
+const cliArgs = ["replica", "status"];
+if (args.includes("--probe")) cliArgs.push("--probe");
+if (args.includes("--json")) cliArgs.push("--json");
+const res = runCli(cliArgs);
+if (res.stdout.trim()) console.log(res.stdout.trimEnd());
+if (res.code !== 0 && res.stderr.trim()) console.error(res.stderr.trimEnd());
+
+const meaning = {
+  0: "fresh — skills read the replica",
+  1: "stale — skills read the API and name that source",
+  2: "not connected to a tenant",
+  3: "absent — the replica is optional; nothing is wrong",
+};
+if (!args.includes("--json")) console.log(`verdict ${res.code}: ${meaning[res.code] ?? "unexpected exit code"}`);
+process.exit(res.code);

package/skills/connect-me/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: connect-me
+description: >-
+  Connect this machine to the customer's Catalyst Cloud tenant with their account key, cache the tenant contract, and verify. Use when a person is getting started, when their config is missing or broken, when they rotated their key, when a skill script exits 2 saying the machine is not connected, or when they ask which tenant this machine belongs to. The key names the tenant, so nobody types an account id. Installing the skills is not this skill's job; the agent's own install command did that.
+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 -->
+
+# Connect me
+
+Connecting is one command. It asks the cloud who the key belongs to, writes the config every skill and the CLI read, and caches the tenant contract beside it.
+
+```sh
+CATALYST_CLOUD_TOKEN=<account-key> catalyst-skills login
+```
+
+With no environment variable and a terminal attached, `catalyst-skills login` prompts for the key without echoing it. `--key <account-key>` is the third form, for a script. `npx @catalyst-cloud/catalyst-skills login` works when the package is not installed globally. A non-default cloud is pinned with `CATALYST_CLOUD_BASE_URL` or `--base-url`.
+
+**This skill never installs skills.** You are already reading one, so the person's agent installed the set with its own command. Connecting is only about the credential and the contract.
+
+**What it writes.** `~/.config/catalyst-cloud/customer.json` (mode 0600) holding the key, the tenant it resolved, and the absolute path of this CLI so skill scripts can spawn it; `~/.config/catalyst-cloud/contract.json`, the tenant contract with its ETag.
+
+**The replica is optional and one command away.** Nothing has to be running for reads, writes, asks or explanations; the API is origin-fresh. `catalyst-skills replica start --detach` starts the local replica for cheap repeated reads and ad hoc SQL; `login --start-replica` does the same at the end. Every skill checks `catalyst-skills replica status` first and falls back to the API when the replica is absent or stale, saying so.
+
+## What you do
+
+1. Ask the person for their account key. Their tenant admin mints it in settings; you cannot. A workstation key connects but is refused by the contract and by machine-only reads (a one-line notice, not a failure); tell them an account key is needed for the full set.
+2. Run the login command. Its output names the tenant (`Connected to <name> (<slug>)`), the config path, and the cached contract version.
+3. Verify with `node scripts/verify-connection.mjs`: one line each for the tenant, the contract version, and the replica; exit 1 when the machine is not connected.
+4. Run `catalyst-skills ready` and read the verdict to them.
+5. Offer the replica: `catalyst-skills replica start --detach`, then `catalyst-skills replica status`. For keeping it alive across a reboot, load `references/keeping-the-replica-running.md`.
+6. If login fails: a `401` means a stale or mistyped key, back to the tenant admin, never a retry loop; a network error names the URL, check `--base-url`. If login succeeds but prints a line naming two contract versions, the tenant serves a contract outside this bundle's range: update the bundle before using the other skills.
+
+## The verbs a session runs first
+
+Every skill session opens with these, in this order, before doing anything else:
+
+1. `catalyst-skills status` to confirm the tenant this machine belongs to and where the config and contract live.
+2. `catalyst-skills contract` to load the tenant contract (cached per its own policy; `--refresh` forces a revalidation; `--path teams.0.stages` prints one sub-document).
+3. `catalyst-skills replica status` to learn the read source: exit 0 fresh, 1 stale, 2 not configured, 3 absent.
+4. `catalyst-skills ready` for the full verdict: Node, config, contract, CLI path, skills, SDK, replica, and the tenant's own readiness checks with who can fix each.
+
+## Load on demand
+
+| when | read |
+| -- | -- |
+| the person wants the replica writer to survive a reboot, or asks what it stores and whether anything needs cleaning | `references/keeping-the-replica-running.md` |
+| the full readiness vector and what each check means | the `catalyst-setup` skill |
+
+## Rules
+
+- **The key is a credential.** It goes into the login command or `CATALYST_CLOUD_TOKEN` and nowhere else: not into tickets, transcripts, or any file you write besides the one login writes.
+- **Never guess a tenant.** There is no `--account`; the key is the only tenant selector, on purpose. If the cloud names no tenant for the key, stop and say so.
+- **Read the update notice.** After a bundle update, the next command prints one line with the changelog entry and what to run; read it to the person if they are watching.

package/skills/connect-me/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Connect me"
+  short_description: "Connect this machine to your Catalyst Cloud tenant with your account key, cache the tenant contract, and verify"
+  default_prompt: "Use $connect-me to connect this machine to my Catalyst Cloud tenant."
+policy:
+  allow_implicit_invocation: false

package/skills/connect-me/agents/portability.yaml

@@ -0,0 +1,5 @@
+identity: { pack: catalyst-cloud-skills, skill: connect-me }
+effects: [workspace-write]
+mutating: true
+invocation: explicit
+exposure: [catalog]

package/skills/connect-me/references/keeping-the-replica-running.md

@@ -0,0 +1,88 @@
+# Keeping the replica running
+
+This reference restates invariants of the local replica the Catalyst Cloud SDK manages. Paths are the CLI's defaults; the replica file can be moved with `--db` and the config records it.
+
+## The supported path is the plain command
+
+```sh
+catalyst-skills replica start --detach    # start in the background, write a pidfile, return
+catalyst-skills replica status            # 0 fresh, 1 stale, 2 not configured, 3 absent; one line either way
+catalyst-skills replica status --probe    # also compare the local cursor with the cloud head
+catalyst-skills replica stop              # signal the pidfile's process
+catalyst-skills replica start             # foreground, Ctrl-C to stop
+```
+
+It is a Node process, not a service. Node 22 or newer with its built-in SQLite module runs it the same on macOS, Linux and Windows, and the bundle never requires a daemon, because a required service is the first thing that breaks on a laptop. The writer is not a prerequisite for any skill; a fresh one is a preference. A skill must never refuse to work because the replica is down, and must never silently read a stale one; `replica status` is the one exit code that settles both.
+
+## What it holds on disk, and why nothing rotates
+
+Under `~/.config/catalyst-cloud/` by default:
+
+| file | what it is |
+| -- | -- |
+| `replica.db` | one SQLite file: the tenant's mirrored tables, kept current by upserts and deletes from the stream |
+| `replica.db.writer.lock` | the writer's lock, with a heartbeat the status check reads |
+| `replica.db.pid` | the background writer's process id, written by `--detach` |
+| a `sync_meta` row inside the database | the stream cursor, so a restart resumes where it stopped |
+| `watch-cursor.json` | the events-only cursor for `catalyst-skills watch`, stamped with the tenant; a few bytes |
+
+The replica is upserts and deletes into one file, so it neither grows without bound nor needs pruning; the cursor is a row. There is no directory of old files to clean and nothing to rotate. If the writer logs, it logs to standard error and the shell decides where that goes; nothing under the config directory is a log.
+
+The first start seeds the file from the cloud's snapshot (one full copy of the tables) and then follows the stream; a restart resumes from the saved cursor. When the cloud can no longer replay from that cursor it tells the writer to re-seed, which the writer does on its own.
+
+## Freshness, as the status check judges it
+
+`replica status` needs no network. It answers fresh when the pidfile's process is alive, the writer lock's heartbeat is younger than the staleness threshold (15 seconds by default; `--stale-ms` overrides), and the cursor row is non-empty. Anything else is stale (exit 1) with the reasons listed, absent (exit 3) when there is no file, or not configured (exit 2) when the machine is not connected. `--probe` adds the one network call, fetching the cloud head to print how far behind the local cursor is. Every read verb prints `source: replica (cursor N)` or `source: api (replica stale|absent|not configured)` on standard error, so the answer always names where it came from.
+
+## Surviving a reboot
+
+Optional. The plain command is the supported path; these are for people who want the writer back after a restart. Each example assumes a global install (`npm install -g @catalyst-cloud/catalyst-skills`); substitute the absolute path `catalyst-skills status` prints as the CLI path if you prefer. Run the writer in the foreground under the supervisor (no `--detach`), so the supervisor owns the process.
+
+### macOS, launchd
+
+Save as `~/Library/LaunchAgents/dev.catalystcloud.replica.plist`, then `launchctl load ~/Library/LaunchAgents/dev.catalystcloud.replica.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>dev.catalystcloud.replica</string>
+  <key>ProgramArguments</key><array>
+    <string>/usr/local/bin/catalyst-skills</string><string>replica</string><string>start</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardErrorPath</key><string>/tmp/catalyst-cloud-replica.err</string>
+</dict></plist>
+```
+
+Check the path to the binary with `which catalyst-skills`; Homebrew Node installs under `/opt/homebrew/bin`. `launchctl unload` the same file to stop it.
+
+### Linux, systemd user unit
+
+Save as `~/.config/systemd/user/catalyst-cloud-replica.service`, then `systemctl --user daemon-reload && systemctl --user enable --now catalyst-cloud-replica`:
+
+```ini
+[Unit]
+Description=Catalyst Cloud local replica
+After=network-online.target
+
+[Service]
+ExecStart=/usr/bin/env catalyst-skills replica start
+Restart=on-failure
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+```
+
+For a writer that should run while nobody is logged in, `loginctl enable-linger $USER` once. `journalctl --user -u catalyst-cloud-replica` shows its standard error.
+
+### Windows
+
+There is no service wrapper in the bundle. Task Scheduler runs `catalyst-skills replica start` at logon with "Run whether user is logged on or not" and "If the task fails, restart every 1 minute"; or run `catalyst-skills replica start --detach` from a shell after logging in, which is the plain path and works the same as elsewhere.
+
+## Two things that look like problems and are not
+
+- **Two writers.** The writer lock guards the file, so a second writer on the same file is refused rather than allowed to corrupt it. Stop the first (`replica stop`, or the supervisor) before starting another or moving the file.
+- **A stale verdict right after start.** The first start seeds the whole snapshot before it goes live; `status` reads stale until the cursor row appears. Ask again once `replica start` has printed its live line, or watch `status --probe` count the lag down.