@catalyst-cloud/cli 0.13.0 → 0.14.0

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

@@ -1,70 +1,46 @@
-# Why is it stuck
-
-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; "who acts" names who does — the person, with their own login; a tenant owner or admin, in settings; an operator; or "no one acts", which is a fourth honest answer, not a gap. 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.
-
-## Reasons that release themselves
-
-| reason | what it means | how it clears | 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` | no one acts |
-| `lease_held` | a live container already holds this phase | the phase finishes | no one acts |
-| `intake_lease_held` | a later phase is offered while an intake container still holds the ticket | intake finishes | no one acts |
-| `later_phase_lease_held` | an earlier phase is offered while a live container still holds a later phase of this ticket | the later phase finishes | no one acts |
-| `environment_check_running` | the repository's environment check is in flight | the check finishes | no one acts |
-| `claim_storm` | this unit was claimed too many times in the last hour | it waits the hour out; there is nothing to release | no one acts |
-| `repo_at_capacity` | the repository's runner seats are all in use | it starts when a seat frees | no one acts |
-| `runner_image_breaker` | fleet-wide: the live runner image fails every phase at startup, so dispatch is held rather than parking tickets | an operator moves the pin; one alert per tenant, no per-ticket action | an operator |
-| `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 | usually no one acts; if it persists, a tenant owner or admin, in settings, checks coding accounts |
-| `cooling_down` (with a named callback) | the phase is parked on a condition the cloud watches | the callback fires; the `detail` names it | no one acts; an operator can release it directly if the callback stalls |
-| `no_branch_to_remediate` / `branch_missing` | a branch-dependent phase has no branch yet | the cloud releases these parks on its own budget | no one acts |
-| `stale_failure_episode` | the ladder advanced after the recorded failure, so the round would repair a phase already passed | the round is dropped automatically; the reason is informational | no one acts |
-| `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 | 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 person, with their own login, answers the ask (`what-needs-me`) |
-| `ask_shape_suspected` | its own text reads as a decision request though it carries no ask label | the person, with their own login, 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; when the blocker is an ask, that is the person, with their own login |
-| `not_at_dispatch_stage` | the card is not in the team's dispatch column | the person, with their own login, 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 person, with their own login, returns the card to the pr slot; an automation that bounced it should be found |
-| `no_change_hold` | a repair round changed nothing | the person, with their own login, comments on the ticket or pushes to the branch |
-| `waiting_on` | a merge-gate failure with no cause the cloud can repair | the person, with their own login, reads the merge-wait comment on the ticket; usually a hold label or a review they must give (`catalyst-github`) |
-| `externally_claimed` | a worker outside the cloud holds it | that worker releases it, or the person, with their own login, removes the local-lane label |
-| `environment_check_required` | the repository's environment check has not run | a tenant owner or admin, in settings, runs the environment check |
-| `environment_check_failed` | the repository's environment check failed | a tenant owner or admin, in settings, fixes and reruns the environment check |
-| `environment_check_expired` | the environment check's verdict aged out | a tenant owner or admin, in settings, reruns the environment check |
-| `environment_check_hash_mismatch` | the environment changed since its recorded verdict | a tenant owner or admin, in settings, reruns the environment check |
-| `repo_paused` | an operator paused the repository | an operator resumes it |
-| `scope_overlap` | its declared file scope intersects a ticket already in flight | the person, with their own login, decides which goes first, or waits for the other ticket |
-| `human_owned_pr` | a person's own pull request holds the ticket | the person, with their own login, closes or merges that pull request, or hands it to Catalyst; never close someone's pull request for them. No release clears this one — the release command refuses it terminally — so do not route it to `unstick` expecting one |
-| `review_not_converging` | review and repair kept finding new problems without converging | the person, with their own login, reads the findings (`catalyst-github`) and comments on the ticket to resume; raise an ask for that read. No release clears this one — the release command refuses it terminally — so do not route it to `unstick` expecting one |
-| `round_threshold` | the ticket spent its lifetime repair budget | the person, with their own login, answers the ask the cloud already raised, or pushes a fix; point at that ask rather than raising a second one. No release clears this one — the release command refuses it terminally — so do not route it to `unstick` expecting one |
+# Eligibility reasons
+
+Use explain.mjs; unknown reasons stay verbatim. Holds: when-a-phase-fails.md.
+
+## Automatic release
+
+Automatic waits, where no one acts: `retry_backoff`, `lease_held`, `intake_lease_held`, `later_phase_lease_held`, `environment_check_running`, `claim_storm`, `repo_at_capacity`, `stale_failure_episode`, `no_branch_to_remediate` or `branch_missing`. These cover backoff, leases, environment checks, hourly claim throttling, occupied seats, obsolete repair and budgeted missing-branch release.
+
+| reason | release and actor |
+| -- | -- |
+| `runner_image_breaker` | an operator moves faulty startup image pin; one fleet alert |
+| `routing_unavailable` | kickoff route/slot/provider failure; recovery clears it; persistence needs a workspace owner or admin, in settings |
+| `cooling_down` with callback | cloud watches detail's condition; no one acts unless stalled, then own-login release through unstick |
+| `wip_limit` | no one acts on this ticket; project at limit; started work must finish; inspect those tickets' own reasons |
+
+## Human action
+
+| reason | meaning and action |
+| -- | -- |
+| `ask_ticket` | the person, with their own login: labelled question, never work; answer through what-needs-me |
+| `ask_shape_suspected` | the person, with their own login: unlabelled decision text; answer or apply contract release label |
+| `blocked` | blocker owner closes it; for an ask, the person, with their own login, answers |
+| `not_at_dispatch_stage` / `not_at_pr_stage` | the person, with their own login: restore dispatch/PR slot respectively; for PR, fix bouncing automation |
+| `no_change_hold` | the person, with their own login: unchanged repair; comment/push/unstick |
+| `waiting_on` | the person, with their own login: unrepairable PR merge gate; read merge-wait comment for hold/review owed, using catalyst-github |
+| `externally_claimed` | the person, with their own login: outside worker owns it; worker/person removes local-lane label |
+| `environment_check_required` / `environment_check_failed` / `environment_check_expired` / `environment_check_hash_mismatch` | absent/failed/aged/changed environment check; a workspace owner or admin, in settings, runs or fixes it |
+| `repo_paused` | an operator resumes repository |
+| `scope_overlap` | the person, with their own login: declared files overlap running work; choose order or wait |
+| `human_owned_pr` | the person, with their own login: only its human owner closes, merges or hands it over; release refused |
+| `review_not_converging` | the person, with their own login: read findings through catalyst-github, comment; release refused |
+| `round_threshold` | the person, with their own login: lifetime repair budget spent; answer existing ask or push fix, never duplicate ask; release refused |
 
 ## Reasons a release clears once the cause is fixed
 
-These do not release themselves: 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.
-
-| reason | what it means | note | who acts |
-| -- | -- | -- | -- |
-| `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 | the person, with their own login |
-| `remediate_parked` | the repair phase itself is parked, so the failing phase has nowhere to be repaired | as above | the person, with their own login |
-| `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` | the person, with their own login |
-| `branch_gone` | a branch that existed was deleted | the person, with their own login, decides whether to recreate it or drop the ticket | the person, with their own login |
-
-## Reasons that are not problems
+After a fix, the person, with their own login, routes `phase_parked`, `cooling_down` from failures/round cap, `remediate_parked`, `validate_class_spent` and `branch_gone` to `unstick`. Read history, preview release; recreate deleted branches or drop tickets. Validate-budget also clears by push/comment/ask answer.
 
