@catalyst-cloud/cli 0.9.5 → 0.13.1

package/skills/what-this-repo-needs/scripts/check.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// check.mjs — validates a catalyst.env.json file offline, with the same rules this bundle vendors
+// from the cloud's own validator. Never reads or prints a value. Offline: no login, no network —
+// wraps `catalyst env check`.
+import { runCliOffline } from "./lib/cli.mjs";
+
+const HELP = `Usage: node scripts/check.mjs <file> [--json]
+
+Validates a catalyst.env.json file against this bundle's offline copy of the cloud's rules. Prints
+"valid" or the refusal reasons — never a value. Exit 0 valid, 1 invalid or unreadable.
+
+--json prints {state, errors}. This is a local, offline check: no login, no network required.`;
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(HELP);
+  process.exit(0);
+}
+const json = args.includes("--json");
+const file = args.find((a) => a !== "--json");
+if (!file) {
+  console.error("env check needs a file: node scripts/check.mjs <path to catalyst.env.json>");
+  console.log(HELP);
+  process.exit(1);
+}
+
+const res = runCliOffline(["env", "check", file, ...(json ? ["--json"] : [])]);
+if (res.stdout) process.stdout.write(res.stdout);
+if (res.stderr) process.stderr.write(res.stderr);
+await finish(res.code);
+
+/**
+ * ⛔ NEVER `process.exit(code)` STRAIGHT AFTER A WRITE — the same rule `bin/launch.js`
+ * states in full, reintroduced here at validate attempt 29 (M-3). When this script's own stdout is a
+ * PIPE — which is how an agent harness runs it — writes are asynchronous, so `process.exit` severs
+ * whatever is still in flight AND STILL REPORTS THE ORIGINAL EXIT CODE. Measured: a `--json` body of
+ * 385,633 bytes arrived as 65,536 bytes of invalid JSON at exit 0. Writing to a FILE hides it,
+ * because a file gives stdout a synchronous write path.
+ *
+ * So: park the code on `process.exitCode`, wait for both streams to drain, and only then exit.
+ */
+function drained(stream) {
+  return new Promise((resolve) => {
+    if (!stream || stream.destroyed || stream.writableEnded) return resolve();
+    let settled = false;
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+    stream.once("error", done);
+    try {
+      stream.write("", done);
+    } catch {
+      done();
+    }
+  });
+}
+
+async function finish(code) {
+  process.exitCode = code;
+  await Promise.all([drained(process.stdout), drained(process.stderr)]);
+  process.exit(code);
+}

package/skills/what-this-repo-needs/scripts/inventory.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// inventory.mjs — lists the environment variable NAMES this repository needs, grouped build/test,
+// deploy-only and bindings, each with where it was found, what uses it, and where a local value
+// would come from. Never reads or prints a value. Offline: no login, no network — wraps
+// `catalyst env inventory`.
+import { runCliOffline } from "./lib/cli.mjs";
+
+const HELP = `Usage: node scripts/inventory.mjs [path] [--json]
+
+Scans a repository (default: the current directory) for the environment variable names it needs and
+prints them in three groups: build/test, deploy-only, bindings. For each name: where it was found
+(file:line), what uses it, and where a local value would come from. Never reads or prints a value.
+
+--json prints the same data as JSON. This is a local, offline scan: no login, no network required.`;
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  console.log(HELP);
+  process.exit(0);
+}
+const json = args.includes("--json");
+const path = args.find((a) => a !== "--json") ?? ".";
+
+const res = runCliOffline(["env", "inventory", path, ...(json ? ["--json"] : [])]);
+if (res.stdout) process.stdout.write(res.stdout);
+if (res.stderr) process.stderr.write(res.stderr);
+await finish(res.code);
+
+/**
+ * ⛔ NEVER `process.exit(code)` STRAIGHT AFTER A WRITE — the same rule `bin/launch.js`
+ * states in full, reintroduced here at validate attempt 29 (M-3). When this script's own stdout is a
+ * PIPE — which is how an agent harness runs it — writes are asynchronous, so `process.exit` severs
+ * whatever is still in flight AND STILL REPORTS THE ORIGINAL EXIT CODE. Measured: a `--json` body of
+ * 385,633 bytes arrived as 65,536 bytes of invalid JSON at exit 0. Writing to a FILE hides it,
+ * because a file gives stdout a synchronous write path.
+ *
+ * So: park the code on `process.exitCode`, wait for both streams to drain, and only then exit.
+ */
+function drained(stream) {
+  return new Promise((resolve) => {
+    if (!stream || stream.destroyed || stream.writableEnded) return resolve();
+    let settled = false;
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+    stream.once("error", done);
+    try {
+      stream.write("", done);
+    } catch {
+      done();
+    }
+  });
+}
+
+async function finish(code) {
+  process.exitCode = code;
+  await Promise.all([drained(process.stdout), drained(process.stderr)]);
+  process.exit(code);
+}

package/skills/{catalyst-setup → what-this-repo-needs}/scripts/lib/cli.mjs

