@catalyst-cloud/catalyst-skills 0.7.0 → 0.8.0

package/skills/connect-me/SKILL.md

@@ -1,63 +0,0 @@
----
-name: connect-me
-description: >-
-  Connect this machine to the person's Catalyst Cloud tenant as themselves — keyless (a browser device-code login) or with their own personal key — cache the tenant contract, and verify. Use when a person is getting started, when their config is missing or broken, when their login expired or 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 login names the tenant and the person, 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@0.7.0 — written in this repository for customer tenants -->
-
-# Connect me
-
-Connecting is one command. Keyless is the preferred rail — with no key, `login` opens a browser device-code flow and logs the person in as themselves:
-
-```sh
-catalyst-skills login
-```
-
-It prints a short code and a URL; the person approves in a browser (or from a phone, on a machine with no browser) and this machine is connected as them. The short-lived session refreshes silently on every request, so they stay connected for months.
-
-A **personal key** still works for a script or an unattended shell — the environment form keeps it out of shell history; `--key <personal-key>` is the third form:
-
-```sh
-CATALYST_CLOUD_TOKEN=<your-personal-key> catalyst-skills login
-```
-
-`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 credential — a keyless login session (`auth`), or a personal key — the tenant it resolved, the person it resolved (`user`: id, label, role, Linear user id), and the absolute path of this CLI so skill scripts can spawn it; `~/.config/catalyst-cloud/contract.json`, the tenant contract with its ETag. A keyless session's token rotates on its own and the file is rewritten atomically each time.
-
-**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. Prefer keyless: run `catalyst-skills login` with no key and have the person approve the code in their browser (or from a phone). Nothing to mint, nothing to paste, nothing to keep out of the transcript. A **personal key** is the fallback for a script or unattended shell — they mint it at Settings → API keys (every active member can; no admin is needed) and hand it to the login command via `CATALYST_CLOUD_TOKEN`; it is shown once, so never put it in a file, a ticket, or this conversation beyond that one command. Either way, do not ask an admin for the tenant's **account key** (`ctc_acct_`, Settings → Account keys): that is a host credential — runners, daemons, the host replica — and a person connected with it has no name on anything their agent writes, and "what needs me" cannot mean them. If they connect with one anyway, login says so on stderr and still works.
-2. Run the login command. Its output names the tenant (`Connected to <name> (<slug>)`), the person (`Connected as <label> (<role>)`), the config path, and the cached contract version. If the person line says their Linear identity is not matched yet, tell them: an admin matches it in Settings → Members, and until then "what needs me" shows everyone's asks.
-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 keyless session that reports "your login expired or was revoked" needs one fresh `catalyst-skills login`, never a retry loop (it means the session was revoked or lapsed past the inactivity window — routine expiry refreshes silently and never surfaces). A `401` on the key rail means a stale, mistyped or revoked key — mint a new one at Settings → API keys, never a retry loop; a network error names the URL, check `--base-url`. A `403` on the contract naming an older cloud means the cloud has not yet deployed personal-key access: update the cloud, or connect with the account key until it has. 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 credential is a secret.** Keyless is safest — nothing to handle. A key 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; and never read back the `auth` block a keyless session stores.
-- **Never guess a tenant.** There is no `--account`; the credential is the only tenant selector, on purpose. If the cloud names no tenant for the login, 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

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Connect me"
-  short_description: "Connect this machine to your Catalyst Cloud tenant with your own personal 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

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

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

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

@@ -1,185 +0,0 @@
-#!/usr/bin/env node
-// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: by spawning the catalyst-skills
-// CLI. The CLI holds the SDK and the key; this file holds neither. It reads
-// ~/.config/catalyst-cloud/customer.json (under CATALYST_SKILLS_HOME when set, else HOME) for the
-// CLI path that login recorded and falls back to `npx @catalyst-cloud/catalyst-skills`.
-//
-// Exit codes every script built on this file shares: 2 = this machine is not connected, 1 = the
-// script's own check failed, 0 = fine.
-import { spawn } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
-
-export const PACKAGE_NAME = "@catalyst-cloud/catalyst-skills";
-export const NOT_CONFIGURED_EXIT = 2;
-export const CHECK_FAILED_EXIT = 1;
-
-export function homeDir() {
-  return process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? process.env.USERPROFILE ?? "/";
-}
-
-export function configDir() {
-  return join(homeDir(), ".config", "catalyst-cloud");
-}
-
-export function configPath() {
-  return join(configDir(), "customer.json");
-}
-
-/** The stored config, or null when the file is absent or unreadable. Never throws. */
-export function loadCustomerConfig() {
-  const path = configPath();
-  if (!existsSync(path)) return null;
-  try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
-    if (!hasCredential(parsed) || typeof parsed.account !== "string") return null;
-    return parsed;
-  } catch {
-    return null;
-  }
-}
-
-/** Print the one not-connected line and exit 2. */
-export function requireConfigured() {
-  const cfg = loadCustomerConfig();
-  if (cfg) return cfg;
-  console.error(`not connected: ${configPath()} is missing or unreadable — run: ${CONNECT_COMMAND}`);
-  process.exit(NOT_CONFIGURED_EXIT);
-}
-
-/** The command and argument prefix that reaches the CLI on this machine. */
-export function cliCommand(cfg = loadCustomerConfig()) {
-  if (cfg && typeof cfg.cliPath === "string" && existsSync(cfg.cliPath)) {
-    return { command: process.execPath, prefix: [cfg.cliPath], via: `node ${cfg.cliPath}` };
-  }
-  const npx = process.platform === "win32" ? "npx.cmd" : "npx";
-  return { command: npx, prefix: [PACKAGE_NAME], via: `npx ${PACKAGE_NAME}` };
-}
-
-/**
- * Run one CLI verb and capture its output. Resolves `{code, stdout, stderr, notConfigured}`;
- * `notConfigured` is true when the CLI itself said the machine is not connected.
- */
-export function runCli(args, { stdin } = {}) {
-  const { command, prefix } = cliCommand();
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, [...prefix, ...args], {
-      stdio: [stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
-      env: process.env,
-      shell: process.platform === "win32",
-    });
-    let stdout = "";
-    let stderr = "";
-    child.stdout.on("data", (d) => (stdout += String(d)));
-    child.stderr.on("data", (d) => (stderr += String(d)));
-    child.on("error", reject);
-    child.on("close", (code) => {
-      resolve({ code: code ?? 1, stdout, stderr, notConfigured: /not (joined|connected)/i.test(stderr) || /not (joined|connected)/i.test(stdout) });
-    });
-    if (stdin !== undefined) child.stdin.end(stdin);
-  });
-}
-
-/**
- * Run one CLI verb with the terminal attached, so a long-running verb such as `watch` streams
- * straight through. Resolves with the exit code; SIGINT and SIGTERM are forwarded to the child.
- */
-export function execCli(args) {
-  const { command, prefix } = cliCommand();
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, [...prefix, ...args], { stdio: "inherit", env: process.env, shell: process.platform === "win32" });
-    const forward = (sig) => () => {
-      try {
-        child.kill(sig);
-      } catch {
-        // already gone
-      }
-    };
-    const onInt = forward("SIGINT");
-    const onTerm = forward("SIGTERM");
-    process.on("SIGINT", onInt);
-    process.on("SIGTERM", onTerm);
-    child.on("error", reject);
-    child.on("close", (code) => {
-      process.off("SIGINT", onInt);
-      process.off("SIGTERM", onTerm);
-      resolve(code ?? 1);
-    });
-  });
-}
-
-/** Parse the CLI's --json output; a parse failure names the first line of what came back. */
-export function parseJson(stdout) {
-  try {
-    return JSON.parse(stdout);
-  } catch {
-    throw new Error(`the CLI did not answer with JSON: ${stdout.split("\n")[0] ?? "(empty)"}`);
-  }
-}
-
-/** Exit 2 with the CLI's own not-connected line when a call reports it; otherwise return the result. */
-export function guard(result) {
-  if (result.notConfigured) {
-    process.stderr.write(result.stderr || result.stdout);
-    process.exit(NOT_CONFIGURED_EXIT);
-  }
-  return result;
-}
-
-/** A tiny flag parser: `--name value`, `--name=value`, `--flag`, repeatable names collected as arrays. */
-export function parseFlags(argv, { values = [], repeat = [], booleans = [] } = {}) {
-  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 value;
-    const eq = name.indexOf("=");
-    if (eq !== -1) {
-      value = name.slice(eq + 1);
-      name = name.slice(0, eq);
-    }
-    if (booleans.includes(name)) {
-      flags[name] = true;
-      continue;
-    }
-    if (!values.includes(name) && !repeat.includes(name)) {
-      console.error(`unknown option: --${name} (try --help)`);
-      process.exit(CHECK_FAILED_EXIT);
-    }
-    if (value === undefined) {
-      value = argv[++i];
-      if (value === undefined) {
-        console.error(`--${name} needs a value`);
-        process.exit(CHECK_FAILED_EXIT);
-      }
-    }
-    if (repeat.includes(name)) flags[name] = [...(flags[name] ?? []), value];
-    else flags[name] = value;
-  }
-  return { flags, positionals };
-}
-
-export function wantsHelp(argv) {
-  return argv.includes("--help") || argv.includes("-h");
-}
-
-const HELP = `lib/cli.mjs — shared helper; not a command.
-
-Resolves the catalyst-skills CLI (the path login recorded in ${configPath()}, else npx ${PACKAGE_NAME})
-and runs one verb for the script that imports it. Run any sibling script with --help instead.`;
-
-if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
-  console.log(HELP);
-  process.exit(0);
-}

package/skills/connect-me/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/connect-me/scripts/verify-connection.mjs

@@ -1,68 +0,0 @@
-#!/usr/bin/env node
-// verify-connection.mjs — did the connect step land? One line each for the tenant, the contract version and the
-// replica, from the CLI's own verbs. The machine is connected when `status` names a tenant.
-import { CHECK_FAILED_EXIT, cliCommand, loadCustomerConfig, parseFlags, runCli, wantsHelp } from "./lib/cli.mjs";
-
-const HELP = `Usage: node scripts/verify-connection.mjs [--json]
-
-Runs catalyst-skills status, contract --path contractVersion, and replica status, and prints one
-line for each: the tenant this machine is connected to, the cached contract version, and the replica
-verdict. Nothing is written.
-
-Options:
-  --json   one JSON document instead of three lines
-  --help   this text
-
-Exit codes: 1 when status reports the machine is not connected (or the CLI could not be run);
-0 otherwise, whatever the replica verdict is, because the replica is optional.`;
-
-const argv = process.argv.slice(2);
-if (wantsHelp(argv)) {
-  console.log(HELP);
-  process.exit(0);
-}
-const { flags, positionals } = parseFlags(argv, { booleans: ["json"] });
-if (positionals.length > 0) {
-  console.error(`unexpected argument: ${positionals[0]} (see --help)`);
-  process.exit(CHECK_FAILED_EXIT);
-}
-
-const cfg = loadCustomerConfig();
-const { via } = cliCommand(cfg);
-const out = { cli: via, connected: false, tenant: null, contractVersion: null, replica: null };
-
-let status;
-try {
-  status = await runCli(["status"]);
-} catch (err) {
-  console.error(`could not run the CLI (${via}): ${err instanceof Error ? err.message : String(err)}`);
-  process.exit(CHECK_FAILED_EXIT);
-}
-const tenantLine = status.stdout.split("\n").find((l) => l.startsWith("Tenant:"));
-out.connected = status.code === 0 && Boolean(tenantLine) && !status.notConfigured;
-out.tenant = tenantLine ? tenantLine.slice("Tenant:".length).trim() : null;
-
-if (out.connected) {
-  const contract = await runCli(["contract", "--path", "contractVersion"]);
-  out.contractVersion = contract.code === 0 ? contract.stdout.trim() : null;
-  out.contractError = contract.code === 0 ? undefined : (contract.stderr || contract.stdout).trim().split("\n").at(-1);
-  const replica = await runCli(["replica", "status", "--json"]);
-  try {
-    const parsed = JSON.parse(replica.stdout);
-    out.replica = { verdict: parsed.verdict, exitCode: replica.code, cursor: parsed.cursor ?? null, reasons: parsed.reasons ?? [] };
-  } catch {
-    out.replica = { verdict: "unknown", exitCode: replica.code, line: (replica.stdout || replica.stderr).trim() };
-  }
-}
-
-if (flags.json) {
-  console.log(JSON.stringify(out));
-} else if (!out.connected) {
-  console.log(`not connected (${via}): ${(status.stdout || status.stderr).trim().split("\n")[0] ?? "status printed nothing"}`);
-} else {
-  console.log(`tenant: ${out.tenant}`);
-  console.log(out.contractVersion ? `contract: version ${out.contractVersion} cached` : `contract: not cached (${out.contractError ?? "unknown reason"}) — run: catalyst-skills contract --refresh`);
-  const r = out.replica;
-  console.log(`replica: ${r.verdict}${r.cursor !== null && r.cursor !== undefined ? ` (cursor ${r.cursor})` : ""}${r.reasons && r.reasons.length ? ` — ${r.reasons.join("; ")}` : ""}${r.verdict === "absent" ? " — optional; start it with: catalyst-skills replica start --detach" : ""}`);
-}
-process.exit(out.connected ? 0 : CHECK_FAILED_EXIT);

package/skills/how-catalyst-works/SKILL.md

@@ -1,42 +0,0 @@
----
-name: how-catalyst-works
-description: >-
-  How Catalyst Cloud runs a ticket on the customer's own tenant, as facts an agent loads on demand: the eight-phase ladder and what each phase produces, the eleven board slots and this team's live stage map, what happens when a phase fails (retry, backoff, Remediate, park), how the queue is ordered and routed and every reason a ticket is excluded, and the coding-account model. Use when a person asks "how does this work?", "why did it do that?", "why is this stuck?", "what runs next?" or "how does it prioritise?". Read-only; its scripts explain one ticket's eligibility in plain English, show what is running and queued, and print the tenant's stage map and thresholds straight from the contract.
-allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
----
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.7.0 — written in this repository for customer tenants -->
-
-# How Catalyst works
-
-You explain the machine. A person asks why Catalyst did something, what it will do next, or how it decides; you answer from the tenant's live contract and eligibility explainer, and from the invariants in the references below. You never guess a stage name, a label, a threshold or a route: the scripts print the live values.
-
-Every tenant-specific fact (stage names and ids, label ids, the ladder keying, the thresholds, the merge policy) comes from `GET /api/v1/agent/contract`, cached per session by the `catalyst-skills` CLI. The references restate only what does not vary per tenant.
-
-## Run first
-
-Run each with `--help` before reading anything else; the scripts are black boxes, not reading material.
-
-- `node scripts/explain-ticket.mjs <ticket>` — why one ticket is or is not about to run, as one paragraph plus the raw eligibility row.
-- `node scripts/whats-running.mjs [--queue] [--accounts] [--team <key>]` — fleet activity, the agent roster and lease attributions; with `--queue` the dispatch order; with `--accounts` the coding-account line.
-- `node scripts/show-my-map.mjs [--team <key>]` — this tenant's slot-to-stage map, ladder and live thresholds.
-
-Exit codes: 0 answered, 1 not found or a usage error, 2 this machine is not connected or the cloud refused (the one line printed says which; connect first if it names the login).
-
-## Load on demand
-
-| when | read |
-| -- | -- |
-| "what are the phases, what does each produce, when is a ticket Done?" | `references/the-ladder.md` |
-| "which column is which, why does nothing dispatch, what is a slot?" | `references/stages-and-mapping.md` |
-| a phase FAILED, a card went to Remediate, a ticket is parked or on hold | `references/when-a-phase-fails.md` |
-| "what runs next, why not this one, what does this exclusion reason mean?" | `references/what-runs-next.md` |
-| "why is nothing running", walls, quarantine, which provider ran a phase | `references/coding-accounts.md` |
-
-## Rules
-
-- **Print, never recall.** A stage name, label, threshold or route in your answer must have come from a script's output in this session.
-- **A reason is a layer.** Translate an exclusion reason through `references/what-runs-next.md`; name what releases it and who can do that (a clock, a comment, a push, an operator).
-- **Unknown is not absent.** An `unknown` verdict from the explainer means the cloud could not look; report it as inconclusive.
-- **System causes are one alert.** A provider outage, the runner image breaker or a paused repository holds many tickets for one reason; never escalate it ticket by ticket.
-- **Say what a key cannot see.** A few PR facts are not mirrored (labels, the reviewer's reaction) and a park is released only by an operator; the scripts say so and name the settings page. Do not fill the gap with a guess.
-- **Depth lives elsewhere.** What a ticket accumulates in Linear is `catalyst-linear`; what a PR accumulates and whether it is mergeable is `catalyst-github`; raising a decision is `what-needs-me`.

package/skills/how-catalyst-works/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "How Catalyst Works"
-  short_description: "Explain how Catalyst Cloud runs a ticket: the ladder, your stage map, failures, what runs next, coding accounts"
-  default_prompt: "Use $how-catalyst-works to explain why Catalyst did that, or what it will run next."
-policy:
-  allow_implicit_invocation: true

package/skills/how-catalyst-works/agents/portability.yaml

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

package/skills/how-catalyst-works/references/coding-accounts.md

@@ -1,51 +0,0 @@
-# Coding accounts: slots, windows, walls, and what a key cannot read yet
-
-This reference restates the model, which does not vary per tenant. Your tenant's actual accounts — provider, harness, declared and observed state, usage windows, walls, quarantine — are readable with your key: `node scripts/whats-running.mjs --accounts` prints the live rows (`catalyst-skills accounts`). No credential or email ever rides in that read; the settings page (`/settings/coding-accounts`) is where an admin enrols, pauses or removes one.
-
-## What a slot is
-
-A slot is one enrolled coding-account credential: a subscription or token that runs phases. A tenant may enrol several accounts of the same provider under the same email, because identity is the credential, not the email; the email is a display field. A revoked slot leaves the roster.
-
-## Providers and harnesses
-
-| Provider | Harness | Credential |
-| -- | -- | -- |
-| Claude | the Claude CLI | its own subscription |
-| Codex | Codex | its own subscription |
-| GLM | the Claude CLI | its own token |
-| Qwen | the Claude CLI | its own token |
-| GLM via OpenCode | OpenCode | the same GLM enrolment |
-| Qwen via OpenCode | OpenCode | the same Qwen enrolment |
-
-The harness is a property of the catalog entry, never a routing input. Which provider a phase runs on is the routing decision in `references/what-runs-next.md`; the routing rows, not the slot, name the model.
-
-## Two state axes
-
-- **Declared**: `active` or `disabled`. The operator sets it.
-- **Observed**: `healthy`, `degraded` or `unknown`. The poller sets it from what the provider reports.
-
-Two more lifecycle facts sit beside them: **quarantined** (system-set, on a credential conflict or an authentication mismatch; sticky, only an operator clears it) and **revoked** (operator-set).
-
-## Windows, walls, headroom
-
-- Subscriptions meter usage over a **5-hour** window and a **7-day** window, each with a used percentage and a reset time.
-- A **wall** is the window limit a session can die at mid-run. Before a slot is granted, a fit gate projects the phase's expected burn against the remaining headroom with a safety margin; a slot that would hit the wall is not offered.
-- **Headroom** per provider is advisory: it counts eligible and degraded slots and the best remaining percentage, and it can never promise what a reservation would refuse because both read the same eligibility predicate.
-- Holds: a Claude slot can serve several phases at once up to a per-account cap; a Codex slot serves one at a time because its refresh tokens are single-use.
-- Slot choice orders by usage band, then live-hold count, then used percent, then the latest reset, so bursts spread across accounts rather than stacking on one.
-
-A poller refreshes an active slot's usage every 5 minutes and a disabled one daily. Separately, vendor status pages are polled for provider health; that signal says nothing about your own accounts' windows, walls or quarantine.
-
-## What the settings page shows
-
-Your tenant's coding-accounts page lists each slot with a five-value status, first match wins: expired-or-revoked, walled, active, attested (healthy and active, but the provider is unobserved), unobserved. A drilldown shows the windows, the holds and the history.
-
-## What a key cannot read yet, and what to say
-
-Coding-account status (provider, declared and observed state, window percentages and resets, walls, quarantine, live holds) is served only behind the tenant's admin gate. So when a human asks "why is nothing running?":
-
-1. Run `node scripts/explain-ticket.mjs <ticket>` for a stuck ticket. `routing_unavailable` with a detail naming a slot or provider, or `no_eligible_account_slot` in the routing block, points at accounts.
-2. Read the live rows with `catalyst-skills accounts` and say what they show; an empty list means no account is enrolled, and the script prints the settings link. Do not guess a wall or a quarantine from silence — a wall is the `walled` field, a quarantine is `quarantined` with its reason.
-3. Treat it as ONE fleet-level cause for every ticket it holds, never as a per-ticket escalation.
-
-The customer session never holds or mints a coding-account credential; phases run in the cloud on the enrolled accounts, and repository access is a per-phase installation token.

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

@@ -1,54 +0,0 @@
-# Stages and mapping: eleven slots, five that matter, and how to read this team's map
-
-This reference restates invariants (the slot vocabulary, which slots are load-bearing, the allowed state types, the three mapping modes). Everything about YOUR team — which Linear stage each slot maps to, its name, its type, whether it still exists — is live on the contract under `teams[].stages`. Read it with `node scripts/show-my-map.mjs [--team <key>]`; never quote a stage name or id from memory.
-
-## The eleven slots, in pipeline order
-
-`dispatch`, `intake`, `research`, `plan`, `implement`, `remediate`, `verify`, `review`, `pr`, `done`, `canceled`
-
-A slot is Catalyst's name for a position on the board. A stage is the Linear workflow state your team actually has. Mapping is the per-team table that binds each slot to one stage.
-
-## Five slots are load-bearing
-
-| Slot | Why it matters | Allowed Linear state types |
-| -- | -- | -- |
-| `dispatch` | Moving a card here is how work is dispatched. Nothing is offered from any other column. | `unstarted`, `backlog` |
-| `intake` | Where a never-seen ticket lands for the optional intake pass. | `unstarted`, `backlog` (never Linear's reserved triage type) |
-| `pr` | Where a card must sit for `merge` to be offered. | `started` |
-| `done` | Written by the merge webhook. | `completed` |
-| `canceled` | Terminal; a card here is never work. | `canceled` |
-
-An absent or wrongly-typed mapping on one of these five is a distinct silent failure: the ladder simply never moves. The other six slots are informational — a wrong value costs a warning in readiness, not a stall. That asymmetry is why "map my stages" is a five-field decision.
-
-## Three mapping modes
-
-The contract's `teams[].workflowMode` reports which one a team is in:
-
-- **adopted**: Catalyst created its recommended stage set for the team, one stage per slot, with verify and review sharing one validation stage.
-- **mapped**: the team kept its existing stages and a human chose which stage fills each slot.
-- **mixed**: some slots adopted, some hand-chosen.
-
-`teams[].gitAutomation` is a stored consent for a feature that is not built yet (Catalyst managing a team's Linear git automations); nothing reads it, so `off` never stops work and turning it on would start none. What decides whether a team's tickets start is the mapping above: until dispatch, pr, done and canceled each point at a live stage, Catalyst starts nothing in that team, and `explain` says so by name.
-
-## The state id is the authority; names are display
-
-Each mapped stage carries a `stateId`, a display `name`, a `type`, `stateStillExists` and a `source` (how the mapping was chosen). Only the id is a lookup key. A Linear-to-Linear import can preserve every human-readable name while re-minting every state id, and then a name-based lookup points at nothing. So:
-
-- Move cards by slot (`catalyst-linear`'s move script does this) and let the CLI resolve the id from the contract. Never move a card "to Todo" by name.
-- `stateStillExists: false` means the mapped state is provably gone; the map needs fixing in your tenant settings before that slot can be written to. The CLI refuses such a move rather than guessing.
-- The stage names the contract shows come from the mirror's live view of Linear, not from a stored snapshot, so they are current at read time.
-
-## How to read the printed map
-
-`node scripts/show-my-map.mjs` prints, per team, one row per slot: the slot, the stage name (or `(unmapped)`, or `(state gone)`), the state type, whether the state still exists, and the source. Load-bearing slots are starred. Then the team's ask, hold and release labels with `(absent)` where the workspace has no such label, then the ladder (phases, keying, intake on or off) and the live thresholds.
-
-Reading it for a question:
-
-- "Why does nothing dispatch?" — is `dispatch` mapped, does its state still exist, and is the card actually in that stage? `node scripts/explain-ticket.mjs <ticket>` names `not_at_dispatch_stage` when the card is elsewhere.
-- "Why is merge not running?" — is the card in the `pr` slot's stage?
-- "Why did the card go to Remediate?" — `remediate` is mapped, so a failed phase moved it there (see `references/when-a-phase-fails.md`); if `remediate` is unmapped the same episode shows up as the hold label from `teams[].labels.hold` instead.
-- "The team's Backlog is not in the list" — correct. Backlog is not a slot. Parking a card is a move to the team's backlog-type state, which the CLI resolves from the team's live workflow states rather than from the map.
-
-## Readiness over the mapping
-
-The contract carries a readiness vector per team (`teams[].readiness`), including whether every mapped state exists, whether the mapping is total, whether the types are compatible, whether the labels are present, whether writes land and whether the webhook covers the team. A check the cloud could not run is `unknown`, never `pass`. `catalyst-setup` reads this vector; this skill only points at it.