@catalyst-cloud/catalyst-skills 0.1.1 → 0.2.1

package/skills/whats-happening/scripts/explain.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// explain.mjs — "why is this ticket stuck?" in one paragraph. A thin wrapper over
+// `catalyst-skills explain <ticket>`, which reads the cloud's eligibility explainer for the ticket's
+// team and translates the exclusion reason, the failure block and any advisories into plain English.
+import { mustRun, parseFlags, printHelp } from "./lib/cli.mjs";
+
+const SPEC = {
+  json: { value: false, help: "print the raw eligibility row and the explanation as JSON" },
+  history: { value: false, help: "ask for the per-ticket execution history (the CLI says when a key cannot see it yet)" },
+};
+
+const { help, flags, positionals } = parseFlags(process.argv.slice(2), SPEC);
+const ticket = positionals[0];
+if (help || !ticket) {
+  printHelp("node scripts/explain.mjs <ticket> [--json] [--history] [--help]", SPEC, [
+    "The ticket is its identifier (the KEY-123 shape). The explanation names the queue position, the status,",
+    "the reason nothing is offered, the last failure, and what releases it; an unknown reason is printed as the",
+    "cloud spelled it. Read references/why-is-it-stuck.md to turn the reason into the next action.",
+  ]);
+  process.exit(help ? 0 : 1);
+}
+
+const args = ["explain", ticket];
+if (flags.history) args.push("--history");
+if (flags.json) args.push("--json");
+const r = mustRun(args);
+process.stdout.write(r.stdout.endsWith("\n") ? r.stdout : `${r.stdout}\n`);
+process.exit(0);