@@ -1,16 +1,18 @@
 #!/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
+// catalyst CLI this bundle installed. It reads customer.json to find that CLI and nothing
 // else; it never holds the 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).
+// --help for usage. Per-skill (skills install one directory at a time, so nothing shared outside the
+// skill would ever be installed) — see runCliOffline below for the one way this skill's copy differs.
 import { spawnSync } 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 = "@catalyst-cloud/catalyst-skills";
+export const PACKAGE = "@catalyst-cloud/cli";
+/** The package ships two commands, so npx needs the one to run named: `npx -p <package> catalyst`. */
+export const NPX_ARGS = ["-p", PACKAGE, "catalyst"];
 export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: ${CONNECT_COMMAND}`;
 
 /** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME before HOME. */
@@ -41,15 +43,38 @@ export function requireCustomerConfig() {
 }
 
 /**
- * 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
+ * Run one catalyst verb and return {code, stdout, stderr}. Spawns the CLI whose path the
+ * connect step recorded in customer.json; falls back to `npx -p @catalyst-cloud/cli catalyst` 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);
+  return spawnCli(cfg, args, opts);
+}
+
+/**
+ * Run `catalyst env inventory` / `env check` without requiring a credential at all. Unlike
+ * every other verb this launcher can reach, `env inventory` and `env check` are LOCAL and OFFLINE —
+ * they never call the cloud — so gating them on `requireCustomerConfig` would break the feature they
+ * exist to provide. Still resolves the recorded `cliPath` when a customer.json happens to exist (so
+ * an already-connected machine reuses the same installed CLI), and still falls back to
+ * `npx -p @catalyst-cloud/cli catalyst` otherwise.
+ */
+export function runCliOffline(args, opts = {}) {
+  let cfg = null;
+  try {
+    const path = configPath();
+    if (existsSync(path)) cfg = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    cfg = null;
+  }
+  return spawnCli(cfg, args, opts);
+}
+
+function spawnCli(cfg, args, opts) {
+  const recorded = Boolean(cfg) && 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 argv = recorded ? [cfg.cliPath, ...args] : [...NPX_ARGS, ...args];
   const res = spawnSync(command, argv, {
     encoding: "utf8",
     input: opts.stdin,
@@ -58,7 +83,7 @@ export function runCli(args, opts = {}) {
     shell: !recorded && process.platform === "win32",
   });
   if (res.error) {
-    console.error(`could not run ${recorded ? cfg.cliPath : `npx ${PACKAGE}`}: ${res.error.message}`);
+    console.error(`could not run ${recorded ? cfg.cliPath : `npx -p ${PACKAGE} catalyst`}: ${res.error.message}`);
     process.exit(2);
   }
   return { code: res.status ?? 1, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
@@ -72,7 +97,7 @@ export function runCli(args, opts = {}) {
 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}`;
+  const why = res.stderr.trim() || res.stdout.trim() || `catalyst ${args.join(" ")} exited ${res.code}`;
   console.error(why);
   process.exit(res.code === 2 ? 2 : 1);
 }
@@ -86,18 +111,6 @@ export function parseJson(stdout) {
   }
 }
 
