@catalyst-cloud/cli 0.13.0 → 0.13.1

package/skills/what-this-repo-needs/SKILL.md

@@ -1,28 +1,21 @@
 ---
 name: what-this-repo-needs
 description: >-
-  What environment variable names does this repository need, and where does each one come from? Scans the repository offline (no login, no network) and lists the names in three groups — build/test, deploy-only, bindings — each with where it was found, what uses it, and where a local value would come from. Never reads or prints a value. Also validates a catalyst.env.json file the same way the cloud does. Use when someone asks "what does catalyst.env.json mean", "what env vars does this repo need", "why does the container need this", or before reviewing or writing a repository's environment declaration.
-allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
+  What environment variable names does this repository need, and where does each one come from? Scans the repository offline (no login, no network) and lists the names in three groups (build/test, deploy-only, bindings), each with where it was found, what uses it, and where a local value would come from. Never reads or prints a value. Also validates a catalyst.env.json file the same way the cloud does. Use when someone asks "what does catalyst.env.json mean", "what env vars does this repo need", "why does the container need this", or before reviewing or writing a repository's environment declaration.
+allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.1 — written in this repository for customer accounts -->
 
 # What this repository needs
 
-Say this first, in your own words, before you scan: the fleet builds and tests this repository in a
-container that has only what is declared — nothing more, nothing guessed. The names below are what
-that container needs; none of them is a value, and this tool never reads or shows one.
+Say this first, in your own words, before you scan: the fleet builds and tests this repository in a container that has only what is declared, nothing guessed. The names below are what that container needs; none of them is a value, and this tool never reads or shows one.
 
 ## Run first
 
-- `node scripts/inventory.mjs [path] --help` — scans the repository (default: here) and prints the
-  names in three groups: build/test, deploy-only, bindings. Each name shows where it was found
-  (file:line), what uses it, and where a local value would come from — a `.env` file, your shell, a
-  CI secret, or a Cloudflare binding. `--json` gives the same data in machine form.
-- `node scripts/check.mjs <file> --help` — validates an existing `catalyst.env.json` offline, with
-  the same rules the cloud applies, and never prints a value from it either.
+- `node scripts/inventory.mjs [path] --help`: scans the repository (default: here) and prints the names in three groups: build/test, deploy-only, bindings. Each name shows where it was found (file:line), what uses it, and where a local value would come from: a `.env` file, your shell, a CI secret, or a Cloudflare binding. `--json` gives the same data in machine form.
+- `node scripts/check.mjs <file> --help`: validates an existing `catalyst.env.json` offline with the cloud's rules, and never prints a value from it either.
 
-Then ask the person to review the grouped list: for each name, keep it, drop it, or move it to a
-different group. Keep your own reasoning short — the list is the point, not your commentary on it.
+Then ask the person to review the grouped list: for each name, keep it, drop it, or move it to a different group. Keep your own reasoning short; the list is the point.
 
 ## Load on demand
 
@@ -32,9 +25,7 @@ different group. Keep your own reasoning short — the list is the point, not yo
 
 ## Rules
 
-- Report, never repair. This tool never writes `catalyst.env.json` and never proposes anything.
-- Never print a value. Not a `.env` value, not a secret, not a committed `wrangler.toml [vars]`
-  value — only the name, where it was found, and where a local value would come from.
+- Report only. This tool writes no `catalyst.env.json` and proposes nothing.
+- Print names only: never a `.env` value, a secret, or a committed `wrangler.toml [vars]` value. Give the name, where it was found, and where a local value would come from.
 - A Cloudflare (or other platform) binding is not an environment value; keep the two apart.
-- This reads the repository only. It needs no login and makes no network call — unlike the
-  account-scope `catalyst-skills environment` verb, which reads your tenant's own declaration.
+- This reads the repository only, with no login and no network call. The account-scope `catalyst environment` verb reads your cloud account's own declaration.

package/skills/what-this-repo-needs/references/what-each-group-means.md

@@ -1,68 +1,38 @@
 # What each group means
 