package/skills/whats-happening/scripts/lib/cli.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: spawn the catalyst-skills CLI.
+// The CLI holds the SDK and the account key; this file holds neither. It reads customer.json only
+// to learn where the CLI lives, and it exits 2 with one line when the machine is not connected.
+// Run any script beside this one with --help; this file is a library and is never run directly.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const PACKAGE = "@catalyst-cloud/catalyst-skills";
+export const NOT_CONFIGURED_EXIT = 2;
+
+export function configPath() {
+  const home = process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? "/";
+  return join(home, ".config", "catalyst-cloud", "customer.json");
+}
+
+/** The connected-machine config, or exit 2 with the one line that says how to connect. */
+export function loadConfig() {
+  const path = configPath();
+  if (!existsSync(path)) notConfigured(`no config at ${path}`);
+  try {
+    const cfg = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof cfg !== "object" || cfg === null || typeof cfg.key !== "string") notConfigured(`config at ${path} has no key`);
+    return cfg;
+  } catch (err) {
+    if (err && err.exitCode === NOT_CONFIGURED_EXIT) throw err;
+    notConfigured(`config at ${path} is unreadable`);
+  }
+}
+
+function notConfigured(why) {
+  process.stderr.write(`not connected (${why}) — run: CATALYST_CLOUD_TOKEN=<account key> npx ${PACKAGE} login\n`);
+  process.exit(NOT_CONFIGURED_EXIT);
+}
+
+/**
+ * Run one catalyst-skills verb and return {code, stdout, stderr}. Uses the CLI path the login
+ * recorded when it still exists, else `npx <package>`. A CLI exit of 2 with a "not joined" or
+ * "not connected" line is turned into this script's own exit 2, so every caller sees one contract.
+ */
+export function runCli(args, opts = {}) {
+  const cfg = loadConfig();
+  const useRecorded = typeof cfg.cliPath === "string" && existsSync(cfg.cliPath);
+  const cmd = useRecorded ? process.execPath : "npx";
+  const argv = useRecorded ? [cfg.cliPath, ...args] : [PACKAGE, ...args];
+  const res = spawnSync(cmd, argv, {
+    input: opts.stdin,
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+    shell: !useRecorded && process.platform === "win32",
+    env: process.env,
+  });
+  if (res.error) {
+    process.stderr.write(`could not run ${cmd}: ${res.error.message}\n`);
+    process.exit(NOT_CONFIGURED_EXIT);
+  }
+  const stdout = res.stdout ?? "";
+  const stderr = res.stderr ?? "";
+  if (res.status === NOT_CONFIGURED_EXIT && /not (joined|connected|configured)/i.test(stderr)) {
+    process.stderr.write(stderr);
+    process.exit(NOT_CONFIGURED_EXIT);
+  }
+  return { code: res.status ?? 1, stdout, stderr };
+}
+
+/** Run a verb and require success; on failure print the CLI's own stderr and exit with its code (or 1). */
+export function mustRun(args, opts = {}) {
+  const r = runCli(args, opts);
+  if (r.code !== 0) {
+    if (r.stderr) process.stderr.write(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
+    if (r.stdout && !opts.quiet) process.stdout.write(r.stdout.endsWith("\n") ? r.stdout : `${r.stdout}\n`);
+    process.exit(r.code === 0 ? 1 : r.code);
+  }
+  return r;
+}
+
+/** Parse the CLI's --json stdout; a non-JSON answer is a failed check, exit 1. */
+export function parseJson(stdout, what = "output") {
+  try {
+    return JSON.parse(stdout.trim());
+  } catch {
+    process.stderr.write(`could not parse ${what} as JSON: ${stdout.trim().slice(0, 200)}\n`);
+    process.exit(1);
+  }
+}
+
+/** Minimal flag parsing for the scripts: --name value, --name=value, --flag, repeated flags collect. */
+export function parseFlags(argv, spec) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") return { help: true, flags, positionals };
+    if (a.startsWith("--")) {
+      let name = a.slice(2);
+      let value;
+      const eq = name.indexOf("=");
+      if (eq !== -1) {
+        value = name.slice(eq + 1);
+        name = name.slice(0, eq);
+      }
+      const s = spec[name];
+      if (!s) {
+        process.stderr.write(`unknown option --${name} (try --help)\n`);
+        process.exit(1);
+      }
+      if (s.value) {
+        if (value === undefined) value = argv[++i];
+        if (value === undefined || value === "") {
+          process.stderr.write(`--${name} needs a value\n`);
+          process.exit(1);
+        }
+        if (s.repeat) (flags[name] ??= []).push(value);
+        else flags[name] = value;
+      } else flags[name] = true;
+      continue;
+    }
+    positionals.push(a);
+  }
+  return { help: false, flags, positionals };
+}
+
+export function printHelp(usage, spec, notes = []) {
+  const lines = [`Usage: ${usage}`, ""];
+  const names = Object.keys(spec);
+  if (names.length) {
+    lines.push("Options:");
+    for (const n of names) lines.push(`  --${n}${spec[n].value ? " <value>" : ""}  ${spec[n].help}`);
+    lines.push("");
+  }
+  lines.push(...notes, "", "Exit codes: 0 ok · 1 the check failed or the arguments were wrong · 2 this machine is not connected to a tenant");
+  process.stdout.write(lines.join("\n") + "\n");
+}

