@catalyst-cloud/cli 0.13.0 → 0.14.0

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,13 +1,13 @@
 #!/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`.
+// check.mjs — checks the repository settings TOML offline. 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]
+const HELP = `Usage: node scripts/check.mjs [path] [--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.
+Checks TOML syntax and the environment variable table in .catalyst/catalyst.toml (default), or at
+the repo-relative path you name. Prints "valid" or refusal reasons — never a value. A legacy root
+catalyst.env.json is not read by the cloud. Exit 0 valid or absent, 1 invalid or unreadable.
 
 --json prints {state, errors}. This is a local, offline check: no login, no network required.`;
 
@@ -18,19 +18,18 @@ if (args.includes("--help") || args.includes("-h")) {
 }
 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"] : [])]);
+const res = runCliOffline([
+  "env",
+  "check",
+  ...(file ? [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/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,33 @@
 ---
 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:*)
+  Use for "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?" and "what does this setting do, where is it set?" in Catalyst Cloud, or asks for something to be done rather than known. Reads the contract via catalyst CLI. Read-only: route work/decisions, never answer 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.14.0 — 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`.
+Use one snapshot and the person's login. Run scripts, never read them. --help explains usage; exit 2 needs onboard, exit 1 means failure.
 
-## Run first
+- `node scripts/snapshot.mjs` prints contract, running work, queue, ranked asks, replica verdict. --board adds stages, --accounts coding accounts, --team K narrows.
+- `node scripts/explain.mjs <ticket>` explains eligibility; --history adds attempts, rounds, holds and releases.
+- `node scripts/show-my-map.mjs [--team K]` prints stages, labels, ladder and thresholds.
 
-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.
-
-- `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.
-
-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`.
+Comments/relations: catalyst-linear. PRs: catalyst-github. Readiness: catalyst-onboard. Use current account facts/URLs, never memory. Unknown means inconclusive. PR labels/reactions are unmirrored; print their URL. Accounts/history are readable.
 
 ## Load on demand
 
-| when | read |
+| question | reference |
 | -- | -- |
-| 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` |
-| `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` |
-| 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).
-
-## 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.**
+| status or stuck? | references/status-reply.md; schema assets/status-reply.json |
+| eligibility reason? | references/why-is-it-stuck.md |
+| order, capacity, WIP or routing? | references/what-runs-next.md |
+| failure, park or hold? | references/when-a-phase-fails.md |
+| request or decision? | references/routing-work.md |
+| phases or Done? | references/the-ladder.md |
+| columns or slots? | references/stages-and-mapping.md |
+| accounts, windows, quarantine or provider? | references/coding-accounts.md |
+| setting, screen, route or role? | references/settings-and-where-they-live.md |
+
+Read-only: give ids, source, release and actor. Route releases to `unstick`, decisions to what-needs-me before defaults, ownership to run-this-project. Subscribe, never poll. Report each system cause once.

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,11 @@
+# Coding accounts
+
+snapshot.mjs --accounts omits credentials/emails. An owner/admin enrols, pauses, removes or replaces credentials at `<their cloud>/settings/coding-accounts`.
+
+Slots identify credentials, not emails. Claude/GLM/Qwen use Claude CLI, Codex uses Codex; GLM/Qwen also use OpenCode. Routing names the model.
+
+Declared state is operator-set active/disabled. Observed health is healthy/degraded/unknown, polled every five minutes for active slots and daily for disabled ones. Credential conflicts/auth mismatches quarantine; Replace credential on the account's page clears it.
+
+Subscriptions have 5-hour and 7-day windows. Walls kill sessions; phase burn must fit headroom. Claude slots allow concurrent phases up to a cap; Codex permits one because refresh tokens are single-use. Vendor status does not reveal account windows.
+
+When idle, explain. routing_unavailable or no_eligible_account_slot points here. Read --accounts: empty means no enrolment; inspect walled, quarantined and reason. Silence proves nothing.

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

@@ -1,36 +1,7 @@
-# Routing work
+# Route requests
 
-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.
+Classify first: question, work request, human decision, or both request/decision. Questions: status-reply.md. Decisions: what-needs-me before defaults.
 
-## Three kinds of request
+Search projects with catalyst query projects and `catalyst query search <terms>`. Reuse fitting projects. Otherwise name outcome, one or two catalyst-linear tickets and owner; the person creates the project. Assign a person or run-this-project session, giving its start command. Report returned ids, owner and next event; never guess ids.
 
-A message from the person is one of three things, and you decide which in the first sentence of your reply:
-
-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 that contains a decision is both: route the work and raise the decision, and say in the reply that you did both.
-
-## 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.
+Pick no ask option, close no ask and post nothing in the human's voice. Record their chat answer through what-needs-me as the app actor.

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

@@ -0,0 +1,17 @@
+# Settings
+
+Use live values and the person's cloud prefix. Owner/admin acts unless stated. Name screen, route, rule.
+
+| screen and route | rule |
+| -- | -- |
+| Integrations, /settings/connections | Connecting Linear needs admin browser session, which chooses the account. A workspace binds to exactly one account and vice versa; a conflict needs a decision, not retry. |
+| Profile, /settings/profile, then Connections | The personal GitHub grant comes first; missing identity or another person's installation refusal means grant personal GitHub first. |
+| Connections | Removing the App on GitHub self-heals the registry; Catalyst unlink uninstalls upstream; neither needs support. |
+| Your projects, /settings/projects | Each Catalyst project pairs one Linear team with its registered GitHub repositories. Manage the project, attach repositories, and choose the team's default repository here. |
+| Merging, /settings/projects/$projectId/repositories/$repoId/merging | Merge policy is changed here; contract merge gives value/source; catalyst-github only reads. |
+| Code reviews, /settings/projects/$projectId/repositories/$repoId/code-reviews | Post review requests as selects a connected member. Strict policy without reviewer never earns ready label; configure reviewer or change policy. |
+| Merge queue, no Catalyst page | After ready label, the merge itself is whatever the repository's own setup does with it; the repo admin owns this. This bundle cannot identify its queue vendor; never guess. |
+| Repositories | Shows operator-set runner cap, default 20, paused effective zero; see what-runs-next.md. |
+| Secrets /settings/secrets and Environment /settings/environment, plus repository sections | Secrets write-only, variables readable; names are never both. Repository values override account values. Variables may reference vault secrets, expanded only in container. |
+| Repositories | Without a registered team nothing reaches a runner, and the failure is silent; raise admin/operator fix as ask. |
+| Routing, no settings page for this | Global stage defaults and empty per-account table select default provider; never promise Codex-first. |

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

@@ -0,0 +1,19 @@
+# Stages
+
+Slots are board positions; stages are Linear states. teams[].stages maps them per team; show-my-map.mjs stars required slots.
+
+Order: dispatch, intake, research, plan, implement, remediate, verify, review, pr, done, canceled.
+
+| required slot | allowed Linear type | purpose |
+| -- | -- | -- |
+| dispatch | unstarted/backlog | starts work |
+| intake | unstarted/backlog, never triage | optional classification of unseen tickets |
+| pr | started | permits merge phase |
+| done | completed | merge webhook writes it |
+| canceled | canceled | terminal |
+
+Missing/wrong required mappings stop work; others warn. Dispatch/pr/done/canceled must be live. `teams[].gitAutomation` stores consent; nothing reads it.
+
+workflowMode: adopted means Catalyst-created, mapped means human-chosen, mixed means both. Configure at `<their cloud>/settings/linear-teams`, never catalyst.toml.
+
+stateId is authoritative; imports can replace ids but keep names. catalyst-linear resolves slots to ids. stateStillExists: false refuses the move; remap with `catalyst team map <KEY>`. Backlog is not a slot: parking resolves a live backlog-type state. catalyst-onboard explains readiness and who fixes it.

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

@@ -1,36 +1,16 @@
-# The one-reply shape
+# Status
 
-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`.
+Open with takenAt, source and replica cursor/API reason. Then:
 
-## The rule
+1. In flight: ticket, phase and elapsed time from running.
+2. Blocked: reason and release actor.
+3. Waiting on human: ranked waitingOnHuman asks, question and what each releases. Details belong to what-needs-me.
+4. Closed: query issues at the contract's done stage or read the change feed for the requested window; otherwise since the last reply.
+5. Next: queue order and phase.
+6. Cannot see, when nonempty: unreadable facts and CLI-printed URLs. PR labels/reactions are not mirrored. Metrics such as cycle time, throughput, or how long pull requests have been open are not computed; never substitute ticket dates.
 
-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.
+Lines use identifier, contract stage, then one clause. Age uses updated_at/lease start and expected phase duration. Omit empty blocks.
 
-## The five blocks, in this order
+Read --board by slot. Long dispatch with nothing running: explain its first ticket. Unmoved cards may run, retry or remediate; count repair separately, never as progress. Asks wait on humans; local-lane work runs elsewhere. Comments and explain --history must agree.
 
-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`.
-
-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.
-
-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.
-
-## The header line
-
-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.
-
-## Writing the lines
-
-- 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.
-
-## What the reply never does
-
-- 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.
+Stuck: nothing offered, no automatic release, no ask or post-failure human comment/push. Otherwise name the wait. Move nothing; route requests to routing-work.md and decisions to what-needs-me.

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

@@ -0,0 +1,20 @@
+# Phases
+
+Explain using their tickets/repos. Dispatch starts repository-configured cloud containers on enrolled accounts, never laptop coding sessions. Agents react to events; documents/outcome comments stay on the ticket.
+
+Tickets need outcome title, acceptance criteria, priority, no open blocker and no assumed chat context. Catalyst owns working stages/Done. Draft PRs become ready; green, thread-free PRs queue-merge unless held. Linear asks carry options/default/blocked work. Human comments get eyes and threaded replies.
+
+| phase | output or effect |
+| -- | -- |
+| intake | optional classification, no artifact; ladder.intakeEnabled |
+| research | research.md, offered from dispatch |
+| plan | plan.md |
+| implement | implement.md; ticket-id branch and draft PR |
+| validate | validation.md; success enters the shared verify/review stage |
+| pr | pr.md, title first then body; rebase, force-push, mark ready |
+| remediate | remediation.json; failure interrupt, never advances beyond PR |
+| merge | receipt; evidence gate then queue-ready label |
+
+Read ladder.advance and keying: trailing stages name the completed phase, leading stages the next. Failure, remediate and merge do not advance the card; see when-a-phase-fails.md. show-my-map.mjs translates stages; explain names the next phase.
+
+Done means merged. The webhook writes it within seconds; a sweep recovers losses. Missing Done after one minute is a finding; never hand-close. Live requires deployment.

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

@@ -0,0 +1,13 @@
+# Dispatch
+
+Queues update within seconds. Dispatch sorts by priority, created time, identifier; mid-ladder tickets precede them by phases completed. Order never grants eligibility.
+
+An operator sets the repository concurrency cap, default 20, displayed in settings. Pause means zero, preserving the cap. Teams share capacity, including comment-wake.
+
+WIP limits starts per project, one Linear team across repositories: project setting, operator's account value, then 12; zero prevents starts. Members read `catalyst project wip-limit get --team <KEY>`; owners/admins use `set <n>` or set default. Only first phases are held; later phases continue. Count live tickets past dispatch or granted a first phase, including waits/blocks/parks; exclude never-started, backlog and local-lane. Idle at the limit means started tickets wait; use unstick, catalyst-github or what-needs-me.
+
+Routing selects the first candidate passing capability, configured model, provider availability, eligible slot/headroom when needed, and parameters. No survivor gives `no_eligible_account_slot` if capacity skipped a candidate, otherwise routing_unavailable. Stage defaults are global; no routing setting exists and a Codex-first pipeline cannot be promised.
+
+Priority reorders; dispatch starts; backlog stops future phases/rounds without canceling. The person/project owner moves cards. Contract merge.prLabels holds keep PRs out of the queue; ask relations block tickets; the release label corrects ask-shape false positives. Nothing interrupts a running phase. Failed phases need no requeue; manual moves usually restart counts. Priority never overrides blockers.
+
+Explain why not next: position means capacity, so report tickets ahead/running. With none running, read accounts. Reasons use why-is-it-stuck.md; missing means another team, terminal or unknown, so verify the id.

package/skills/whats-happening/references/when-a-phase-fails.md

@@ -0,0 +1,21 @@
+# Failures
+
+Quote live show-my-map.mjs thresholds; these are defaults. Failure itself moves no card.
+
+- Pre-branch or infrastructure failures, including 5xx, stream loss, timeout and environment gaps, retry the same phase without repair.
+- Retry and kickoff routing refusal back off 2, 5, 15 minutes, thresholds.retryBackoffMs.
+- Other failures enter remediate; success restores the exact prior stage. Without a remediate stage, use teams[].labels.hold. thresholds.remediateRoundCap defaults to 3 per episode. Failed rounds queue no further round; repeated validate fingerprints consume one round per episode; no recorded branch means no round.
+- thresholds.parkAfterConsecutiveFailures defaults to 3. Repeated-failure and round-cap parks need release after a fix, never a clock; cap release grants one extra round. The cloud's budgeted loop releases missing-branch/rebase-conflict parks.
+
+unstick previews and runs `catalyst release <ticket> --because <change>`. Release clears all governors or none, naming required action. Without visible change, require --retry-unchanged.
+
+| hold | trigger | release |
+| -- | -- | -- |
+| validate_class_spent | same validate failure after one repair | push, human non-bookkeeping comment, validate pass, ask answer; release after push/comment or --retry-unchanged plus --because; unanswered ask defaults to re-plan after 48 hours |
+| round_threshold | lifetime repair budget | non-fleet push or ask answer grants one cycle; unanswered ask defaults to re-plan after 48 hours; comments and release refused |
+| review_not_converging | nonconverging validate/repair cycles | human comment resumes validate; catalyst: resume implement resumes implement; push and release refused; no ask or 48-hour default |
+| no_change_hold | repair changed nothing | push, human comment or release; never a clock |
+| hand fix pending | ask answered human fixes it | commit on branch |
+| runner pin | runner change merged before image covers it | image pin moves, then Done |
+
+Only validate-budget/round-threshold asks default after 48 hours; others await answers. Runner image breaker needs three distinct tickets failing the same startup class on the live image; dispatch waits for the pin. Paused repositories need operator resume. Report each fleet cause once. explain --history prints attempts, rounds/cap, holds, release conditions and past releases.