@catalyst-cloud/cli 0.13.1 → 0.14.1

package/skills/run-this-project/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Own one Catalyst Cloud project end to end until it closes. Use when the person says "run this project for me", "own this until it ships", "keep this moving", or hands you a project id or a set of tickets to drive. Subscribes to the account's event stream for the scope through the catalyst CLI, reacts to each change in the same turn, makes tickets ready and moves them to dispatch, parks what should stop, chases stalls, escalates inward, and keeps one status summary current. Writes to Linear as the app actor; never polls.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.1 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.1 — written in this repository for customer accounts -->
 
 # Run this project
 

package/skills/unstick/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Get a stuck Catalyst Cloud ticket moving again. Use when the person asks "why is this parked and can you release it?", "unpark this", "get things flowing again", "the outage is over, retry what failed", or hands you a ticket that is not moving. Reads why nothing runs and what holds the ticket through the catalyst CLI, decides whether the recorded cause is fixed, previews the release, releases every governor holding the ticket the right way (or one failure class across a team), and raises an ask only for what a person has to do. Never releases a cause it cannot show changed without saying so.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.1 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.1 — written in this repository for customer accounts -->
 
 # Unstick
 

package/skills/what-needs-me/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   The human's decision inbox on Catalyst Cloud, and the one way an agent raises a decision on their behalf. Use when the person asks "what needs me?", "what am I blocking?", or when active work is gated on a choice only they can make. Lists open asks ranked by how much open work each one holds, files an ask through the cloud's ask route with the account's own template, and records the answer so the held work releases. Never answers as the human, never duplicates an open ask.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.1 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.1 — written in this repository for customer accounts -->
 
 # What needs me
 

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

@@ -1,10 +1,10 @@
 ---
 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.
+  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 a value or prints one. Also checks the environment variable table in `.catalyst/catalyst.toml` offline. 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 the declaration.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.1 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.1 — written in this repository for customer accounts -->
 
 # What this repository needs
 
@@ -13,7 +13,7 @@ Say this first, in your own words, before you scan: the fleet builds and tests t
 ## 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 cloud's rules, and never prints a value from it either.
+- `node scripts/check.mjs [path] --help`: checks TOML syntax and the environment variable table in `.catalyst/catalyst.toml` (default) or the repo-relative path you name. It never reads or prints a variable value. The old root JSON declaration is not read by the cloud.
 
 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.
 
@@ -25,7 +25,7 @@ Then ask the person to review the grouped list: for each name, keep it, drop it,
 
 ## Rules
 
-- Report only. This tool writes no `catalyst.env.json` and proposes nothing.
+- Report only. This tool writes no `.catalyst/catalyst.toml` 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, 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/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 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,13 +18,12 @@ 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);

package/skills/whats-happening/SKILL.md

@@ -1,49 +1,33 @@
 ---
 name: whats-happening
 description: >-
-  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.
+  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.1 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.1 — written in this repository for customer accounts -->
 
 # What's happening
 
-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.
+Use one snapshot and the person's login. Run scripts, never read them. --help explains usage; exit 2 needs onboard, exit 1 means failure.
 
-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.
+- `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.
 
-## Run first
-
-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`: 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.
-
-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`.
+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, 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` |
-| "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` |
-| "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 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.
+| 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/references/coding-accounts.md

@@ -1,24 +1,11 @@
-# Coding accounts: slots, windows, walls
+# Coding accounts
 
-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`.
+snapshot.mjs --accounts omits credentials/emails. An owner/admin enrols, pauses, removes or replaces credentials at `<their cloud>/settings/coding-accounts`.
 
-## Slots and providers
+Slots identify credentials, not emails. Claude/GLM/Qwen use Claude CLI, Codex uses Codex; GLM/Qwen also use OpenCode. Routing names the model.
 
-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.
+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.
 
-## 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.
+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,18 +1,7 @@
-# Routing work
+# Route requests
 
-Your first sentence says which of three things the message is:
+Classify first: question, work request, human decision, or both request/decision. Questions: status-reply.md. Decisions: what-needs-me before defaults.
 
-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.
+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 request containing a decision is both; do and say both.
-
-## A request becomes a project with an owner
-
-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.
-
-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.
+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

@@ -1,20 +1,17 @@
-# Settings and where they live
+# Settings
 
-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.
+Use live values and the person's cloud prefix. Owner/admin acts unless stated. Name screen, route, rule.
 
-| 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`). |
+| 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

@@ -1,25 +1,19 @@
-# Stages and mapping
+# Stages
 
-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.
+Slots are board positions; stages are Linear states. teams[].stages maps them per team; show-my-map.mjs stars required slots.
 
-The slots, in pipeline order: `dispatch`, `intake`, `research`, `plan`, `implement`, `remediate`, `verify`, `review`, `pr`, `done`, `canceled`.
+Order: dispatch, intake, research, plan, implement, remediate, verify, review, pr, done, canceled.
 
-## Five slots are load-bearing
-
-| slot | why it matters | allowed state types |
+| required slot | allowed Linear type | purpose |
 | -- | -- | -- |