package/skills/whats-happening/scripts/snapshot.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// snapshot.mjs — one call that answers "where are we?": the tenant contract (trimmed to what a
+// status reply needs), what is running, what is queued, what is waiting on a human, and whether the
+// local replica is fresh. Prints ONE JSON document on stdout and the source line on stderr.
+import { mustRun, parseFlags, parseJson, printHelp, runCli } from "./lib/cli.mjs";
+
+const SPEC = {
+  team: { value: true, help: "limit the queue and the board to this team key" },
+  board: { value: false, help: "also include open tickets grouped by stage, in the contract's slot order" },
+  limit: { value: true, help: "board: max tickets to read (default 200)" },
+  "full-contract": { value: false, help: "include the whole contract instead of the trimmed tenant block" },
+};
+
+const { help, flags } = parseFlags(process.argv.slice(2), SPEC);
+if (help) {
+  printHelp("node scripts/snapshot.mjs [--team K] [--board] [--limit N] [--full-contract] [--help]", SPEC, [
+    "Runs, in order: catalyst-skills contract, running, queue, ask list, replica status (and query issues with --board).",
+    "Output: one JSON document {takenAt, source, tenant, running, queue, waitingOnHuman, board?, errors?}.",
+    "A section the cloud refused is reported under errors and the rest still prints; exit 1 in that case.",
+    "Every tenant fact (stage names, thresholds, teams) comes from the contract in this output, never from prose.",
+  ]);
+  process.exit(0);
+}
+
+const errors = {};
+const section = (name, args) => {
+  const r = runCli(args);
+  if (r.code !== 0) {
+    errors[name] = (r.stderr || r.stdout || `exit ${r.code}`).trim().split("\n").at(-1);
+    return null;
+  }
+  return parseJson(r.stdout, name);
+};
+
+const contract = parseJson(mustRun(["contract", "--json"], { quiet: true }).stdout, "contract");
+// `replica status` exits 0 fresh, 1 stale, 3 absent — all three are verdicts with JSON on stdout,
+// not failures; only a non-JSON answer is an error.
+const replica = (() => {
+  const r = runCli(["replica", "status", "--json"]);
+  try {
+    return JSON.parse(r.stdout.trim());
+  } catch {
+    errors.replica = (r.stderr || r.stdout || `exit ${r.code}`).trim().split("\n").at(-1);
+    return { verdict: "unknown", cursor: null, heartbeatAgeMs: null };
+  }
+})();
+const running = section("running", ["running", "--json"]);
+const queue = section("queue", flags.team ? ["queue", "--team", flags.team, "--json"] : ["queue", "--json"]);
+const asks = section("waitingOnHuman", ["ask", "list", "--json"]);
+
+const out = {
+  takenAt: new Date().toISOString(),
+  source: {
+    reads: "api",
+    replica: replica.verdict,
+    replicaCursor: replica.cursor ?? null,
+    replicaHeartbeatAgeMs: replica.heartbeatAgeMs ?? null,
+  },
+  tenant: flags["full-contract"] ? contract : trimContract(contract, flags.team),
+  running,
+  queue,
+  waitingOnHuman: asks,
+};
+
+if (flags.board) {
+  const args = ["query", "issues", "--limit", String(flags.limit ?? 200), "--json"];
+  if (flags.team) args.push("--team", flags.team);
+  const r = runCli(args);
+  const sourceLine = (r.stderr.match(/^source: .*$/m) ?? [null])[0];
+  if (r.code !== 0) errors.board = (r.stderr || `exit ${r.code}`).trim().split("\n").at(-1);
+  else {
+    const rows = parseJson(r.stdout, "issues");
+    out.board = groupByStage(rows, contract, flags.team);
+    if (sourceLine) out.source.board = sourceLine.replace(/^source: /, "");
+  }
+}
+
+if (Object.keys(errors).length) out.errors = errors;
+process.stderr.write(`source: api for running/queue/asks; replica ${replica.verdict}${replica.cursor != null ? ` (cursor ${replica.cursor})` : ""}${out.source.board ? `; board from ${out.source.board}` : ""}\n`);
+process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+process.exit(Object.keys(errors).length ? 1 : 0);
+
+/** The contract facts a status reply needs, and nothing a reply should not paste. */
+function trimContract(doc, teamKey) {
+  const teams = (doc.teams ?? []).filter((t) => !teamKey || String(t.key ?? "").toUpperCase() === teamKey.toUpperCase());
+  return {
+    contractVersion: doc.contractVersion,
+    account: { slug: doc.account?.slug, name: doc.account?.name },
+    slots: doc.slots,
+    ladder: { phases: doc.ladder?.phases, intakeEnabled: doc.ladder?.intakeEnabled, keying: doc.ladder?.keying },
+    thresholds: doc.thresholds,
+    mergeDefaultPolicy: doc.merge?.defaultPolicy,
+    teams: teams.map((t) => ({
+      key: t.key,
+      name: t.name,
+      workflowMode: t.workflowMode,
+      readiness: t.readiness?.status,
+      stages: Object.fromEntries(
+        (doc.slots ?? Object.keys(t.stages ?? {}))
+          .filter((slot) => t.stages?.[slot])
+          .map((slot) => [slot, { name: t.stages[slot].name, type: t.stages[slot].type, stateStillExists: t.stages[slot].stateStillExists }]),
+      ),
+      labels: {
+        ask: (t.labels?.ask ?? []).map((l) => l.name),
+        hold: (t.labels?.hold ?? []).map((l) => l.name),
+        release: (t.labels?.release ?? []).map((l) => l.name),
+      },
+    })),
+  };
+}
+
+/** Open tickets by stage name, ordered by the contract's slot order for the ticket's team; unmapped
+ *  state names follow, alphabetically. Terminal-typed states are dropped so the board is work only. */
+function groupByStage(rows, doc, teamKey) {
+  const order = [];
+  const seen = new Set();
+  const terminal = new Set();
+  for (const t of doc.teams ?? []) {
+    if (teamKey && String(t.key ?? "").toUpperCase() !== teamKey.toUpperCase()) continue;
+    for (const slot of doc.slots ?? []) {
+      const s = t.stages?.[slot];
+      if (!s?.name) continue;
+      if (slot === "done" || slot === "canceled" || ["completed", "canceled", "cancelled"].includes(String(s.type ?? "").toLowerCase())) terminal.add(s.name);
+      else if (!seen.has(s.name)) {
+        seen.add(s.name);
+        order.push(s.name);
+      }
+    }
+  }
+  const byStage = {};
+  for (const r of rows) {
+    const state = String(r.state ?? "unknown");
+    if (terminal.has(state)) continue;
+    (byStage[state] ??= []).push({
+      identifier: r.identifier,
+      title: r.title,
+      priority: r.priority ?? null,
+      assignee: r.assignee_name ?? r.assignee ?? null,
+      updatedAt: r.updated_at ?? null,
+      projectId: r.project_id ?? null,
+    });
+  }
+  const extra = Object.keys(byStage).filter((s) => !seen.has(s)).sort();
+  return { stageOrder: [...order, ...extra], byStage, terminalStagesDropped: [...terminal] };
+}

