@catalyst-cloud/cli 0.9.5 → 0.13.1

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

@@ -0,0 +1,27 @@
+# When a phase fails: retries, repair rounds, parks and holds
+
+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.
+
+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.
+
+`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.
+
+## Holds, and what clears each
+
+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.

package/skills/whats-happening/references/why-is-it-stuck.md

@@ -1,63 +1,56 @@
-# Why is it stuck
+# Why is it stuck: every reason, and who acts
 
-This reference restates an invariant: the vocabulary the cloud's eligibility explainer uses when nothing is offered for a ticket, translated for a person, with what releases each. `node scripts/explain.mjs <ticket>` prints the reason for one ticket; this table turns it into the next action. The `how-catalyst-works` skill carries the mechanism behind each row.
-
-## How to read a reason
-
-`explain` prints one paragraph: the queue position (or none), the status, the reason, a detail or marker when the cloud gave one, the last failure, and any advisories. Match the reason to a row below. "Releases itself" means the cloud clears it with no human action; "needs" names who acts. When a reason is not in this table, `explain` prints it as the cloud spelled it; report it verbatim and say the bundle does not know it.
+The pack's one reason table; other skills point here. Match the reason `node scripts/explain.mjs <ticket>` prints to a row. "No one acts" is an honest answer. A reason missing here is printed as the cloud spelled it: report it verbatim and say the bundle does not know it. The mechanism is in `references/when-a-phase-fails.md`.
 
 ## Reasons that release themselves
 
-| reason | what it means | how it clears |
+`retry_backoff` (a retry rung, `thresholds.retryBackoffMs`), `lease_held`, `intake_lease_held` and `later_phase_lease_held` (a live container holds this or a later phase), `environment_check_running`, `claim_storm` (claimed too often in the last hour), `repo_at_capacity` (every runner seat busy), `stale_failure_episode` (the round would repair a phase already passed, so it is dropped), and `no_branch_to_remediate` / `branch_missing` (the cloud's budgeted release): each clears on its own, and no one acts.
+
+| reason | what it means, and what clears it | who acts |
 | -- | -- | -- |
-| `retry_backoff` | the failed phase is retrying in place and waiting out its rung | a clock; the rungs are the contract's `thresholds.retryBackoffMs` |
-| `lease_held` | a live container already holds this phase | the phase finishes |
-| `intake_lease_held` | a later phase is offered while an intake container still holds the ticket | intake finishes |
-| `environment_check_running` | the repository's environment check is in flight | the check finishes |
-| `runner_image_breaker` | fleet-wide: the live runner image fails every phase at startup, so dispatch is held rather than parking tickets | the cloud moves the pin; one alert per tenant, no per-ticket action |
-| `routing_unavailable` | claimed, then refused at kickoff: no route, no eligible coding-account slot, or the provider is unavailable | provider recovery or a slot freeing; if it persists, the tenant admin checks coding accounts in settings |
-| `cooling_down` (with a named callback) | the phase is parked on a condition the cloud watches | the callback fires; the `detail` names it |
-| `wip_limit` | the project (one Linear team, all its repositories) is at its WIP limit, default 12, so this ticket gets no first phase; tickets already in progress are unaffected | a ticket in progress finishes. If the fleet is idle at the limit, the in-progress tickets are the ones waiting (merge queue, holds, paused repositories, asks): unstick those, never the queue. Raising the limit is the project owner's call |
+| `runner_image_breaker` | fleet-wide: the live runner image fails every phase at startup; the image pin moves; one alert per account | an operator |
+| `routing_unavailable` | refused at kickoff: no route, no eligible slot, or the provider down (the detail says which); clears on recovery | usually no one acts; if it persists, a workspace owner or admin, in settings, checks coding accounts (`references/coding-accounts.md`) |
+| `cooling_down` (with a named callback) | parked on a condition the cloud watches; the callback in `detail` fires | no one acts; if the callback stalls, the person, with their own login, releases it through `unstick` |
+| `wip_limit` | the project is at its work-in-progress limit, so no first phase; a ticket in progress finishing clears it | no one acts on this ticket; the in-progress tickets it waits on each have their own row |
 
 ## Reasons that need a human
 
 | reason | what it means | who acts and how |
 | -- | -- | -- |
-| `ask_ticket` | it carries an ask label; a question is never work | the human answers the ask (`what-needs-me`) |
-| `ask_shape_suspected` | its own text reads as a decision request though it carries no ask label | the human either answers it as an ask or applies the release label the contract names |
-| `blocked` | a live blocking relation holds it | whoever owns the blocker closes it; if the blocker is an ask, that is the human |
-| `not_at_dispatch_stage` | the card is not in the team's dispatch column | someone moves the card to the dispatch slot (`references/reprioritising.md`) |
-| `not_at_pr_stage` | merge is next but the card is not in the PR column | the card returns to the pr slot; an automation that bounced it should be found |
-| `no_change_hold` | a repair round changed nothing | a human comment on the ticket, or a new push to the branch |
-| `waiting_on` | a merge-gate failure with no cause the cloud can repair | read the merge-wait comment on the ticket; usually a hold label or a review a person must give (`catalyst-github`) |
-| `externally_claimed` | a worker outside the cloud holds it | that worker, or the human removes the local-lane label |
-| `environment_check_required` / `_failed` / `_expired` / `_hash_mismatch` | the repository's environment gate has not passed | the tenant admin runs or fixes the environment check in settings |
-| `repo_paused` | an operator paused the repository | the operator resumes it |
-| `scope_overlap` | its declared file scope intersects a ticket already in flight | wait for the other ticket, or the human decides which goes first |
+| `ask_ticket` | it carries an ask label; a question is never work | the person, with their own login, answers the ask (`what-needs-me`) |
+| `ask_shape_suspected` | its text reads as a decision request with no ask label | the person, with their own login, answers it as an ask or applies the contract's release label |
+| `blocked` | a live blocking relation holds it | the blocker's owner closes it; for an ask, the person, with their own login |
+| `not_at_dispatch_stage` | the card is not in the dispatch column | the person, with their own login, moves it to the dispatch slot |
+| `not_at_pr_stage` | merge is next but the card is off the PR column | the person, with their own login, returns it to the pr slot and finds the automation that bounced it |
+| `no_change_hold` | a repair round changed nothing | the person, with their own login, comments or pushes; `unstick` can also release it |
+| `waiting_on` | a merge-gate failure the cloud cannot repair holds it at PR | the person, with their own login, reads the merge-wait comment: usually a hold label or an owed review (`catalyst-github`) |
+| `externally_claimed` | a worker outside the cloud holds it | that worker, or the person, with their own login, removes the local-lane label |
+| `environment_check_required` / `environment_check_failed` / `environment_check_expired` / `environment_check_hash_mismatch` | the repository's environment check has not run, failed, aged out, or predates a change | a workspace owner or admin, in settings, runs, fixes or reruns it |
+| `repo_paused` | an operator paused the repository | an operator resumes it |
+| `scope_overlap` | its declared file scope meets a ticket in flight | the person, with their own login, picks which goes first, or waits |
+| `human_owned_pr` | a person's own pull request holds the ticket | the person, with their own login, closes, merges or hands over that pull request, which only they may close. The release command refuses it |
+| `review_not_converging` | validate and repair cycles are not converging (review convergence hold) | the person, with their own login, reads the findings (`catalyst-github`) and comments. The release command refuses it; the hold table in `references/when-a-phase-fails.md` says what clears it |
+| `round_threshold` | the lifetime repair budget is spent (round-threshold hold) | the person, with their own login, answers the ask the cloud raised or pushes a fix; point at that ask rather than raising another. The release command refuses it; see the hold table |
 
 ## Reasons a release clears once the cause is fixed
 
-These do not release themselves, and nobody but the person needs to act: once the recorded cause is fixed, the person's own login releases them with `catalyst-skills release <ticket>`. The desk does not release; route the ticket to the `unstick` skill, which reads the history, previews the release and runs it, or names what a person must do first.
+The desk does not release. Route these to the `unstick` skill, which reads the history, previews `catalyst release <ticket>`, and runs it or names what a person must do first.
 
-| reason | what it means | note |
-| -- | -- | -- |
-| `phase_parked` / `cooling_down` (parked after repeated failures, or the round cap was spent) | the phase is parked and does not release itself | `unstick`; `explain --history` names the park and the failure class it recorded |
-| `remediate_parked` | the repair phase itself is parked, so the failing phase has nowhere to be repaired | as above |
-| `validate_class_spent` | this validate failure already spent its one repair round in this episode | a push or a comment saying what to change releases it on its own; otherwise `unstick` |
-| `human_owned_pr` | a person's own pull request holds the ticket | that person closes or merges it; no release clears it |
-| `review_not_converging` | review and repair kept finding new problems without converging | a person reads the findings and comments on the ticket to resume; raise an ask for that read |
-| `round_threshold` | the ticket spent its lifetime repair budget | a person answers the ask the cloud raised, or pushes a fix |
-| `no_branch_to_remediate` / `branch_missing` / `branch_gone` | a branch-dependent phase has no branch to clone | the cloud releases missing-branch parks on its own budget; a deleted branch needs a human to decide |
-| `stale_failure_episode` | the ladder advanced after the recorded failure | informational; the round is dropped |
+| reason | what it means | note | who acts |
+| -- | -- | -- | -- |
+| `phase_parked` / `cooling_down` (repeated failures, or the round cap spent) | the phase is parked | `explain --history` names the park | the person, with their own login |
+| `remediate_parked` | the repair phase itself is parked | as above | the person, with their own login |
+| `validate_class_spent` | the validate-budget hold | a push, comment or ask answer also clears it (the hold table) | the person, with their own login |
+| `branch_gone` | a branch that existed was deleted | recreate it, or drop the ticket | the person, with their own login |
 
 ## Reasons that are not problems
 
-`ticket_terminal` (done or canceled), `pipeline_complete` (every phase ran), and `pr_merged` (the PR merged, nothing left to clone) describe finished work. Report them as closed, not blocked.
+`ticket_terminal`, `pipeline_complete` and `pr_merged` describe finished work; no one acts. Report them as closed.
 
 ## When the cloud could not judge
 
-A status of `unknown` with a reason such as `ordering_never_published`, `ordering_stale`, `workflow_mapping_unknown`, `ticket_unknown`, `dependency_snapshot_unknown`, `blocker_unknown`, `label_snapshot_unknown`, `prior_artifact_unknown`, `scope_unknown`, `scope_occupancy_unknown` or `branch_snapshot_unknown` means the evaluator failed closed rather than guessing. Most clear on the cloud's next pass. `workflow_mapping_unknown`, and `ordering_never_published` beside it, does not clear by itself when the team has no saved stage mapping: `explain` then names the missing stages, and a tenant owner or admin maps the team in Settings → Linear teams. If any other one persists for a team, the readiness checks (`catalyst-setup`) are the next read.
+A status of `unknown` with `ordering_never_published`, `ordering_stale`, `workflow_mapping_unknown`, `ticket_unknown`, `dependency_snapshot_unknown`, `blocker_unknown`, `label_snapshot_unknown`, `prior_artifact_unknown`, `scope_unknown`, `scope_occupancy_unknown` or `branch_snapshot_unknown` means "I could not look", never "it is not there": report it as inconclusive; most clear on the next pass. `workflow_mapping_unknown` (and `ordering_never_published` with it) does not clear by itself when the team has no saved mapping: a workspace owner or admin maps it (`catalyst team map <KEY>`). If another persists, read readiness (`catalyst-onboard`).
 
 ## The one advisory
 
-`human_addressed_unlabeled_ask_suspect` gates nothing: the ticket is assigned to a human with no delegate and may be an unlabelled ask. Mention it in the waiting-on-human block with a question mark.
+`human_addressed_unlabeled_ask_suspect` gates nothing: a human-assigned ticket may be an unlabelled ask. List it under waiting-on-human with a question mark.

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // explain.mjs — "why is this ticket stuck?" in one paragraph. A thin wrapper over
-// `catalyst-skills explain <ticket>`, which reads the cloud's eligibility explainer for the ticket's
+// `catalyst explain <ticket>`, which reads the cloud's eligibility explainer for the ticket's
 // team and translates the exclusion reason, the failure block and any advisories into plain English.
 import { mustRun, parseFlags, printHelp } from "./lib/cli.mjs";
 

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: spawn the catalyst-skills CLI.
+// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: spawn the catalyst CLI.
 // The CLI holds the SDK and the key; this file holds neither. It reads customer.json only
 // to learn where the CLI lives, and it exits 2 with one line when the machine is not connected.
 // Run any script beside this one with --help; this file is a library and is never run directly.
@@ -8,7 +8,9 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 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 NOT_CONFIGURED_EXIT = 2;
 
 export function configPath() {
@@ -36,7 +38,7 @@ function notConfigured(why) {
 }
 
 /**
- * Run one catalyst-skills verb and return {code, stdout, stderr}. Uses the CLI path the login
+ * Run one catalyst verb and return {code, stdout, stderr}. Uses the CLI path the login
  * recorded when it still exists, else `npx <package>`. A CLI exit of 2 with a "not joined" or
  * "not connected" line is turned into this script's own exit 2, so every caller sees one contract.
  */
@@ -44,7 +46,7 @@ export function runCli(args, opts = {}) {
   const cfg = loadConfig();
   const useRecorded = typeof cfg.cliPath === "string" && existsSync(cfg.cliPath);
   const cmd = useRecorded ? process.execPath : "npx";
-  const argv = useRecorded ? [cfg.cliPath, ...args] : [PACKAGE, ...args];
+  const argv = useRecorded ? [cfg.cliPath, ...args] : [...NPX_ARGS, ...args];
   const res = spawnSync(cmd, argv, {
     input: opts.stdin,
     encoding: "utf8",
@@ -130,6 +132,6 @@ export function printHelp(usage, spec, notes = []) {
     for (const n of names) lines.push(`  --${n}${spec[n].value ? " <value>" : ""}  ${spec[n].help}`);
     lines.push("");
   }
-  lines.push(...notes, "", "Exit codes: 0 ok · 1 the check failed or the arguments were wrong · 2 this machine is not connected to a tenant");
+  lines.push(...notes, "", "Exit codes: 0 ok · 1 the check failed or the arguments were wrong · 2 this machine is not connected");
   process.stdout.write(lines.join("\n") + "\n");
 }

package/skills/whats-happening/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/{how-catalyst-works → whats-happening}/scripts/show-my-map.mjs

@@ -1,45 +1,31 @@
 #!/usr/bin/env node
-// show-my-map.mjs — this tenant's stage map, ladder and thresholds, straight from the contract:
+// show-my-map.mjs — this account's stage map, ladder and thresholds, straight from the contract:
 // per team, every slot with the Linear stage it maps to, its type, whether that state still exists
 // and how the mapping was chosen; then the ladder and the live failure thresholds.
-import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, wantsHelp } from "./lib/cli.mjs";
+import { mustRun, parseFlags, parseJson, printHelp } from "./lib/cli.mjs";
 
-const HELP = `Usage: node scripts/show-my-map.mjs [--team <key>] [--json]
-
-Prints the tenant contract's stage map, ladder and thresholds. Nothing here is guessed: every value is
-read from the contract Catalyst Cloud serves for your tenant. Wraps: catalyst-skills contract --path.
-
-  --team <key>   only this team
-  --json         one JSON document: { slots, teams, ladder, thresholds }
-  --help         this text
-
-A slot marked * is load-bearing: dispatch, intake, pr, done and canceled must be mapped for the
-ladder to move at all; the others are informational. "(unmapped)" means the team has no stage for
-that slot; "(state gone)" means the mapped Linear state no longer exists and needs re-mapping in
-settings.
-
-Exit 0, 1 on a usage error or an unknown team, 2 when this machine is not connected to a tenant or
-the contract could not be read (the line says which).`;
+const SPEC = {
+  team: { value: true, help: "only this team" },
+  json: { value: false, help: "one JSON document: { slots, teams, ladder, thresholds }" },
+};
 
 const LOAD_BEARING = new Set(["dispatch", "intake", "pr", "done", "canceled"]);
 
-const argv = process.argv.slice(2);
-if (wantsHelp(argv)) {
-  console.log(HELP);
+const { help, flags } = parseFlags(process.argv.slice(2), SPEC);
+if (help) {
+  printHelp("node scripts/show-my-map.mjs [--team <key>] [--json] [--help]", SPEC, [
+    "Prints the contract's stage map, ladder and thresholds. Every value is read from the contract",
+    "Catalyst Cloud serves for your account. Wraps: catalyst contract --path.",
+    "A slot marked * is load-bearing: dispatch, intake, pr, done and canceled must be mapped for the",
+    'ladder to move at all. "(unmapped)" means the team has no stage for that slot; "(state gone)"',
+    "means the mapped Linear state no longer exists and the team needs re-mapping.",
+  ]);
   process.exit(0);
 }
-const { flags } = parseFlags(argv, { bool: ["json"], value: ["team"] });
 
 function contractPath(path) {
-  const r = runCli(["contract", "--path", path, "--json"]);
-  exitOnFailure(r);
-  const v = parseJson(r.stdout);
-  if (v === null || v === undefined) {
-    relayStderr(r);
-    console.error(`contract --path ${path} returned nothing readable`);
-    process.exit(1);
-  }
-  return { value: v, stderr: r.stderr };
+  const r = mustRun(["contract", "--path", path, "--json"]);
+  return { value: parseJson(r.stdout, `contract --path ${path}`), stderr: r.stderr };
 }
 
 const slotsRead = contractPath("slots");
@@ -53,7 +39,7 @@ if (flags.team) {
   const want = flags.team.toUpperCase();
   teams = teams.filter((t) => String(t.key ?? "").toUpperCase() === want);
   if (teams.length === 0) {
-    console.error(`no team with key ${flags.team} on this tenant's contract`);
+    console.error(`no team with key ${flags.team} on this account's contract`);
     process.exit(1);
   }
 }

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// snapshot.mjs — one call that answers "where are we?": the tenant contract (trimmed to what a
+// snapshot.mjs — one call that answers "where are we?": the account's contract (trimmed to what a
 // status reply needs), what is running, what is queued, what is waiting on a human, and whether the
 // local replica is fresh. Prints ONE JSON document on stdout and the source line on stderr.
 import { mustRun, parseFlags, parseJson, printHelp, runCli } from "./lib/cli.mjs";