-`node scripts/inventory.mjs` sorts every environment variable name it finds into exactly one of
-three groups. This page explains what each one means and why a name lands where it does — it never
-restates a value, because the scan itself never reads one.
+`node scripts/inventory.mjs` sorts every environment variable name it finds into exactly one of three groups. This page explains why a name lands where it does; the scan never reads a value.
 
 ## build/test
 
-Needed to install, build and run the tests in a container. This is the default group: a name lands
-here unless something specific pulls it into `deploy-only` or `bindings`. Examples: a name read by
-the repository's own source (`process.env.X`), a name documented in a `.env.example`-shaped file, a
-name a non-deploy workflow job uses.
+Needed to install, build and run the tests in a container. This is the default group: a name lands here unless something specific pulls it into `deploy-only` or `bindings`. Examples: a name the source reads (`process.env.X`), a name in a `.env.example`-shaped file, a name a non-deploy workflow job uses.
 
-The scan does not read `package.json` scripts. A name that only a script's own shell line mentions
-and nothing else refers to is therefore not listed — add it by hand if the container needs it.
+The scan does not read `package.json` scripts. A name only a script's shell line mentions is therefore not listed; add it by hand if the container needs it.
 
-A name referenced from **both** a deploy job and a non-deploy job (or build step) still lands here,
-not in `deploy-only` — a container that builds and tests the repository needs it too, so the
-stricter requirement wins.
+A name referenced from **both** a deploy job and a non-deploy job (or build step) lands here, because a container that builds and tests the repository needs it too.
 
 ## deploy-only
 
-A CI secret used **only** by a job the scan classifies as deploying something: a workflow job that
-sets `environment:`, whose id looks like `deploy`, `publish`, `release` or `cd`, or that runs a
-recognised deploy command (`wrangler deploy`, `npm publish`, `gh release create`, and similar). If
-the same name is referenced anywhere outside a deploy job, it moves to `build/test` instead.
-
-Its local value comes from a CI secret — something a repository or organisation admin sets in the
-CI provider, not something a person types into a local `.env` file.
+A CI secret used **only** by a job the scan classifies as deploying: a workflow job that sets `environment:`, whose id looks like `deploy`, `publish`, `release` or `cd`, or that runs a recognised deploy command (`wrangler deploy`, `npm publish`, `gh release create`, and similar). A reference anywhere outside a deploy job moves the name to `build/test`. Its local value is a CI secret a repository or organisation admin sets in the CI provider.
 
 ## bindings
 
-A Cloudflare (or other platform) binding: a name bound to a resource — a KV namespace, a D1
-database, a Durable Object, an R2 bucket, a queue — declared in `wrangler.toml`. A binding is not an
-environment value a process reads from `process.env`; it is wired up by the platform at deploy
-time, which is why this scan keeps the two apart even though both are "names the container needs".
-
-A `wrangler.toml` binding table names the binding through one attribute's value — `binding = "NAME"`
-for most tables, `name = "NAME"` for `durable_objects.bindings` — never through the table's own key.
+A Cloudflare (or other platform) binding: a name bound to a resource (a KV namespace, a D1 database, a Durable Object, an R2 bucket, a queue) declared in `wrangler.toml`. The platform wires it up at deploy time, so it is not a `process.env` value, and the scan keeps the two apart. A binding table names the binding through one attribute's value (`binding = "NAME"` for most tables, `name = "NAME"` for `durable_objects.bindings`), never through the table's own key.
 
 ## wrangler.toml `[vars]`: build/test, not a binding, and nothing to declare
 
-A `[vars]` (or `[env.<name>.vars]`) table is different from every other wrangler table: its keys ARE
-the names, and their values are committed in `wrangler.toml` itself — checked into the repository,
-not a secret and not something a person supplies locally. So a `[vars]` name lands in `build/test`
-(it is a plain value a build or test step could read, not a resource binding), and the scan marks it
-`needsDeclaration: false`: there is nothing for a customer to declare, because the value is already
-sitting in the file everyone can already read.
+A `[vars]` (or `[env.<name>.vars]`) table's keys ARE the names, and their values are committed in `wrangler.toml` itself, readable by everyone. So a `[vars]` name lands in `build/test` as a plain value a step could read, marked `needsDeclaration: false`: there is nothing to declare.
 
 ## Where a local value comes from
 