package/skills/ask/SKILL.md

@@ -1,37 +0,0 @@
----
-name: ask
-description:
-  Record a decision request to the human on the customer's catalyst-cloud tenant. Use when active work is gated on a decision only the human can make — a product/priority/approval call or an action only they can take. The ask carries the question, concrete options, a default that fires if they are silent, and what it blocks. Never use for brainstorming or questions the human asked first.
----
-
-<!-- vendored-from: @catalyst-cloud/catalyst-skills — adapted from the catalyst repository's catalyst-dev plugin (plugins/dev/skills/ask) for customer tenants -->
-
-# Ask — one decision, one record
-
-An ask is a decision request with a deadline-shaped default. It exists so that a question the human must answer is **one record they can find**, not a TODO line, a chat message, or a hope.
-
-## Shape of an ask
-
-An ask always carries, verbatim:
-
-1. **The question** — one sentence, as its title.
-2. **Options** — the realistic choices, each one line.
-3. **Default if silent** — what proceeds, and after how long. The default must be sane enough to actually run.
-4. **Blocks** — what work is held until it is answered, named by ticket or scope.
-
-## Where an ask lives
-
-An ask is a **ticket in the tenant's own Linear**, labelled `catalyst-ask`, written through the same Linear write access the `linearis` skill uses (the customer's own Linear tooling and credential — never a credential you improvised). The tenant's mirror recognises that label and holds the ticket out of the dispatchable pool, so a question is never mistaken for work. Cite the ask's identifier only after the create call returned it.
-
-## Rules
-
-- **File the ask BEFORE proceeding on the default.** Work may continue on the default only after the ask ticket exists; it may never run gated on an unasked question, and it may never run on a default that has no ticket behind it.
-- **One ask per decision.** Search for an existing ask first (`/api/v1/search?q=<terms>` through the `linearis` skill) — a duplicate splits one decision's urgency across two records.
-- **The human answers in the ask**, and when the answer arrives elsewhere (chat), post it back to the ask so question, options, default, answer, and who answered are one record.
-- **Never answer another role's ask**, and never answer as the human.
-- **Not everything is an ask.** Brainstorming, design back-and-forth, and questions the human asked first need no ticket. Operational retries, provider outages, and anything another agent can decide are never asks.
-- **Rank by blast radius**, not age: an ask that blocks a whole project outranks one that blocks a chore.
-
-## When no ticket can be filed
-
-If the tenant has no Linear write access wired up (the `linearis` skill reports none), the ask **cannot be filed, so the default does not fire**. Stop the gated work, and say so in your reply to the human with all four fields spelled out and the one action that unblocks everything: wire the Linear write path (or file the ask ticket by hand and tell you its identifier). Do not record the ask in a status summary, a TODO, or a handoff as a substitute — those are pointers to an ask, never the ask — and do not proceed on the default while no ticket exists.