-/** 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 → what-this-repo-needs}/scripts/lib/credential.mjs

@@ -6,12 +6,12 @@
 //
 // 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
+// catalyst 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)";
+  "npx -p @catalyst-cloud/cli catalyst login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx -p @catalyst-cloud/cli catalyst login)";
 
 /** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
 export function hasCredential(cfg) {

package/skills/whats-happening/SKILL.md

@@ -1,43 +1,49 @@
 ---
 name: whats-happening
 description: >-
-  The desk for a Catalyst Cloud tenant. Use when the person asks "what's happening?", "where are we?", "why is that stuck?", "what closed?", "what's next?", or asks for something to be done rather than known. Reads the tenant contract, what is running and queued, the eligibility explainer and the open asks through the catalyst-skills CLI, and answers in one reply with ticket ids. Routes work to a project owner and decisions to what-needs-me. Never composes a URL, never polls, never answers as the human.
-allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
+  The desk for a Catalyst Cloud account, and the facts behind it. Use when the person asks "what's happening?", "where are we?", "why is that stuck?", "what closed?", "what's next?", "how does this work?", "why did it do that?", "how does it prioritise?" or "what does this setting do, where is it set?", or asks for something to be done rather than known. Reads the contract, what is running and queued, the eligibility explainer, the coding accounts and the open asks through the catalyst CLI, and answers in one reply with ticket ids. Explains the ladder, the stage map, failures, parks and holds, the queue order and every reason a ticket is excluded. Routes work to a project owner and decisions to what-needs-me. Read-only: never composes a URL, never polls, never answers as the human.
+allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.5 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.1 — written in this repository for customer accounts -->
 
 # What's happening
 
-You are the one desk the person talks to about their Catalyst Cloud tenant. They ask four questions: where are we, why is that stuck, what closed, what is next. You answer each in one reply, from their tenant's data only, with a ticket identifier on every line. When they ask for something to be done, you route it to an owner; when only they can decide something, you raise it through `what-needs-me`.
+You are the one desk the person talks to about their Catalyst Cloud account: where things stand, why something is stuck, what closed, what is next, and how Catalyst works. Answer each in one reply from their own account's data.
+
+Every account-specific fact (stage names and ids, labels, the ladder keying, thresholds, merge policy) comes from the contract, `GET /api/v1/agent/contract`; the references hold only what is the same for every account.
 
 ## Run first
 
-Scripts are run, never read. Each prints `--help`; exit 2 means this machine is not connected (run the `connect-me` skill), exit 1 means the check itself failed.
+Scripts are run, never read; each prints `--help`. Exit 2 means this machine is not connected (`catalyst-onboard`), exit 1 that the check itself failed.
 
-- `node scripts/snapshot.mjs --help` — one JSON document: the trimmed contract (teams, stage names by slot, thresholds, ladder), what is running, the queue, the open asks ranked by what they hold, and the replica verdict. Add `--board` for open tickets grouped by stage in the contract's slot order, `--team K` to narrow.
-- `node scripts/explain.mjs --help` — why nothing is offered for one ticket, in one paragraph.
+- `node scripts/snapshot.mjs`: the trimmed contract, what is running, the queue, the ranked open asks, and the replica verdict. `--board` adds open tickets by stage, `--accounts` the coding accounts, `--team K` narrows.
+- `node scripts/explain.mjs <ticket>`: why one ticket is or is not about to run. `--history` adds attempts, rounds, holds and past releases.
+- `node scripts/show-my-map.mjs [--team K]`: this account's slot-to-stage map, labels, ladder and live thresholds.
 
-For a single ticket's comments, relations and linked PRs use the `catalyst-linear` skill (`catalyst-skills query issue <id>`); for a pull request's checks and threads, `catalyst-github`.
+One ticket's comments and relations are the `catalyst-linear` skill; a pull request's checks and threads, `catalyst-github`; readiness ("am I set up?"), `catalyst-onboard`.
 
 ## Load on demand
 
 | when | read |
 | -- | -- |
-| writing any status answer | `references/status-reply.md` (schema: `assets/status-reply.json`) |
-| the board looks wrong, a column is long, or you must decide whether something is stuck | `references/reading-the-board.md` |
+| writing any status answer, or deciding whether something is stuck | `references/status-reply.md` (schema: `assets/status-reply.json`) |
 | `explain` returned a reason and the person wants the next action | `references/why-is-it-stuck.md` |
-| "do this one first", "why is that not next", "stop that" | `references/reprioritising.md` |
+| "what runs next?", "do this one first", the WIP limit, capacity, routing | `references/what-runs-next.md` |
+| a phase failed, a card went to Remediate, a ticket is parked or on hold | `references/when-a-phase-fails.md` |
 | the person asks for work to be done, or a decision surfaces | `references/routing-work.md` |
-
-For depth beyond these, load the fact skills: `how-catalyst-works` (the ladder, slots and mapping, failure layers, queue order, coding accounts), `catalyst-linear` (what a ticket accumulates, reading and writing), `catalyst-github` (what a PR accumulates, mergeability), `catalyst-setup` (readiness).
+| "what is Catalyst Cloud?", the phases, what each produces, when a ticket is Done | `references/the-ladder.md` |
+| "which column is which, why does nothing dispatch, what is a slot?" | `references/stages-and-mapping.md` |
+| "why is nothing running", walls, quarantine, which provider ran a phase | `references/coding-accounts.md` |
+| "what does this setting do, where is it set, who can change it?" | `references/settings-and-where-they-live.md` |
 
 ## Rules
 
-- **Their tenant, as them.** Every read goes through the CLI, which holds the person's own key, the tenant and who they are. You never name, guess at, or try another tenant, and you never paste the key anywhere. "You" in your reply means the connected person: their assigned tickets, their asks.
-- **Tenant facts come from the contract, live.** Stage names, label names, team keys, thresholds and the ladder are in the snapshot's `tenant` block; read them there each time and never restate them from memory.
-- **One reply, ticket ids on every line, source named.** The reply opens with when the snapshot was taken and whether the replica or the API answered. A stale replica is stated, never hidden.
-- **Say what a key cannot see.** PR labels and reactions are not mirrored; the CLI prints the settings URL, and you repeat it instead of guessing. A park or hold is released from the person's own login once its cause is fixed: route that to the `unstick` skill (`catalyst-skills release`), never tell them it needs an operator. Coding-account status (`accounts`) and per-ticket execution history (`explain --history`) are readable — read them.
-- **No polling.** One snapshot per question. Waiting on a change is the project owner's job (`run-this-project` subscribes to the tenant stream); the desk never loops a read.
-- **You are not the owner.** You route work and make it visible; you do not dispatch, overrule a project owner, or run long work in this session.
-- **Never answer as the human.** A decision is an ask through `what-needs-me`, filed before anyone proceeds on its default; the answer is recorded there as the app actor.
-- **Cite an identifier only after a create call returned it.**
+- **Their account, as them.** Every read goes through the CLI with the person's own login; "you" in a reply means the connected person.
+- **Print, never recall.** A stage name, label, threshold or route in your answer comes from a script's output in this session. A settings answer names the screen, its route and the rule from `references/settings-and-where-they-live.md`.
+- **One reply, ticket ids on every line, source named** (`references/status-reply.md`).
+- **A reason is a row** in `references/why-is-it-stuck.md`: name what releases it and who can. Unknown is not absent; report it as inconclusive.
+- **Parks and holds have their own release.** Once the cause is fixed, the person's own login releases a park, a no-change hold or a validate-budget hold through the `unstick` skill (`catalyst release`). A round-threshold hold and a review that will not converge refuse that release; `references/when-a-phase-fails.md` says what clears each.
+- **Say what a key cannot see.** PR labels and reactions are not mirrored; repeat the settings URL the CLI prints. Coding accounts and execution history are readable, so read them.
+- **System causes are one alert.** A provider outage, the runner image breaker or a paused repository is said once, for every ticket it holds.
+- **One snapshot per question.** Waiting on a change is the project owner's job (`run-this-project` subscribes to the stream).
+- **You route; the owner acts** (`references/routing-work.md`). The human answers for themselves: a decision is an ask through `what-needs-me`, filed before anyone proceeds on its default.

package/skills/whats-happening/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "What's happening"
-  short_description: "Where your Catalyst work stands: in flight, blocked and on whom, closed, and what runs next"
+  short_description: "Where your Catalyst work stands and how Catalyst decides: in flight, blocked and on whom, closed, what runs next, and why"
   default_prompt: "Use $whats-happening to tell me where my work stands and why anything is stuck."
 policy:
   allow_implicit_invocation: true

package/skills/whats-happening/references/coding-accounts.md

@@ -0,0 +1,24 @@
+# Coding accounts: slots, windows, walls
+
+The person's own rows print with `node scripts/snapshot.mjs --accounts`, with no credential or email. An owner or admin enrols, pauses or removes one at `<their cloud>/settings/coding-accounts`.
+
+## Slots and providers
+
+A slot is one enrolled credential that runs phases; identity is the credential, so one email may hold several. Claude, GLM and Qwen run under the Claude CLI, Codex under Codex, and GLM and Qwen also under OpenCode. The routing rows (`references/what-runs-next.md`), not the harness, name the model.
+
+## State
+
+- **Declared:** `active` or `disabled`, set by the operator.
+- **Observed:** `healthy`, `degraded` or `unknown`, set by the poller (every 5 minutes for an active slot, daily for a disabled one).
+- **Quarantined:** system-set on a credential conflict or an authentication mismatch. Replace credential on the account's page clears it, and a workspace owner or admin can do that.
+
+## Windows and walls
+
+Subscriptions meter usage over a **5-hour** and a **7-day** window. A **wall** is the limit a session can die at mid-run, so a slot whose remaining headroom cannot fit the phase's projected burn is not offered. A Claude slot serves several phases at once up to a cap; a Codex slot serves one, because its refresh tokens are single-use. Vendor status pages say nothing about the person's own windows.
+
+## "Why is nothing running?"
+
+1. `node scripts/explain.mjs <ticket>`: `routing_unavailable` naming a slot or provider, or `no_eligible_account_slot` in the routing block, points at accounts.
+2. `node scripts/snapshot.mjs --accounts`: an empty list means none is enrolled; a wall is the `walled` field, a quarantine `quarantined` with its reason. Read them; silence proves nothing.
+3. Report it as one fleet-level cause for every ticket it holds.
+

package/skills/whats-happening/references/routing-work.md

@@ -1,36 +1,18 @@
 # Routing work
 
-This reference restates an invariant: what this skill does when the person asks for something to be done rather than known, and where a decision goes. Nothing here is tenant-specific.
+Your first sentence says which of three things the message is:
 
-## Three kinds of request
+1. **A question** ("where is X, why is Y stuck, what closed?"): answer it in the one-reply shape (`references/status-reply.md`).
+2. **A request for work** ("get X done, own this until it closes"): turn it into a project with an owner, in one pass, as below.
+3. **A decision only they can make**: raise it through `what-needs-me` before anyone proceeds on the default. `what-needs-me` owns what is and is not an ask.
 
-A message from the person is one of three things, and you decide which in the first sentence of your reply:
+A request containing a decision is both; do and say both.
 
-1. **A question.** "Where is X? Why is Y stuck? What closed today?" Answer it in the one-reply shape (`references/status-reply.md`). No routing.
-2. **A request for work.** "Get X done. Ship the Y change. Own this until it closes." Turn it into a project with an owner, in one pass, as below.
-3. **A decision only they can make**, surfaced by you or by the cloud. That is never answered here; it goes to `what-needs-me`.
+## A request becomes a project with an owner
 
-A request that contains a decision is both: route the work and raise the decision, and say in the reply that you did both.
+1. **Find the existing home** with `catalyst query projects` and `catalyst query search <terms>`. A request that fits an open project is a ticket there, never a duplicate project.
+2. **Scaffold when there is none:** the outcome in a sentence, the first ticket or two (through `catalyst-linear`), and the owner. The person creates a project in Linear; name it for them.
+3. **Name the owner:** a `run-this-project` session for that project, or a person. Give the one command that starts the owner session; long-running work belongs there, not at the desk.
+4. **Say what you did:** the identifiers created, the owner, and the next thing the person will see. Cite an identifier only after the create call returned it; a guessed number is usually a real, unrelated ticket.
 
-## A request becomes a project with an owner, in one pass
-
-You hold no authority over project owners. Your job is to make the work visible and hand it to a single-threaded owner, then get out of the way.
-
-1. **Find the existing home first.** `catalyst-skills query projects` and `query search <terms>`. A request that fits an open project is a ticket in that project, not a new project. Duplicate projects split one goal's status across two places.
-2. **Scaffold when there is no home.** State the outcome in one sentence, the first ticket or two, and who owns it. Tickets are created through the `catalyst-linear` skill (the app actor, the team key from the contract); a project itself is created by the person in Linear, so name what you want it called and ask them to create it if none fits.
-3. **Name the owner.** The owner is a `run-this-project` session for that project, or a person. Say which, in the reply. Tell the person the one command that starts the owner session, and do not start long-running work inside this session: the desk answers questions; the owner reacts to events.
-4. **Say what you did.** The reply ends with the identifiers created, the owner named, and the next thing the person will see.
-
-Cite an identifier only after the create call returned it. A guessed number is usually a real, unrelated ticket.
-
-## What goes to what-needs-me
-
-Anything that gates active work on a choice only the human can make: a product call, a priority call between two things that cannot both go first, an approval, or an action only they can physically take (a click in settings, a credential). It is raised as an ask through the `what-needs-me` skill with the question, the options, the default that fires if they stay silent, and what it blocks, and it is raised **before** anyone proceeds on the default.
-
-Not an ask: brainstorming, a design back-and-forth, a question the person asked first, a retry-or-abandon call an owner can make, a provider outage (that is one status line, not a per-ticket question).
-
-## Three rules that bind this skill
-
-- **Never answer as the human.** You do not pick an option on an open ask, close one, or post in their voice. When their answer arrives in chat, it is recorded on the ask through `what-needs-me` so the record is complete, and it is recorded as the app actor, never as them.
-- **Escalate inward, never outward.** An instrument reports to the project owner; the owner asks the desk; the desk asks the human, as an ask. A single stuck ticket is never a page to the human. A system-level failure (provider down, out of capacity, rate-limited) is one line in the status reply, not a question per ticket.
-- **One door.** If the person needs a second place to look after your reply, add the missing block to the reply next time rather than pointing them at a dashboard.
+The human answers for themselves: pick no option on an open ask, close none, and post nothing in their voice. An answer they give in chat is recorded on the ask through `what-needs-me`, as the app actor. A system-level failure is one line in the status reply, not a question per ticket.

package/skills/whats-happening/references/settings-and-where-they-live.md

@@ -0,0 +1,20 @@
+# Settings and where they live
+
+Live values come from the contract or a script. Prefix every route with the person's own `<their cloud>`, never an invented host. Unless a row says otherwise, an owner or admin sets it.
+
+| what | where | the rule |
+| -- | -- | -- |
+| **Connecting Linear** | `<their cloud>/settings/connections` | Needs an owner or admin browser session, which also decides the account. |
+| **One workspace, one account** | `<their cloud>/settings/connections` | A Linear workspace binds to exactly one account, and the reverse; a second account for the same workspace is refused. Raise it as a decision, not a retry. |
+| **Installing the GitHub App** | `<their cloud>/settings/connections`, after `<their cloud>/settings/profile` | The admin's personal GitHub grant comes first: a refusal naming a missing GitHub identity or someone else's installation means "grant your personal GitHub first". |
+| **Uninstalling** | `<their cloud>/settings/connections` | Removing the App on GitHub self-heals the registry; unlinking in Catalyst uninstalls upstream. Neither needs support. |
+| **One team, one repository** | `<their cloud>/settings/repositories` | A Linear team maps to at most one repository per account, and a GitHub repository to at most one, case-insensitively. |
+| **Neither half can be re-pointed** | `<their cloud>/settings/repositories` | A repository is one team plus one GitHub repo; the only editable field is its name, so a monorepo across two teams cannot be modelled. |
+| **An archived repository holds both keys** | `<their cloud>/settings/repositories` | Re-registering the same team-plus-repo pair is refused until the archived entry is restored. |
+| **Merge policy** | `<their cloud>/settings/repositories/$repoId/merging` | The effective policy and its source are on the contract's `merge` block; this page changes it (`catalyst-github` only reads it). |
+| **Reviewers** | `<their cloud>/settings/repositories/$repoId/code-reviews` | "Post review requests as" names one connected member. A strict merge policy with no reviewer never earns the merge label: configure one, or change the policy. |
+| **The merge queue** | no settings page; the repository's own merge automation | The merge phase's one write is the ready label; the merge itself is whatever the repository's own setup does with it. This bundle cannot see which queue runs; say so, naming no vendor the person has not named. The GitHub repository's administrator owns it. |
+| **The runner cap** | `<their cloud>/settings/repositories` | 20 running phases per repository by default, which an operator changes; the page only displays it, and a paused repository resolves to zero. See `references/what-runs-next.md`. |
+| **Secrets and environment variables** | `<their cloud>/settings/secrets`, `<their cloud>/settings/environment`, and each repository's sections | Secrets are write-only; variables are readable. A name is one or the other, never both; a repository value wins over an account one; a variable may reference a vault secret by name, expanded only in the container. |
+| **"My secrets are not in the container"** | `<their cloud>/settings/repositories` | When a repository was registered without its team, nothing reaches a runner, and the failure is silent: a phase's build cannot find its environment. Raise the fix, an admin or operator action, as an ask. |
+| **Routing** | none: there is no settings page for this | Stage defaults are global and the per-account table is empty, so routing always resolves to the default provider. A Codex-first pipeline is not something to promise (`references/what-runs-next.md`). |

package/skills/whats-happening/references/stages-and-mapping.md

@@ -0,0 +1,25 @@
+# Stages and mapping
+
+A **slot** is Catalyst's name for a position on the board; a **stage** is the Linear workflow state a team has; the **mapping** binds each slot to one stage per team. Every team's live map is on the contract under `teams[].stages`; `node scripts/show-my-map.mjs [--team <key>]` prints it with the load-bearing slots starred.
+
+The slots, in pipeline order: `dispatch`, `intake`, `research`, `plan`, `implement`, `remediate`, `verify`, `review`, `pr`, `done`, `canceled`.
+
+## Five slots are load-bearing
+
+| slot | why it matters | allowed state types |
+| -- | -- | -- |
+| `dispatch` | moving a card here dispatches work; 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 triage type |
+| `pr` | a card must sit here for `merge` to be offered | `started` |
+| `done` | written by the merge webhook | `completed` |
+| `canceled` | terminal; never work | `canceled` |
+
+An absent or wrongly typed mapping on one of these stops the ladder silently (on the others it costs a readiness warning): until dispatch, pr, done and canceled each point at a live stage, Catalyst starts nothing in that team, and `explain` says so. `teams[].gitAutomation` is a stored consent for a feature not built yet; nothing reads it, so its value neither stops nor starts work.
+
+`teams[].workflowMode` is **adopted** (Catalyst created the stages), **mapped** (a human chose each) or **mixed**. Mappings live at `<their cloud>/settings/linear-teams`; `.catalyst/catalyst.toml` has no stage section.
+
+## The state id is the authority
+
+Only a stage's `stateId` is a lookup key, because a Linear import can keep every name while re-minting every id. Move cards by slot (`catalyst-linear` does) and let the CLI resolve the id. `stateStillExists: false` means the team needs re-mapping (`catalyst team map <KEY>`) before that slot can be written; the CLI refuses the move.
+
+Backlog is not a slot: parking a card moves it to the team's backlog-type state, which the CLI resolves from the live workflow. Readiness over the mapping, and who fixes each check, is the `catalyst-onboard` skill.

package/skills/whats-happening/references/status-reply.md

@@ -1,34 +1,34 @@
 # The one-reply shape
 
-This reference restates an invariant of this skill: how a status answer is shaped. The facts inside it come live from `node scripts/snapshot.mjs` and `node scripts/explain.mjs`; the machine-readable schema is `assets/status-reply.json`.
+One question gets one reply, complete enough that the person needs no second surface. Every line names a ticket identifier, and a fact you could not read is named as unreadable, with where it lives.
 
-## The rule
+Open with one clause: the snapshot's `takenAt` and its source (a fresh replica's cursor, or the API and why). Then the blocks, in order:
 
-The person asked one question and gets one reply. If they would need a second surface, a second message, or a follow-up question from you to know where things stand, the reply is wrong. Every line names a ticket identifier. Nothing in the reply is a guess: a fact you could not read is named as unreadable, with where it lives.
+1. **In flight.** From the snapshot's `running` block: identifier, the phase running, how long.
+2. **Blocked, and on whom.** The queue's excluded rows, with `explain` on the ones the person cares about. Every line carries the reason in the person's words and who releases it: the person, a role, the cloud itself, or a clock.
+3. **Waiting on the human.** `waitingOnHuman` in the snapshot, ranked by what each ask holds: identifier, the question, what it releases. `what-needs-me` owns the detail.
+4. **Closed.** What reached the done slot in the window asked about (`query issues` by the done-slot stage name, or the change feed); with no window read, "since my last reply".
+5. **Next.** The snapshot's `queue` block in the cloud's order, with each ticket's next phase.
+6. **Cannot see**, only when non-empty: PR labels and reactions (not mirrored), each with the URL the CLI printed. A flow number goes here by name: cycle time, throughput, or how long pull requests have been open are not computed by anything a key reads, so say they are not computed rather than counting ticket dates.
 
-## The five blocks, in this order
+## Writing the lines
 
-1. **In flight.** Tickets a phase is running on right now, or that hold a live lease mid-ladder. Source: the snapshot's `running` block (fleet activity, the agent roster, lease attributions). One line per ticket: identifier, the phase running, how long it has run.
-2. **Blocked, and on whom.** Tickets nothing is offered for. Source: the queue's excluded rows, then `explain` on each one the person cares about. Every line carries the reason in the person's words and who releases it: the human (an ask), a role, the cloud itself (a backoff, a park that self-releases), or a clock. "On whom" is never blank; if you cannot tell, say the reason the cloud gave and that the release is unknown to a key.
-3. **Waiting on the human.** The open asks, ranked by what each one holds. Source: `waitingOnHuman` in the snapshot. Keep this to identifier, the question, and what it releases; the `what-needs-me` skill owns the detail and the settling.
-4. **Closed.** What reached the done slot in the window the person asked about (or since your last reply). Source: `query issues` filtered by the team's done-slot stage name from the contract, or the change feed for a time window. When you did not read a window, say "since my last reply" and mean it.
-5. **Next.** What the queue picks up next, in the cloud's order, with the phase each will run. Source: the snapshot's `queue` block. Do not reorder it to what you think should be next; the levers are in `references/reprioritising.md`.
+- Identifier first, then the stage as the contract spells it, then one clause: `KEY-123 · <stage name> · implement running 14 min`.
+- Age in human units from `updated_at` or the lease start, judged against the phase's natural duration.
+- A reason is its translation from `references/why-is-it-stuck.md`. One ticket in flight and nothing blocked is a three-line reply.
 
-A sixth block, **cannot see**, appears only when it is non-empty: the facts your key cannot read (PR labels and reactions, which are not mirrored; an operator-only park release), each with the URL the CLI printed.
+## Reading the board
 
-## The header line
+`node scripts/snapshot.mjs --board` groups open tickets by stage in slot order; read it by slot, never by name. A long dispatch column with nothing in flight is a capacity or eligibility question: `explain` the first row. A card that has not moved is running, retrying in place, or in remediate, which is an interrupt to count separately, never progress. An ask-labelled ticket belongs in the waiting-on-human block; a local-lane ticket is in flight elsewhere. The ticket's comments (`catalyst-linear`) and `catalyst explain --history <ticket>` must agree.
 
-The reply opens with one clause that says when and from where: the snapshot's `takenAt` and its source line. When the replica was stale or absent, the reply says the numbers came from the API; when it was fresh, it says the cursor. This is not decoration. A stale source that goes unmentioned is the way a wrong status reply happens.
+## What counts as stuck
 
-## Writing the lines
+A ticket is **stuck** only when all three hold:
 
-- Identifier first, then the stage as the contract spells it for that team, then one clause. `KEY-123 · <stage name> · implement running 14 min`.
-- Age in human units (minutes, hours, days), from `updated_at` or the lease's start, never a raw timestamp.
-- A reason is the translation from `references/why-is-it-stuck.md`, not the cloud's snake_case token, unless the token is one the table does not know, in which case quote it as the cloud spelled it.
-- No adjectives about health. "Stuck" has a definition (`references/reading-the-board.md`); use it only when it applies.
+1. Nothing is offered for it: the queue excludes it, or `explain` gives a reason rather than a position.
+2. The reason does not release itself (`references/why-is-it-stuck.md` marks which do).
+3. No one is acting on the release: no open ask names it, and no human comment or push landed after the failure.
 
-## What the reply never does
+Everything else is **waiting**, and the reply says on what; calling a wait "stuck" sends the human to fix what the cloud is handling.
 
-- It never restates a stage name, threshold or label from memory. The snapshot's `tenant` block carries the live values; read them there each time.
-- It never answers an ask, proposes a default on the human's behalf inside the status reply, or moves anything. Routing a request is `references/routing-work.md`; a decision is the `what-needs-me` skill.
-- It never pads a short answer. When one ticket is in flight and nothing is blocked, the reply is three lines.
+The reply answers no ask, proposes no default for the human, and moves nothing: requests go to `references/routing-work.md`, decisions to `what-needs-me`.

package/skills/whats-happening/references/the-ladder.md

@@ -0,0 +1,30 @@
+# What Catalyst is, and the ladder
+
+## In the person's terms
+
+Use their repositories and tickets as examples. Moving a card into the team's dispatch column starts the work, and nothing else does. Each phase runs in a cloud container set up for the repository, on a coding account their workspace enrolled, and leaves a document and an outcome comment on the ticket, so the ticket is the record. Their laptop runs no coding sessions, and agents react to events rather than polling.
+
+What changes in their day: they write each ticket for a reader who cannot see their chat (an outcome title, what done looks like, a priority, no open blocker). They leave working stages and Done to Catalyst. A draft pull request appears that a later phase marks ready, and a green one with no open threads merges through the queue unless a hold label keeps it out. A decision only they can make arrives as an ask in their own Linear, with options, a silent default and what it holds. A comment they post gets an eyes reaction and a threaded reply.
+
+## The phases
+
+The contract's `ladder` block (`node scripts/show-my-map.mjs`) says whether intake is on and which keying applies.
+
+| phase | produces | notes |
+| -- | -- | -- |
+| `intake` | nothing (a classification pass) | optional, for a new ticket, when `ladder.intakeEnabled` |
+| `research` | `research.md` | offered from the dispatch slot |
+| `plan` | `plan.md` | |
+| `implement` | `implement.md` | creates the branch, named exactly the ticket identifier, and opens a draft pull request |
+| `validate` | `validation.md` | success moves the card to the review stage (verify and review share it) |
+| `pr` | `pr.md` | first line is the PR title, then the body; rebases, force-pushes, marks the PR ready |
+| `remediate` | `remediation.json` | an interrupt that repairs a failed phase; never advances past the PR slot |
+| `merge` | a receipt | applies the queue-ready label once its evidence gate passes |
+
+## What moves the card
+
+The contract's `ladder.advance` maps each completed phase to a card move; its keying decides whether a stage names the phase just finished (trailing, the default) or the one ahead (leading). A failed phase, `remediate` and `merge` move nothing (`references/when-a-phase-fails.md`).
+
+**Done is written by the merge.** GitHub's merged event moves the ticket to Done within seconds, with a sweep behind a dropped webhook, so a ticket not Done a minute after its PR merged is a finding, not a chore to hand-close. Done means merged; a separately deployed change is live only once deployed.
+
+To place a ticket, its stage says which phase last finished (`node scripts/show-my-map.mjs --team <key>` translates it) and `explain` says what runs next.

package/skills/whats-happening/references/what-runs-next.md

@@ -0,0 +1,32 @@
+# What runs next: order, capacity, routing, and the person's levers
+
+## Queue order
+
+The cloud derives each team's queue from its tickets within seconds of any board change. Cards in the dispatch slot rank by Linear **priority** (urgent first), then **created time**, then **identifier**. Tickets already **mid-ladder** join the same set and sort ahead by phases completed, so a ticket near the end goes first; that count orders, and never makes an ineligible ticket eligible.
+
+## Capacity
+
+- Each repository has a concurrency cap of 20 running phases by default, which an operator raises or lowers; the account's own settings page displays it. A paused repository resolves to zero and keeps the stored value for resuming.
+- Dispatch splits slots across teams so none starves, and comment-wake work shares the cap.
+
+## The work-in-progress limit
+
+A project (one Linear team across its repositories) at its limit starts no new ticket: its own setting, else an account-wide value an operator set, else 12. `0` holds every new start. Members read it, its source and the count with `catalyst project wip-limit get --team <KEY>`; an owner or admin runs `set <n>` (or `set default`).
+
+It holds only first phases (`explain` prints `wip_limit`, e.g. "14 tickets in progress, at or above its WIP limit of 12"); a started ticket keeps getting every later phase. In progress counts tickets, not containers: every live ticket past the dispatch column (or granted a first phase), blocked, parked and waiting ones included; never-started, backlog and local-lane tickets are not counted. A fleet idle at the limit means the tickets in progress are all waiting; unstick those (`unstick`, `catalyst-github`, `what-needs-me`).
+
+## Routing
+
+A phase about to start takes the first route that passes, in order: capability match, a configured model, the provider available, an eligible coding-account slot with headroom (when the route needs one), and resolvable parameters. With no survivor, the routing block reads `no_eligible_account_slot` when a candidate was skipped on capacity, else `routing_unavailable`. Stage defaults are global and there is no routing setting yet, so a Codex-first pipeline is not something to promise. Slots are in `references/coding-accounts.md`.
+
+## The person's levers
+
+1. **Priority on the ticket** reorders the queue: the lever for "do this one first".
+2. **The dispatch column.** Moving a card there starts work; moving it to a backlog-type state stops work, and further rounds, without cancelling. Describe the move and let the person or the project owner (`run-this-project`) make it.
+3. **Holds.** A hold label from the contract's `merge.prLabels` keeps a mergeable pull request out of the queue until removed. An ask's blocking relation holds every ticket it names. The contract's release label frees a ticket the ask-shape detector flagged by mistake.
+
+No lever interrupts a running phase. A failed phase needs no re-queueing, and moving its card by hand usually restarts its count. Priority is the fleet's order, not the person's urgency: an urgent ticket blocked on an ask still waits for the ask.
+
+## "Why is that one not next?"
+
+Run `explain` on it. A position means capacity bounds it: say how many are ahead and whether anything runs at all; if nothing runs anywhere, read the coding accounts first. A reason goes to `references/why-is-it-stuck.md`. A ticket missing from the explainer is on another team, terminal, or unknown; check the identifier.