-| `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.
+| 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 |
 
-## The state id is the authority
+Missing/wrong required mappings stop work; others warn. Dispatch/pr/done/canceled must be live. `teams[].gitAutomation` stores consent; nothing reads it.
 
-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.
+workflowMode: adopted means Catalyst-created, mapped means human-chosen, mixed means both. Configure at `<their cloud>/settings/linear-teams`, never catalyst.toml.
 
-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.
+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,34 +1,16 @@
-# The one-reply shape
+# Status
 
-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.
+Open with takenAt, source and replica cursor/API reason. Then:
 
-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:
+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.
 
-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.
+Lines use identifier, contract stage, then one clause. Age uses updated_at/lease start and expected phase duration. Omit empty blocks.
 
-## Writing the lines
+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.
 
-- 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.
-
-## Reading the board
-
-`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.
-
-## What counts as stuck
-
-A ticket is **stuck** only when all three hold:
-
-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.
-
-Everything else is **waiting**, and the reply says on what; calling a wait "stuck" sends the human to fix what the cloud is handling.
-
-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`.
+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

@@ -1,30 +1,20 @@
-# What Catalyst is, and the ladder
+# Phases
 
-## In the person's terms
+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.
 
-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.
+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.
 
-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.
+| 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 |
 
-## The phases
+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.
 
-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.
+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

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

@@ -1,27 +1,21 @@
-# When a phase fails: retries, repair rounds, parks and holds
+# Failures
 
-Numbers here are fleet defaults; quote the live `thresholds` that `node scripts/show-my-map.mjs` prints. A failed phase writes no board state: the ticket stays at its stage, and four layers decide what happens next.
+Quote live show-my-map.mjs thresholds; these are defaults. Failure itself moves no card.
 
-1. **Retry in place.** A failure that is not the ticket's fault (one before any branch existed, or infrastructure: a vendor 5xx, a dropped stream, a timeout, an environment gap) re-offers the same phase with no repair round.
-2. **Backoff.** Each retry in place, and a routing refusal at kickoff, waits out a rung first: 2, 5, then 15 minutes (`thresholds.retryBackoffMs`).
-3. **Remediate.** Any other failure moves the card to the remediate stage and queues a repair round; a successful round returns the card to its exact pre-failure stage. A team with no remediate stage gets the hold label (`teams[].labels.hold`) instead. Rounds are capped per failure episode at `thresholds.remediateRoundCap` (default 3); a failed round queues no other, a repeated validate fingerprint spends one round per episode, and a ticket with no recorded branch gets none.
-4. **Park.** After `thresholds.parkAfterConsecutiveFailures` consecutive failures (default 3) the phase parks. A repeated-failure park, and a park at the round cap, release through the person's own login once the cause is fixed (`catalyst release`, never a clock; at the cap it buys one more round). A missing-branch or rebase-conflict park is released by the cloud's own budgeted loop.
+- 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.
 
-`catalyst release <ticket> --because <what changed>` releases every governor holding the ticket, or nothing, naming what a person must do; a cause it cannot see change needs `--retry-unchanged`. The `unstick` skill runs it.
+unstick previews and runs `catalyst release <ticket> --because <change>`. Release clears all governors or none, naming required action. Without visible change, require --retry-unchanged.
 
-## Holds, and what clears each
+| 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 |
 
-A hold stops the cloud retrying what would fail the same way. Each kind clears differently; keep them apart.
-
-| hold | created by | cleared by | refused |
-| -- | -- | -- | -- |
-| **validate budget** (`validate_class_spent`) | the same validate failure returns after its one repair round | a push to the branch; a human comment (a `[bookkeeping]` one does not count); a validate pass; the person's own `catalyst release` after a push or comment since the hold, or with `--retry-unchanged` and a `--because`; an answer to the ask it raised; that ask's default (re-plan) after 48 hours unanswered | nothing a person can do is refused |
-| **round threshold** (`round_threshold`) | the ticket's counted repair rounds reach its lifetime budget | each grants one more cycle: a push the fleet did not make, or an answer to its ask; the ask's default (re-plan) applies after 48 hours unanswered | a human comment does not clear it; `catalyst release` is refused |
-| **review convergence** (`review_not_converging`) | validate and repair cycles that do not converge | a human comment, which resumes at validate; `catalyst: resume implement` in the comment resumes at implement | a push alone does not clear it; `catalyst release` is refused; it raises no ask and has no 48-hour default |
-| **no change** (`no_change_hold`) | a repair round that changed nothing | a push, a human comment, or `catalyst release` | never a clock |
-| **hand fix pending** | an ask answered "a human fixes it" | a commit landing on the branch | |
-| **runner pin** | a runner change merged before the live runner image covers it | the image pin moving, which moves the ticket to Done | |
-
-The 48-hour default applies only to the asks a validate-budget or round-threshold hold raises; every other ask waits for its answer (`what-needs-me`).
-
-Two holds are fleet-wide, one alert for every ticket they hold: the **runner image breaker** (three distinct tickets failing the same startup class on the live image pauses their dispatch until the image pin moves) and a **paused repository** (an operator resumes it). `catalyst explain --history <ticket>` prints the attempts, rounds against the cap, holds with what releases each, and past releases.
+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.