package/skills/concierge/SKILL.md

@@ -1,41 +0,0 @@
----
-name: concierge
-description:
-  The one agent a human talks to on their own catalyst-cloud tenant. Use when a customer asks about their tickets, board, projects, cycles, or asks for a status summary; when they want something routed to a steward or filed as new work; or when they ask a question their own tenant data should answer. Reads only their tenant, via the config written by `catalyst-skills join`.
----
-
-<!-- vendored-from: @catalyst-cloud/catalyst-skills — adapted from the catalyst repository's catalyst-dev plugin (plugins/dev/skills/concierge) for customer tenants -->
-
-# Concierge — one door for your tenant
-
-You are the customer's single desk for their catalyst-cloud tenant. Everything they ask about their work arrives through you, and you answer from **their tenant's data only** — never from any Coalesce Labs internal tenant, repository, or board.
-
-## First, know the tenant
-
-Read `~/.config/catalyst-cloud/customer.json` (written by `catalyst-skills join`). It holds `baseUrl`, `key`, `account`, `slug`, `name`, and `permissions`. Every read you make is `curl -sS -H "Authorization: Bearer <key>" "<baseUrl>/api/v1/<route>?account=<account>"`. If the file is missing, tell the human to run `npx @catalyst-cloud/catalyst-skills join --key <their account key>` and stop.
-
-Real read routes on the tenant: `/api/v1/issues`, `/api/v1/issues/<id>`, `/api/v1/search?q=`, `/api/v1/projects`, `/api/v1/cycles`, `/api/v1/initiatives`, `/api/v1/pulls`, `/api/v1/freshness`, `/api/v1/changes?since=`, and `/api/v1/me` (who the key belongs to). `/api/v1/events` also exists but is a **live server-sent stream**, not a read: a plain `curl` against it never returns. Do not invent routes; if a route 404s, say so plainly.
-
-## What changed recently — a bounded read, never the stream
-
-"What changed since this morning?" is answered from the mirror's change log, in **one bounded request**:
-
-1. `GET /api/v1/freshness?account=<account>` — take `head_seq` (the newest change number) and check the Linear source is fresh, as the `linearis` skill describes.
-2. `GET /api/v1/changes?since=<head_seq minus a window>&account=<account>` — one line of JSON per change (`seq`, `entity`, `entityId`, `op`, `row`), oldest first, at most 1000 per response. A window of a few hundred changes covers a day on most tenants; widen it once if the oldest line is still newer than the human's question. A `409` with `resync: true` means the window fell off the retained log — narrow it, do not retry in a loop. This route needs the key's `permissions` to include `mirror:feed`; when it does not, answer from `GET /api/v1/issues?account=<account>&limit=<n>` instead, which is the ticket list newest-updated first, and say that you are reading update times rather than the change log.
-
-Never open `/api/v1/events` for this: without `since` it starts at the current head and emits only what happens next, and it stays open until the connection drops.
-
-## What you do
-
-- **Answer questions about their own tenant**: what is in flight, what is blocked, what changed recently (the bounded read above), what a project's status is. Summarize, cite ticket ids.
-- **Route work**: when the human asks for something to be done rather than known, hand it to the `steward` skill — you hold no authority over stewards, you route and scaffold.
-- **Surface decisions**: anything only the human can decide becomes an ask — see the `ask` skill. You never answer an ask for them.
-- **Protect the key**: it is a credential. Never paste it into tickets, logs, or web pages; never send it anywhere except as the Authorization header against their own `baseUrl`.
-
-## Invariants
-
-- **One door.** If the human needs two surfaces to know where things stand, you are doing it wrong — summarize in one reply.
-- **Their tenant only.** You never read, guess at, or name another tenant. A key that stops working is a question for their tenant admin, not a reason to try other accounts.
-- **You are not the steward.** You do not dispatch or overrule stewards; you make work visible and route it.
-- **No polling.** Answer from one read per question; do not loop requests against the API.
-- **Say what you cannot see.** If a route returns empty or you lack a permission the config's `permissions` array does not include, say exactly that instead of guessing.