-For every name, "where the local value comes from" is one of:
+For every name, one of:
 
-- **a `.env` file or your shell** — the ordinary case for `build/test`.
-- **a CI secret** — for `deploy-only`, and for any `build/test` name whose only non-committed source
-  is a workflow's `secrets.X` reference.
-- **a Cloudflare binding** — for `bindings`; there is no local value to supply, the platform wires
-  it up.
-- **value committed in wrangler.toml — nothing to declare** — for a `[vars]` entry.
+- **a `.env` file or your shell:** the ordinary case for `build/test`.
+- **a CI secret:** for `deploy-only`, and for a `build/test` name whose only non-committed source is a workflow's `secrets.X` reference.
+- **a Cloudflare binding:** for `bindings`; the platform wires it, so there is no local value.
+- `value committed in wrangler.toml — nothing to declare`: for a `[vars]` entry.
 
-None of these is the value itself — only where it would come from, so a person reviewing the list
-knows what to check without this tool ever showing them what is actually set.
+Each says where a value would come from, never the value, so a reviewer knows what to check without seeing what is set.
 
 ## A `wrangler.jsonc` or `wrangler.json` file
 
-Modern Wrangler configs are often JSONC. This scan does not read them yet — `wrangler.toml` is the
-only Cloudflare config format it understands — so a repository configured that way gets a note
-saying so, rather than a silent, confidently wrong "no bindings found".
+The scan reads only `wrangler.toml`, so a repository configured with JSONC gets a note saying so rather than a confident "no bindings found".

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

@@ -1,7 +1,7 @@
 #!/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-skills env check`.
+// wraps `catalyst env check`.
 import { runCliOffline } from "./lib/cli.mjs";
 
 const HELP = `Usage: node scripts/check.mjs <file> [--json]
@@ -30,7 +30,7 @@ if (res.stderr) process.stderr.write(res.stderr);
 await finish(res.code);
 
 /**
- * ⛔ NEVER `process.exit(code)` STRAIGHT AFTER A WRITE — the same rule `bin/catalyst-skills.js`
+ * ⛔ 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

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

@@ -2,7 +2,7 @@
 // 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-skills env inventory`.
+// `catalyst env inventory`.
 import { runCliOffline } from "./lib/cli.mjs";
 
 const HELP = `Usage: node scripts/inventory.mjs [path] [--json]
@@ -27,7 +27,7 @@ if (res.stderr) process.stderr.write(res.stderr);
 await finish(res.code);
 
 /**
- * ⛔ NEVER `process.exit(code)` STRAIGHT AFTER A WRITE — the same rule `bin/catalyst-skills.js`
+ * ⛔ 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

package/skills/what-this-repo-needs/scripts/lib/cli.mjs

@@ -1,6 +1,6 @@
 #!/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. 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.
@@ -10,7 +10,9 @@ 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,8 +43,8 @@ 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 = {}) {
@@ -51,12 +53,12 @@ export function runCli(args, opts = {}) {
 }
 
 /**
- * Run `catalyst-skills env inventory` / `env check` without requiring a credential at all. Unlike
+ * 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 @catalyst-cloud/catalyst-skills` otherwise.
+ * `npx -p @catalyst-cloud/cli catalyst` otherwise.
  */
 export function runCliOffline(args, opts = {}) {
   let cfg = null;
@@ -72,7 +74,7 @@ export function runCliOffline(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,
@@ -81,7 +83,7 @@ function spawnCli(cfg, 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 ?? "" };
@@ -95,7 +97,7 @@ function spawnCli(cfg, 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);
 }

package/skills/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.13.0 — 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,36 +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
-
-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`.
+## Writing the lines
 
-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.
+- 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 flow number is named in that block by name, not left out: cycle time, throughput, or how long pull requests have been open are not computed by anything a key reads today. Say they are not computed rather than counting ticket dates or open pull requests and calling it that.
+## 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.