-`ticket_terminal` (done or canceled), `pipeline_complete` (every phase ran), and `pr_merged` (the PR merged, nothing left to clone) describe finished work; no one acts. Report them as closed, not blocked.
+## Finished
 
-## When the cloud could not judge
+Finished, so no one acts: `ticket_terminal`, `pipeline_complete` and `pr_merged`; report them as closed.
 
-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.
+## Inconclusive
 
-## The one advisory
+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 unreadable, never absent. Usually recovered next pass. `workflow_mapping_unknown` does not clear without a saved mapping; nor does accompanying `ordering_never_published`. Remap with `catalyst team map <KEY>` as owner/admin; other persistent unknowns need catalyst-onboard.
 
-`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` is advisory: list the human-assigned possible ask 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/dist/env/declaration-rules.js

@@ -1,163 +0,0 @@
-// declaration-rules.ts — a vendored, dated copy of catalyst-cloud's rules for a repo-scope
-// `catalyst.env.json`, applied by `validateRepoEnvironmentDeclaration`
-// (packages/environment/src/contract.ts:416-493 on catalyst-cloud `main`; the ticket cites line 488,
-// which falls inside that range). That file lives in the PRIVATE `coalesce-labs/catalyst-cloud`
-// monorepo — no sibling checkout, no npm publication (its one customer, `apps/cli`, is itself
-// "private": true) and no network reachability from this session. Everything below is vendored
-// secondhand from two independent, dated thoughts-pool research passes (2026-09-10 and 2026-09-17)
-// that agreed with each other, following the same idiom this repository's own
-// `test/skills-content.test.ts` already uses to vendor catalyst-cloud's `READINESS_CHECK_IDS` (see
-// that file's `TEAM_CHECK_IDS` and its provenance comment): dated, cited, paired with a test, never
-// hand-copied and trusted on its own.
-//
-// What a parity test built against THIS copy can, and cannot, catch: it can catch this copy DRIFTING
-// FROM ITSELF — a rule dropped, loosened or tightened by a future edit here. It CANNOT notice a new
-// rule landing upstream, because nothing in this repository imports the real function — there is no
-// publish channel for it. The one fixture pinned by a real, run command transcript rather than by
-// prose (`valid-empty-provenance.json`, in `test/fixtures/env-declaration/`) is the strongest anchor
-// this vendored copy has; the rest are pinned by the two agreeing research passes.
-const MAX_ENV_REFS = 128;
-const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
-// ⛔ A PREFIX ONLY COUNTS AT A TOKEN BOUNDARY (validate attempt 29, CR-6). These were matched with
-// `text.includes(p)`, and "sk-" is a SUBSTRING of "task-", "risk-" and "disk-" — so a declaration
-// whose setup step was `["npm","run","task-build"]` was refused as containing secret material. Every
-// prefix here is identifier-shaped, so a match is real only at the start of the text or after a
-// character that cannot be part of a token; PEM armour, which is not identifier-shaped and carries
-// its own unmistakable delimiter, keeps a plain substring match of its own.
-// `gho_`, `sk_live_` and `AIza` are in the 2026-09-10 pass's list of upstream's prefixes
-// (thoughts: repos/catalyst/shared/research/2026-09-10-CTC-2020-laptop-environment-inventory.md:65),
-// and `ghs_` is pinned as an upstream entry by the 2026-09-27 CTC-3378 plan v2 (:238). Validate
-// attempt 31 found the first three missing here (and noted `ghs_`), so `env check` said `valid`
-// where upstream's validator refuses.
-// That upstream list ends "and others": this copy still cannot claim to hold every entry.
-const KNOWN_SECRET_PREFIXES = ["ghp_", "gho_", "ghs_", "github_pat_", "sk-", "sk_live_", "AKIA", "AIza", "xoxb-", "xoxp-"];
-const PEM_ARMOUR = "-----BEGIN";
-const KNOWN_SECRET_PREFIX_RE = new RegExp(`(?:^|[^A-Za-z0-9_])(?:${KNOWN_SECRET_PREFIXES.map(escapeForRegExp).join("|")})`);
-function escapeForRegExp(literal) {
-    return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-const SECRET_ASSIGNMENT_RE = /\b([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(\S{4,})/g;
-const SECRET_NAME_RE = /(_TOKEN|_SECRET|_KEY|_PASSWORD|_CREDENTIAL)$|^(TOKEN|SECRET|PASSWORD)$/i;
-const REQUIRED_ARRAY_FIELDS = ["toolchains", "systemPackages", "setup", "verify", "services", "environment", "agentAssets", "provenance"];
-const TOP_LEVEL_FIELDS = new Set(["version", ...REQUIRED_ARRAY_FIELDS]);
-/** Empty array = valid. Never reads, and never returns, a value — only field names and paths. */
-export function validateDeclaration(doc) {
-    if (typeof doc !== "object" || doc === null || Array.isArray(doc)) {
-        return ["the declaration must be a JSON object"];
-    }
-    const rec = doc;
-    const errors = [];
-    for (const key of Object.keys(rec))
-        if (!TOP_LEVEL_FIELDS.has(key))
-            errors.push(`unknown key "${key}"`);
-    if (rec.version !== 1)
-        errors.push("version must be 1");
-    for (const field of REQUIRED_ARRAY_FIELDS)
-        if (!Array.isArray(rec[field]))
-            errors.push(`${field} must be an array`);
-    // The rules below assume the shape above holds; a missing/wrong-typed field is reported on its own.
-    if (errors.length > 0)
-        return errors;
-    const environment = rec.environment;
-    if (environment.length > MAX_ENV_REFS)
-        errors.push(`environment has ${environment.length} entries; at most ${MAX_ENV_REFS}`);
-    for (const [i, e] of environment.entries()) {
-        if (typeof e !== "object" || e === null) {
-            errors.push(`environment[${i}] must be an object`);
-            continue;
-        }
-        const rec2 = e;
-        if (typeof rec2.name !== "string" || !ENV_NAME_RE.test(rec2.name))
-            errors.push(`environment[${i}].name is not a valid name`);
-        if (typeof rec2.required !== "boolean")
-            errors.push(`environment[${i}].required must be a boolean`);
-        if (!Array.isArray(rec2.provenanceIds))
-            errors.push(`environment[${i}].provenanceIds must be an array`);
-    }
-    for (const field of ["setup", "verify"]) {
-        for (const [i, s] of rec[field].entries()) {
-            if (typeof s !== "object" || s === null) {
-                errors.push(`${field}[${i}] must be an object`);
-                continue;
-            }
-            const rec2 = s;
-            const command = rec2.command;
-            if (!Array.isArray(command) || command.length === 0 || !command.every((c) => typeof c === "string")) {
-                errors.push(`${field}[${i}].command must be an argv array (a bare shell string is refused; ["sh","-lc", …] is the explicit escape)`);
-            }
-            if (typeof rec2.timeoutSeconds !== "number")
-                errors.push(`${field}[${i}].timeoutSeconds must be a number`);
-            if (!Array.isArray(rec2.provenanceIds))
-                errors.push(`${field}[${i}].provenanceIds must be an array`);
-        }
-    }
-    // C-2: services / provenance / agentAssets had no element check at all, so a non-object element
-    // reached the free-text sweep below and threw instead of being reported. The rule is the same one
-    // `environment` and `setup`/`verify` already apply: an element that is not an object is an error.
-    for (const field of ["services", "provenance", "agentAssets"]) {
-        for (const [i, e] of rec[field].entries()) {
-            if (typeof e !== "object" || e === null || Array.isArray(e))
-                errors.push(`${field}[${i}] must be an object`);
-        }
-    }
-    // assertNoSecretMaterial, LAST — a value-SHAPE refusal over every free-text field (argv strings,
-    // service image names, provenance explanations, agent-asset references), never a classifier over
-    // environment[].name: there is nothing to classify there. The refusal names the FIELD, never the
-    // matched text, so this function never prints what it found.
-    for (const { path, text } of collectFreeText(rec)) {
-        if (text.includes(PEM_ARMOUR) || KNOWN_SECRET_PREFIX_RE.test(text)) {
-            errors.push(`${path} appears to contain secret material (matches a known credential prefix)`);
-            continue;
-        }
-        SECRET_ASSIGNMENT_RE.lastIndex = 0;
-        let m;
-        while ((m = SECRET_ASSIGNMENT_RE.exec(text))) {
-            if (SECRET_NAME_RE.test(m[1])) {
-                errors.push(`${path} appears to contain secret material (an assignment shaped like a secret name)`);
-                break;
-            }
-        }
-    }
-    return errors;
-}
-function collectFreeText(rec) {
-    const out = [];
-    for (const field of ["setup", "verify"]) {
-        for (const [i, s] of rec[field].entries()) {
-            const rec2 = asRecord(s);
-            if (rec2 === null)
-                continue;
-            if (Array.isArray(rec2.command)) {
-                for (const c of rec2.command)
-                    if (typeof c === "string")
-                        out.push({ path: `${field}[${i}].command`, text: c });
-            }
-        }
-    }
-    for (const [i, s] of rec.services.entries()) {
-        const rec2 = asRecord(s);
-        if (rec2 === null)
-            continue;
-        if (typeof rec2.image === "string")
-            out.push({ path: `services[${i}].image`, text: rec2.image });
-    }
-    for (const [i, p] of rec.provenance.entries()) {
-        const rec2 = asRecord(p);
-        if (rec2 === null)
-            continue;
-        if (typeof rec2.explanation === "string")
-            out.push({ path: `provenance[${i}].explanation`, text: rec2.explanation });
-    }
-    for (const [i, a] of rec.agentAssets.entries()) {
-        const rec2 = asRecord(a);
-        if (rec2 === null)
-            continue;
-        if (typeof rec2.reference === "string")
-            out.push({ path: `agentAssets[${i}].reference`, text: rec2.reference });
-    }
-    return out;
-}
-/** An element the caller may safely read properties off, or null — a non-object is reported above. */
-function asRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
-}

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.