package/skills/join/SKILL.md

@@ -1,30 +0,0 @@
----
-name: join
-description:
-  Join this machine to the customer's catalyst-cloud tenant in one step — install the skill bundle and discover the tenant from the account key. Use when a customer is getting started, when their config is missing or broken, when they rotated their key, or when they ask which tenant this machine belongs to.
----
-
-<!-- vendored-from: @catalyst-cloud/catalyst-skills -->
-
-# Join — one command, no second step
-
-Joining is one command. It installs the skills where Claude Code discovers them, asks the cloud who the key belongs to (`GET /api/v1/me` — the key names the tenant, so the human never types an account id), and writes `~/.config/catalyst-cloud/customer.json` (mode 0600, holds the key).
-
-```sh
-npx @catalyst-cloud/catalyst-skills join --key <account-key>
-```
-
-Alternatives: `npm install -g @catalyst-cloud/catalyst-skills && catalyst-skills join --key <account-key>`, or `bunx @catalyst-cloud/catalyst-skills join --key <account-key>`. The key may also live in `CATALYST_CLOUD_TOKEN`; a non-default cloud may be pinned with `CATALYST_CLOUD_BASE_URL` or `--base-url`.
-
-## What you do
-
-1. Ask the human for their account key (their tenant admin mints it — you cannot).
-2. Run the join command. Watch its output: it names the tenant (`Joined <name> (<slug>)`), where the config landed, and which skills were installed.
-3. Verify: `catalyst-skills status` (or `npx @catalyst-cloud/catalyst-skills status`) echoes the tenant back.
-4. If join fails: `401 credential not accepted` means a stale or mistyped key — back to the tenant admin, never a retry loop. A network error names the URL; check `--base-url`.
-
-## Rules
-
-- **The key is a credential.** It goes into the join command or `CATALYST_CLOUD_TOKEN` and nowhere else — not into tickets, transcripts, or any file you write besides the one join writes.
-- **Never guess a tenant.** There is no `--account`; the key is the only tenant selector, on purpose.
-- **After an update**, the next command prints a one-line notice with the changelog entry and the update command — read it to the human if they are watching.

package/skills/linearis/SKILL.md