@@ -8,16 +8,18 @@ const SPEC = {
   team: { value: true, help: "limit the queue and the board to this team key" },
   board: { value: false, help: "also include open tickets grouped by stage, in the contract's slot order" },
   limit: { value: true, help: "board: max tickets to read (default 200)" },
-  "full-contract": { value: false, help: "include the whole contract instead of the trimmed tenant block" },
+  "full-contract": { value: false, help: "include the whole contract instead of the trimmed `tenant` block" },
+  accounts: { value: false, help: "also include the coding accounts: provider, state, usage windows, walls, quarantine (never a credential)" },
 };
 
 const { help, flags } = parseFlags(process.argv.slice(2), SPEC);
 if (help) {
-  printHelp("node scripts/snapshot.mjs [--team K] [--board] [--limit N] [--full-contract] [--help]", SPEC, [
-    "Runs, in order: catalyst-skills contract, running, queue, ask list, replica status (and query issues with --board).",
-    "Output: one JSON document {takenAt, source, tenant, running, queue, waitingOnHuman, board?, errors?}.",
+  printHelp("node scripts/snapshot.mjs [--team K] [--board] [--accounts] [--limit N] [--full-contract] [--help]", SPEC, [
+    "Runs, in order: catalyst contract, running, queue, ask list, replica status (query issues with --board,",
+    "accounts with --accounts).",
+    "Output: one JSON document {takenAt, source, tenant, running, queue, waitingOnHuman, board?, accounts?, errors?}.",
     "A section the cloud refused is reported under errors and the rest still prints; exit 1 in that case.",
-    "Every tenant fact (stage names, thresholds, teams) comes from the contract in this output, never from prose.",
+    "Every account fact (stage names, thresholds, teams) comes from the contract in this output, never from prose.",
   ]);
   process.exit(0);
 }
@@ -62,6 +64,8 @@ const out = {
   waitingOnHuman: asks,
 };
 
+if (flags.accounts) out.accounts = section("accounts", ["accounts", "--json"]);
+
 if (flags.board) {
   const args = ["query", "issues", "--limit", String(flags.limit ?? 200), "--json"];
   if (flags.team) args.push("--team", flags.team);

package/skills/catalyst-onboard/references/choosing-a-coding-account.md

@@ -1,52 +0,0 @@
-# Choosing a coding account
-
-A coding account is the AI provider login the work runs on. It is the first thing to settle, because nothing else in setup produces any work without one, and because it needs nothing else in setup to be done. Read the part with `node scripts/where-am-i.mjs`; it says whether one is enrolled, whether each enrolled one can still take work, and who may enrol one.
-
-## The first question
-
-Ask it plainly: "Do you already have a coding account you want Catalyst to run on?" Then wait.
-
-Say why in one line: Catalyst runs each stage of a ticket on an account you own, so you pay your own provider at your own rate and keep the usage under your own name.
-
-## What we support today
-
-Four kinds. Name the one they have in their words, then in the page's words.
-
-| they say | kind | what enrolling asks for | how they get it |
-| -- | -- | -- | -- |
-| "a Claude subscription", "Claude Pro or Max", "I use Claude Code" | Claude, a setup token | the token `claude setup-token` prints | on their own machine: run `claude`, check `/status` shows the account they mean, then run `claude setup-token` and copy the token |
-| "ChatGPT", "Codex", "a ChatGPT Plus or Pro plan" | Codex, an auth file | the contents of `~/.codex/auth.json` | run `codex login`, choose "Sign in with ChatGPT"; the login writes the file. `$CODEX_HOME/auth.json` if `CODEX_HOME` is set. On macOS `pbcopy < ~/.codex/auth.json` copies it |
-| "a GLM key", "Z.ai", "a GLM coding plan" | GLM, an API key | the provider's API key | from the provider's console |
-| "a Qwen key", "Alibaba Model Studio", "a Qwen coding plan" | Qwen, an API key | the provider's API key | from the provider's console |
-
-A plain Anthropic or OpenAI API key is not something the page can enrol today. If that is what they have, say so in one sentence and ask whether they also have one of the four above. Do not improvise a way in.
-
-Codex has one more thing to say, before they paste: Catalyst takes over that login. Its refresh token is single-use, so the copy on their machine stops working once Catalyst uses it. To keep using Codex locally, they sign in again afterwards, separately.
-
-## Enrolling one
-
-Enrolling is a browser step, by construction: the person pastes a credential into a write-only field, and nothing you run ever sees it.
-
-1. Hand over the page the script printed for the part (Settings → AI accounts). Say: "Choose the provider, give the account a label you will recognise, and paste the credential the page asks for. Nothing on this side sees it."
-2. Wait. Do not run anything while they are on the page.
-3. When they say it is saved, run `node scripts/where-am-i.mjs` and read them the `coding accounts` part. An enrolled and active account, named by its label, is proof. If the part still says none is enrolled, refresh the contract once (`catalyst contract --refresh`) and read it again.
-
-Only a workspace owner or admin can enrol one (the page still says "tenant" in places). If the person is neither, say who can, and stop this step there.
-
-## Naming accounts
-
-Call an account what the page calls it: its label, else its email, else its slot. `catalyst accounts --json` carries this as `displayName`. Never call one "the first account" or "account 2", and never read out a credential.
-
-## An account that already exists
-
-The script reads each enrolled account. Read it back in their words:
-
-- **Active, or attested.** "Your Claude account, Work laptop, is enrolled and can take work." Move on.
-- **Out of rotation.** Every account is deactivated. Reactivate one on its own page. Never enrol another.
-- **Needs a new credential.** Quarantined, expired or revoked, or its last polls failed on the credential itself. Replace the credential on that account's own page, with a credential from that same login. The steps, and the login check that has to come first, are in `references/replacing-a-credential.md`. Never enrol a second account for this.
-- **Cancelled or ended.** The subscription was cancelled, or the provider ended the account. Say so in one clause and move on: it stays for reporting, it is not used, and it is not counted against setup. Never paste a token from another login into it, which would put a live account's credential onto a dead slot, and never tell them to retire or delete it. If the subscription comes back, they reactivate it on its own page.
-- **Could not be read.** Say the accounts could not be read this time and read again later. It is not "no accounts". Do not tell them to enrol one on this reading.
-
-## When more than one is right
-
-One account is enough to start. A second one, on a different provider or plan, gives the router somewhere to go when the first is at its limit. Offer it as a later improvement, not as a step now.

package/skills/catalyst-onboard/references/who-fixes-what.md

@@ -1,64 +0,0 @@
-# Who fixes what
-
-Setup is eight parts. Each has one instrument, and each instrument answers about its own part and nothing else. Read this before you tell a person that something is not ready, and before you tell them to do anything about it. The product's words for what they own are Workspace, Project, Repository, Integration, Connected account and Member; the parts below are the instruments' names for the same things.
-
-## The eight parts, and the instrument that owns each
-
-| part | instrument | what a pass proves | what it does **not** prove | who fixes a failure, and where |
-| -- | -- | -- | -- | -- |
-| **machine** | `catalyst status`, and the non-team checks of `catalyst ready` | Node is new enough, this machine holds a credential, the CLI is where the config says, the contract is cached, the skills are on disk | anything at all about the tenant | the person at this keyboard, here |
-| **person** | `catalyst me`, and `catalyst connections personal <linear|github> status` | the credential resolves to this person, shows their role and Linear identity match, and reports each personal grant's state | that their seat is active, or that they may change tenant settings | the member approves missing or expired personal grants in a browser; an owner or admin handles seat or identity conflicts in Settings → Members |
-| **account** | `catalyst contract --path account` | a resolved Linear workspace means the tenant's Linear grant landed | that the GitHub App is installed — the contract does not carry it | a tenant owner or admin, `<their cloud>/settings/connections` |
-| **project** | `catalyst team list`, then `team check <KEY>` and the `team:` checks of `ready` for the selected team | the live team list and the selected team's latest readiness verdict | that an unchecked team is ready | a tenant owner or admin, through `catalyst team` or `<their cloud>/settings/linear-teams` |
-| **repository** | `catalyst contract --path merge.repositories` | the repository is registered to the account | that it is active, that a project can dispatch into it, or that its environment is declared | a tenant owner or admin, `<their cloud>/settings/repositories` |
-| **coding accounts** | `codingAccounts` in `catalyst contract` (`catalyst accounts` on an older cloud) | an account is enrolled and active | that it has headroom left for the next phase | the enroller and page the contract names; see `references/what-a-phase-needs.md` |
-| **repository declarations** | the `environment_declared` check in `catalyst contract --path teams`, and its per-repository notes | the project's default repository has a committed `.catalyst/catalyst.toml` in effect: ingested, valid, and its latest revision approved | that the values the names refer to exist; that any other repository is declared, unless its note says so | the person, with you, in the repository for the file; a tenant owner or admin for the approval, at the repository's Environment page under `<their cloud>/settings/repositories` |
-| **host** | the `hosts_current` check in `catalyst contract --path teams` | no host is missing or behind, or the tenant runs none | anything before a project has been checked | the owner the contract names for `hosts_current`; see `references/what-a-phase-needs.md` |
-
-`node scripts/where-am-i.mjs` runs all eight, in the order a person can act on them, and labels each finding with its part. Use it rather than composing this by hand.
-
-## The two silences that are not absences
-
-⛔ **An empty contract project list means nothing is mapped yet — it does not mean they have no projects.** The tenant contract carries a project only once someone has saved a stage mapping for it. Read the available team list with `catalyst team list`, choose one, then go to step 4. `team check --all` performs readiness checks and may create asks for every team.
-
-⛔ **A registered repository is not a dispatchable one.** The contract's repository list carries no status and no project attachment, so a paused repository and an active one look identical there, and a repository registered without a project attached looks exactly like a correctly attached one. Registration is all it proves. If a card does not start, `catalyst explain <ticket>` names the real reason; do not conclude anything about the repository from its presence in a list.
-
-⭐ And the general form of both: **an instrument that answers about a part it does not own will answer confidently and wrongly.** When you are unsure which part something belongs to, look it up in the table above rather than guessing from the wording of an error.
-
-## Triaging NOT READY
-
-`catalyst ready` prints one verdict over every check, machine and project together. That single verdict is correct for "can work run?" and useless for "what should I do now?", because it folds two parts into one word. Split it before you act:
-
-1. Run `catalyst ready --json`. Every check has an `id`.
-2. A check whose id begins with `team:` is a **project** finding. Everything else is a **machine** finding.
-3. Report the two groups separately, in that order, each with its own owner.
-
-- **A machine check failed.** This is the person's, here, now. Each failing check carries its own `fix` line; read it and do it. A missing or partial skill set is `catalyst install`; a stale contract is `catalyst contract --refresh`; a missing CLI path is one more `catalyst login`.
-- **A project check failed.** Name the check, the project, and the owner; the `who` field carries the workspace's own owners and admins. An admin or owner can run the check, preview a stage mapping, or adopt the workflow through `catalyst team`; some failures still need provider consent or a browser action, and `<their cloud>/settings/linear-teams` is where those live. Use the check's reason to choose the next action. Re-running `ready` alone does not fix it.
-- **A check is a note.** Notes never move the verdict. A stale or absent replica or event cache is optional; an unknown freshness probe means the cloud comparison could not be proved. A check that has never been run is waiting, not failing; a check the engine could not run is unknown, which is not a pass and not a failure. Say which it is. The API-backed skills still work; ask before starting the optional writer.
-
-## When to stop rather than continue
-
-- **They have no account yet.** There is no self-serve sign-up. Coalesce Labs provisions each account, and a person joins one by invitation from its admin. Say so and stop; the next step is theirs.
-- **The account is suspended.** Setup cannot proceed and no retry changes that. Say so and name the conversation they need to have.
-- **Their seat is not active, or they are not an owner or admin where one is required.** Say who is, and what to ask for. Do not offer a workaround.
-- **A page said it worked and the instrument still disagrees.** Refresh the contract once (`catalyst contract --refresh`) and read it again. If it still disagrees, report both facts — what the page said and what the instrument says — and let the person decide. Do not pick one for them.
-
-## What still happens in a browser, and why
-
-Every step a key can do, the guide does. These are the ones it hands over, each with the reason; when a reason stops being true, the step moves to the CLI and this table changes in the same release.
-
-| step | today | why it is still the person's |
-| -- | -- | -- |
-| install Node, or a coding agent | the person, on their machine | outside the CLI |
-| approve the login | the code and URL `login` prints, in a browser | a grant only the person can give |
-| connect the Linear integration | Settings → Connections | an OAuth grant, by construction |
-| install the GitHub App | Settings → Connections | an OAuth grant, by construction |
-| enrol a coding account, or replace its credential | Settings → AI accounts | the credential is theirs to paste; a CLI verb for the paste is being built |
-| register a repository to a project | Settings → Repositories | the route exists; the CLI verb is being built |
-| approve one repository's settings file | the repository's Environment page | the route for a key is being built |
-| enter a secret's value | the repository's Environment page, or `secret set` | a value never passes through the agent |
-| the person's own Linear and GitHub connected accounts | the link `connections personal … start` prints | a grant only the person can give |
-| move the first ticket | Linear, or `write state` when they ask | their call which ticket runs first |
-
-A project's readiness check, its stage mapping and adopting the workflow are CLI steps (`team check`, `team map`, `team adopt`) when `catalyst capabilities` says the installed CLI can run them for the person's role; the script names the command, and the page only for a person whose role cannot.

package/skills/catalyst-setup/SKILL.md

@@ -1,36 +0,0 @@
----
-name: catalyst-setup
-description: >-
-  Am I set up? Machine readiness (Node, the tenant connection, the cached contract, the CLI path, the skills, the SDK, the optional replica) plus tenant readiness from the contract's per-team checks, in one verdict: what passes, what is blocked, what is merely waiting, and who can click what. Use when someone asks "am I set up", "what is missing", "why does nothing happen", "is the replica running", or right after connecting a new machine. Reports; never repairs.
-allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
----
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.5 — written in this repository for customer tenants -->
-
-# Am I set up?
-
-You answer one question with one verdict and one list. The verdict is READY or NOT READY. The list is who can click what: the fixes only the person at the keyboard can make, the fixes only a tenant owner or admin can make in settings, and the checks that are simply waiting for the first event. The live check ids, severities, states and the people who can answer come from the contract; the scripts print them, you never restate them.
-
-This readiness skill is part of `catalyst-cloud-skills` and checks tenant setup and operation. Coding workflow skills are a separate pack, `catalyst-dev-skills`. Do not direct a person to the deprecated local runtime or its `catalyst-dev@catalyst` plugin.
-
-## Run first
-
-- `node scripts/check.mjs --help` — every machine and tenant check, one line each, the fix and who for each failure, the verdict, then the who-can-click-what list. Exit 1 when NOT READY.
-- `node scripts/replica-status.mjs --help` — the optional replica's verdict with no network (add `--probe` for how far behind it is). Exit 0 fresh, 1 stale, 2 not connected, 3 absent.
-
-## Load on demand
-
-| when | read |
-| -- | -- |
-| any check is red, unknown or waiting and the person asks what it proves, how to fix it, or who can | `references/what-each-check-means.md` |
-| the person asks how to install, update, or migrate Catalyst skills | `../catalyst-onboard/references/skill-sources.md` |
-
-## Rules
-
-- Report, never repair. No tenant-reachable repair verb exists for a key yet; the settings page is where a tenant owner or admin fixes a mapping, a connection or a label, and you say which one.
-- End every answer with the verdict and the who-can-click-what list, in that order.
-- A stale or absent replica is a note, never a failure: every skill reads the API meanwhile and says so. Do not tell the person to start it unless they want local SQL or cheaper repeated reads.
-- Not connected (exit 2) means the connect step, not a retry: `npx @catalyst-cloud/catalyst-skills login`, which logs the person in keyless in their browser; with a personal key from Settings → API keys instead, prefix it with `CATALYST_CLOUD_TOKEN=<your personal key>`. Never guess a tenant; the login (or the key) is the only selector.
-- Waiting is not failing. "No write observed", "no delivery observed" and "no host connected" clear themselves the first time the thing happens; say that instead of raising them.
-- Unknown is not a pass. A check the engine could not run is reported as such, never rounded up.
-- **Give numbers and a time.** Say how many are `pass`, `fail` and `unknown`, and when the team verdicts were computed: `readiness.checkedAt` per team on the contract, null when no pass has run.
-- Never run a check in a loop. If the person wants to know when a waiting check clears, that is the project-running skill's watch.

package/skills/catalyst-setup/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "Am I set up?"
-  short_description: "Machine and tenant readiness in one verdict: what passes, what is blocked, and who can click what"
-  default_prompt: "Use $catalyst-setup to tell me whether this machine and my tenant are ready, and what is missing."
-policy:
-  allow_implicit_invocation: true

package/skills/catalyst-setup/agents/portability.yaml

@@ -1,4 +0,0 @@
-identity: { pack: catalyst-cloud-skills, skill: catalyst-setup }
-effects: []
-invocation: implicit
-exposure: [catalog]