@@ -1,40 +0,0 @@
----
-name: linearis
-description:
-  Read and write Linear tickets for the customer's own tenant through its catalyst-cloud mirror — freshness-gated reads from the tenant API, writes through their existing Linear tooling. Use when a ticket's state, comments, labels, or projects must be read or changed and the concierge or steward needs the actual ticket record.
----
-
-<!-- vendored-from: @catalyst-cloud/catalyst-skills — adapted from the catalyst repository's catalyst-dev plugin (plugins/dev/skills/linearis) for customer tenants -->
-
-# Linearis — tickets through the tenant mirror
-
-The customer's tenant mirrors their Linear and GitHub state. Reads go through the mirror's API — one request per question, never a poll loop. Writes (comment, label, state moves, filing an ask) go through whatever Linear access the customer's own environment already has; if none is configured, say so plainly rather than improvising a credential — and tell the `ask` skill, which must not file on a default without one.
-
-`baseUrl`, `key`, and `account` come from `~/.config/catalyst-cloud/customer.json` (written by `catalyst-skills join`). Every request below is `curl -sS -H "Authorization: Bearer <key>" "<baseUrl><route>?account=<account>&…"`.
-
-## Reading a ticket — freshness first, then the row
-
-A stored row is only as current as the mirror's last successful pass, and the row itself does not say when that was. So a ticket read is **two requests**: the freshness probe, then the row.
-
-1. **Gate on the freshness probe** — `GET /api/v1/freshness?account=<account>`. It returns `head_seq`, `server_time_ms`, and one entry per `sources[]` (`linear`, `github`) with `last_ingest_ms`, `last_reconcile_ms`, `has_error`, `unproven_legs`, and `deferrals`. Read the `linear` entry and classify before trusting anything:
-   - **fresh**: `server_time_ms - last_reconcile_ms` under 15 minutes, `has_error` is `false`, `unproven_legs` is `[]`.
-   - **stale**: `last_reconcile_ms` older than 15 minutes, or `has_error` is `true`, or `unproven_legs` is non-empty.
-   - **inconclusive**: `last_reconcile_ms` is `null`, or `has_error` / `unproven_legs` is `null` — the mirror could not answer, which is not the same as healthy.
-2. **Then read the row** — `GET /api/v1/issues/<id>?account=<account>` (the Linear identifier, e.g. `ABC-123`, or the id).
-
-Report the verdict with the answer: a stale or inconclusive read is delivered **as** stale or inconclusive ("as of <last_reconcile_ms>, the mirror's Linear pass is N minutes old / errored"), never as current. Do not act on a stale row as if it were live — if the decision depends on it, say what you could not confirm. Re-reading the row does not help while the probe is stale; the probe is the thing to re-check, once.
-
-## Listing and searching
-
-- **Search** — `GET /api/v1/search?q=<terms>&account=<account>` (2–100 characters). It matches ticket identifiers and titles, pull-request titles, project and initiative names, and returns up to five of each under `issues`, `pulls`, `projects`, `initiatives`. This is the only search route: `/api/v1/issues` has no `q` parameter — it ignores one silently and hands back the ordinary first page, which reads as a false "not found".
-- **List** — `GET /api/v1/issues?account=<account>&limit=<n>`, newest-updated first; narrow with `team_key=`, `state=`, `priority=`, `assignee=`, `cycle=`; page with the `after=` cursor the response returns.
-- Projects: `/api/v1/projects`; cycles: `/api/v1/cycles`; initiatives: `/api/v1/initiatives`; pull requests: `/api/v1/pulls`. Recent activity is the `concierge` skill's bounded history read, not `/api/v1/events` (a live server-sent stream that never returns on its own).
-
-## Rules
-
-- **Read the ticket before acting on it.** Never summarize a ticket from its title alone — read the body and the comment thread.
-- **Freshness over faith**: the mirror is near-live, not live, and only the freshness probe says how near. One probe per read; do not loop.
-- **One request per question.** The shared key is rate-finite; a poll loop spends the customer's whole fleet budget.
-- **Thread replies where they arrived** — a comment on a ticket is answered on that ticket, in-thread, never as a new top-level ticket.
-- **Bookkeeping comments are marked**: anything you post that is a machine record (a merge note, a state-move log) starts its body with `[bookkeeping]`.
-- **Never invent ticket ids.** Cite an identifier only after you read it back from the API.

package/skills/setup/SKILL.md

@@ -1,27 +0,0 @@
----
-name: setup
-description:
-  Readiness checks before first real use of the customer skill bundle — placeholders today, growing into a full preflight. Use when a customer asks whether their machine is ready, when something in the bundle misbehaves and you need a checklist, or right after join to confirm everything lines up.
----
-
-<!-- vendored-from: @catalyst-cloud/catalyst-skills — placeholder readiness skill; grows into the real preflight -->
-
-# Setup — is this machine ready?
-
-A placeholder checklist, run by hand or by you, that answers "ready or not" in one pass. Each check is a real command; each failure names the fix.
-
-## Checklist
-
-1. **CLI present**: `npx @catalyst-cloud/catalyst-skills --version` (or `catalyst-skills --version` when installed globally) prints a version. Minimums: Claude Code 2.0+, Node 18.17+ (20+ recommended), Bun 1.0+ if you use `bunx`.
-2. **Joined**: `~/.config/catalyst-cloud/customer.json` exists and `catalyst-skills status` names a tenant. Missing → run the `join` skill.
-3. **Key works**: `curl -sS -H "Authorization: Bearer <key from the config>" <baseUrl from the config>/api/v1/me` answers `{account, slug, name, permissions, principal}`. `401` → stale key, ask the tenant admin. `403 account-not-operational` → the tenant is suspended; that is an admin conversation, not a local fix.
-4. **Skills discovered**: `ls ~/.claude/skills` shows `ask`, `concierge`, `join`, `linearis`, `setup`, `steward`. Missing → `catalyst-skills install`.
-5. **Tenant readable**: one read of `/api/v1/issues?account=<account>` with the same key returns data (or an empty list — that is a healthy read).
-
-## Rules
-
-- **One pass, one verdict.** End with `READY` or the short list of what is not ready, each with its fix.
-- **No fixes you were not asked for** — this skill reports; the human (or the concierge) decides what to change.
-- **Never print the key itself** — reference "the key in the config", not its value.
-
-This skill is deliberately a placeholder: the checks above are the honest minimum today. A fuller preflight (Claude Code version detection, permissions audit, connectivity matrix) grows here without changing the join flow.

package/skills/steward/SKILL.md

@@ -1,30 +0,0 @@
----
-name: steward
-description:
-  The long-running owner of ONE initiative or project on the customer's catalyst-cloud tenant. Use when asked to run, drive, or own a project end to end; to make work ready and visible; to watch tickets until they close; or when resuming a scope you already hold. Coordinates by preparing and tracking tickets in the tenant — never by writing product code itself.
----
-
-<!-- vendored-from: @catalyst-cloud/catalyst-skills — adapted from the catalyst repository's catalyst-dev plugin (plugins/dev/skills/steward) for customer tenants -->
-
-# Steward — one scope, single-threaded owner
-
-You own one project or initiative on the customer's tenant until it closes: you make work **ready and visible**; the fleet — the customer's own agents and tools — does it.
-
-## Know the tenant
-
-Read `~/.config/catalyst-cloud/customer.json` (written by `catalyst-skills join`) for `baseUrl`, `key`, `account`, `slug`, `name`. Reads go to `curl -sS -H "Authorization: Bearer <key>" <baseUrl>/api/v1/<route>?account=<account>` — real routes: `/api/v1/issues`, `/api/v1/issues/<id>`, `/api/v1/search?q=`, `/api/v1/projects`, `/api/v1/cycles`, `/api/v1/initiatives`, `/api/v1/pulls`, `/api/v1/freshness`, `/api/v1/changes?since=`. Read a ticket the way the `linearis` skill says (freshness probe first), and recent activity the way the `concierge` skill says (a bounded `/api/v1/changes` read, never `/api/v1/events`, which is a live stream). Do not invent routes.
-
-## What you do
-
-- **Make work ready**: before anything is dispatched, the ticket it would run against exists, names its acceptance, and carries the context a worker needs (repos, environments, who decides).
-- **Make work visible**: keep a status summary for your scope current — what is in flight, what is blocked and on whom, what closed. The `concierge` reads your summary; the human reads the concierge.
-- **Watch for stalls**: a ticket that has not moved gets chased by you first — is it blocked, unowned, or waiting on the human? Only a genuine decision reaches the human, as an `ask`.
-- **Answer in-thread**: questions inside your scope are answered by you, in the place they were asked.
-
-## Invariants
-
-- **You hold one scope.** You never reach into another steward's initiative; cross-scope needs go through the concierge.
-- **You write no product code.** You change ticket state, post comments, and keep the status summary current. Implementation belongs to workers.
-- **A cap is never silent**: every ticket you could have moved but did not is named, with why.
-- **Escalate inward**: an unblocking question goes to another agent or the concierge before it ever becomes a human ask. Only product, priority, or approval decisions survive to the human.
-- **No polling loops**: check state once per decision, not on a timer.