@catalyst-cloud/catalyst-skills 0.4.0 → 0.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@catalyst-cloud/catalyst-skills",
-  "version": "0.4.0",
-  "description": "Customer skill bundle for Catalyst Cloud: eight skills named from the executive's seat (whats-happening, what-needs-me, run-this-project, catalyst-setup, catalyst-linear, catalyst-github, how-catalyst-works, connect-me) plus the catalyst-skills CLI that reads through the Catalyst Cloud SDK, writes through the agent proxy, and connects your machine to your tenant with one command.",
+  "version": "0.5.0",
+  "description": "Customer skill bundle for Catalyst Cloud: nine skills named from the executive's seat (whats-happening, what-needs-me, run-this-project, unstick, catalyst-setup, catalyst-linear, catalyst-github, how-catalyst-works, connect-me) plus the catalyst-skills CLI that reads through the Catalyst Cloud SDK, writes through the agent proxy, and connects your machine to your tenant with one command.",
   "license": "MIT",
   "type": "module",
   "publishConfig": {
@@ -38,10 +38,11 @@
     "prepare": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "version:sync": "node scripts/sync-plugin-version.mjs"
+    "version:sync": "node scripts/sync-plugin-version.mjs",
+    "skill-lib:sync": "node scripts/sync-skill-lib.mjs"
   },
   "dependencies": {
-    "@catalyst-cloud/sdk": "^0.9.0"
+    "@catalyst-cloud/sdk": "^0.10.0"
   },
   "devDependencies": {
     "@types/node": "^26.3.0",

package/skills/catalyst-github/scripts/lib/cli.mjs

@@ -8,9 +8,10 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
 export const PACKAGE = "@catalyst-cloud/catalyst-skills";
-export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE} login`;
+export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: ${CONNECT_COMMAND}`;
 
 /** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME before HOME. */
 export function configPath() {
@@ -32,7 +33,7 @@ export function requireCustomerConfig() {
     console.error(`${path} could not be read (${err instanceof Error ? err.message : String(err)}) — ${CONNECT_HINT}`);
     process.exit(2);
   }
-  if (!cfg || typeof cfg !== "object" || typeof cfg.key !== "string" || typeof cfg.baseUrl !== "string") {
+  if (!hasCredential(cfg) || typeof cfg.baseUrl !== "string") {
     console.error(`${path} is missing required fields — ${CONNECT_HINT}`);
     process.exit(2);
   }

package/skills/catalyst-github/scripts/lib/credential.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// lib/credential.mjs — is this machine connected? The ONE place a skill script decides it, vendored
+// byte-identical into every skill's scripts/lib/ from skill-lib/credential.mjs at the package root
+// (`npm run skill-lib:sync`; a test fails on any drift). Skills install one directory at a time, so
+// each carries its own copy. This file is a library — run a sibling script with --help for usage.
+//
+// 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
+// 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)";
+
+/** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
+export function hasCredential(cfg) {
+  if (cfg === null || typeof cfg !== "object") return false;
+  const key = cfg["key"];
+  if (typeof key === "string" && key !== "") return true;
+  const login = cfg["auth"];
+  return (
+    login !== null &&
+    typeof login === "object" &&
+    login["kind"] === "oauth" &&
+    typeof login["refreshToken"] === "string" &&
+    login["refreshToken"] !== ""
+  );
+}

package/skills/catalyst-linear/scripts/lib/cli.mjs

@@ -6,9 +6,10 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
 export const PACKAGE = "@catalyst-cloud/catalyst-skills";
-export const CONNECT_HINT = `CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE} login`;
+export const CONNECT_HINT = CONNECT_COMMAND;
 
 /** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME (used by tests) over HOME. */
 export function configPath() {
@@ -22,8 +23,8 @@ export function loadConfig() {
   if (!existsSync(path)) return { ok: false, reason: `no config at ${path}` };
   try {
     const cfg = JSON.parse(readFileSync(path, "utf8"));
-    if (!cfg || typeof cfg.key !== "string" || typeof cfg.account !== "string") {
-      return { ok: false, reason: `${path} is missing the key or account` };
+    if (!hasCredential(cfg) || typeof cfg.account !== "string") {
+      return { ok: false, reason: `${path} is missing a key or login, or the account` };
     }
     return { ok: true, cfg, path };
   } catch (err) {

package/skills/catalyst-linear/scripts/lib/credential.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// lib/credential.mjs — is this machine connected? The ONE place a skill script decides it, vendored
+// byte-identical into every skill's scripts/lib/ from skill-lib/credential.mjs at the package root
+// (`npm run skill-lib:sync`; a test fails on any drift). Skills install one directory at a time, so
+// each carries its own copy. This file is a library — run a sibling script with --help for usage.
+//
+// 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
+// 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)";
+
+/** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
+export function hasCredential(cfg) {
+  if (cfg === null || typeof cfg !== "object") return false;
+  const key = cfg["key"];
+  if (typeof key === "string" && key !== "") return true;
+  const login = cfg["auth"];
+  return (
+    login !== null &&
+    typeof login === "object" &&
+    login["kind"] === "oauth" &&
+    typeof login["refreshToken"] === "string" &&
+    login["refreshToken"] !== ""
+  );
+}

package/skills/catalyst-setup/SKILL.md

@@ -26,7 +26,7 @@ You answer one question with one verdict and one list. The verdict is READY or N
 - 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: `CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login`, with the person's own key from Settings → API keys. Never guess a tenant; the key is the only selector.
+- 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.
 - 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/references/what-each-check-means.md

@@ -37,7 +37,7 @@ Three checks are informational by design (labels, event delivery, host currency)
 | id | proves | fix |
 | -- | -- | -- |
 | `node` | Node 22 or newer, which the SDK's built-in SQLite engine needs | install Node 22+ |
-| `config` | this machine is connected: `customer.json` exists and loads | `CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login`; the person mints the key at Settings → API keys |
+| `config` | this machine is connected: `customer.json` exists and loads | `npx @catalyst-cloud/catalyst-skills login` (keyless: the person approves in their browser); or, with a personal key minted at Settings → API keys, the same command prefixed with `CATALYST_CLOUD_TOKEN=<your personal key>` |
 | `contract` | the tenant contract is cached and its major version is one this bundle accepts | `catalyst-skills contract --refresh`; a version outside the range means update the bundle. A 403 naming an older cloud means the cloud has not yet deployed personal-key access |
 | `cliPath` | the CLI path recorded at login still exists, so skill scripts can spawn it | re-run login |
 | `skills` | every skill of this bundle is present where the CLI installed them | `catalyst-skills install` |
@@ -60,3 +60,7 @@ Three checks are informational by design (labels, event delivery, host currency)
 ## Who can click what
 
 The last block `check.mjs` prints groups every failure by the person it needs. Machine fixes name "you", the person at the keyboard. Tenant fixes name the owner or admin roles the contract lists (as Linear user ids, since that is how the cloud knows them), because the settings page that repairs a mapping, a connection or a label is theirs. A check the contract marks as not needing an answer names nobody: it is informational or self-clearing. This skill reports; it never repairs, because no key-reachable repair verb exists yet.
+
+## Setting up one team at a time
+
+A team starts receiving work only once its stages are saved, and that is done one team at a time: a tenant owner or admin opens Settings → Linear teams, picks the team and presses Map my stages (or Adopt the Catalyst workflow). No other team's stages or tickets change; only the labels Adopt creates are shared across the workspace. Before saving, the screen lists which of that team's tickets would start and which stay where they are. Once saved, the tickets in the team's dispatch stage start; tickets in other stages that Catalyst never worked on stay where they are. To pilot safely, pick a low-stakes team, move anything in its dispatch stage that should not start back to Backlog, and leave the other teams unmapped. `gitAutomation` in the contract plays no part: nothing reads it.

package/skills/catalyst-setup/scripts/lib/cli.mjs

@@ -8,9 +8,10 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
 export const PACKAGE = "@catalyst-cloud/catalyst-skills";
-export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE} login`;
+export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: ${CONNECT_COMMAND}`;
 
 /** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME before HOME. */
 export function configPath() {
@@ -32,7 +33,7 @@ export function requireCustomerConfig() {
     console.error(`${path} could not be read (${err instanceof Error ? err.message : String(err)}) — ${CONNECT_HINT}`);
     process.exit(2);
   }
-  if (!cfg || typeof cfg !== "object" || typeof cfg.key !== "string" || typeof cfg.baseUrl !== "string") {
+  if (!hasCredential(cfg) || typeof cfg.baseUrl !== "string") {
     console.error(`${path} is missing required fields — ${CONNECT_HINT}`);
     process.exit(2);
   }

package/skills/catalyst-setup/scripts/lib/credential.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// lib/credential.mjs — is this machine connected? The ONE place a skill script decides it, vendored
+// byte-identical into every skill's scripts/lib/ from skill-lib/credential.mjs at the package root
+// (`npm run skill-lib:sync`; a test fails on any drift). Skills install one directory at a time, so
+// each carries its own copy. This file is a library — run a sibling script with --help for usage.
+//
+// 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
+// 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)";
+
+/** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
+export function hasCredential(cfg) {
+  if (cfg === null || typeof cfg !== "object") return false;
+  const key = cfg["key"];
+  if (typeof key === "string" && key !== "") return true;
+  const login = cfg["auth"];
+  return (
+    login !== null &&
+    typeof login === "object" &&
+    login["kind"] === "oauth" &&
+    typeof login["refreshToken"] === "string" &&
+    login["refreshToken"] !== ""
+  );
+}

package/skills/catalyst-setup/scripts/replica-status.mjs

@@ -14,7 +14,7 @@ const HELP = `Usage: node scripts/replica-status.mjs [--probe] [--json]
 Exit codes, passed through from catalyst-skills replica status:
   0  fresh: a live writer, a young heartbeat, a cursor — skills read the replica
   1  stale: the file exists but the writer is gone or behind — skills read the API and say so
-  2  not connected to a tenant — run: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login
+  2  not connected to a tenant — run: npx @catalyst-cloud/catalyst-skills login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login)
   3  absent: no replica file — optional; start one with: catalyst-skills replica start --detach`;
 
 const args = process.argv.slice(2);

package/skills/connect-me/scripts/lib/cli.mjs

@@ -10,6 +10,7 @@ import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
 export const PACKAGE_NAME = "@catalyst-cloud/catalyst-skills";
 export const NOT_CONFIGURED_EXIT = 2;
@@ -33,7 +34,7 @@ export function loadCustomerConfig() {
   if (!existsSync(path)) return null;
   try {
     const parsed = JSON.parse(readFileSync(path, "utf8"));
-    if (!parsed || typeof parsed !== "object" || typeof parsed.key !== "string" || typeof parsed.account !== "string") return null;
+    if (!hasCredential(parsed) || typeof parsed.account !== "string") return null;
     return parsed;
   } catch {
     return null;
@@ -44,7 +45,7 @@ export function loadCustomerConfig() {
 export function requireConfigured() {
   const cfg = loadCustomerConfig();
   if (cfg) return cfg;
-  console.error(`not connected: ${configPath()} is missing or unreadable — run: CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE_NAME} login`);
+  console.error(`not connected: ${configPath()} is missing or unreadable — run: ${CONNECT_COMMAND}`);
   process.exit(NOT_CONFIGURED_EXIT);
 }
 

package/skills/connect-me/scripts/lib/credential.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// lib/credential.mjs — is this machine connected? The ONE place a skill script decides it, vendored
+// byte-identical into every skill's scripts/lib/ from skill-lib/credential.mjs at the package root
+// (`npm run skill-lib:sync`; a test fails on any drift). Skills install one directory at a time, so
+// each carries its own copy. This file is a library — run a sibling script with --help for usage.
+//
+// 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
+// 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)";
+
+/** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
+export function hasCredential(cfg) {
+  if (cfg === null || typeof cfg !== "object") return false;
+  const key = cfg["key"];
+  if (typeof key === "string" && key !== "") return true;
+  const login = cfg["auth"];
+  return (
+    login !== null &&
+    typeof login === "object" &&
+    login["kind"] === "oauth" &&
+    typeof login["refreshToken"] === "string" &&
+    login["refreshToken"] !== ""
+  );
+}

package/skills/how-catalyst-works/references/stages-and-mapping.md

@@ -28,7 +28,7 @@ The contract's `teams[].workflowMode` reports which one a team is in:
 - **mapped**: the team kept its existing stages and a human chose which stage fills each slot.
 - **mixed**: some slots adopted, some hand-chosen.
 
-`teams[].gitAutomation` is a separate switch, off by default, because enabling it can delete a team's own review automation in Linear; it is never bundled into "adopt recommended".
+`teams[].gitAutomation` is a stored consent for a feature that is not built yet (Catalyst managing a team's Linear git automations); nothing reads it, so `off` never stops work and turning it on would start none. What decides whether a team's tickets start is the mapping above: until dispatch, pr, done and canceled each point at a live stage, Catalyst starts nothing in that team, and `explain` says so by name.
 
 ## The state id is the authority; names are display
 

package/skills/how-catalyst-works/references/what-runs-next.md

@@ -66,7 +66,7 @@ No survivor is `no_eligible_account_slot` when any candidate was skipped on capa
 
 ## The unknowns (the evaluator fails closed)
 
-When the cloud cannot answer, it says so rather than guessing: `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`, `branch_snapshot_unknown`. An unknown is "I could not look", never "it is not there"; report it as inconclusive.
+When the cloud cannot answer, it says so rather than guessing: `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`, `branch_snapshot_unknown`. An unknown is "I could not look", never "it is not there"; report it as inconclusive. The exception is a team with no saved stage mapping: `workflow_mapping_unknown` never clears on its own there, `explain` names the missing stages, and the fix is a tenant owner or admin mapping the team.
 
 One advisory gates nothing: `human_addressed_unlabeled_ask_suspect` (assigned to a human with no delegate; possibly an unlabelled ask).
 

package/skills/how-catalyst-works/references/when-a-phase-fails.md

@@ -33,12 +33,12 @@ Which parks release themselves:
 
 | Park | Releases by |
 | -- | -- |
-| repeated failure | an operator, not a clock |
-| remediate round cap reached | an operator, not a clock |
+| repeated failure | a release from the person's own login once its cause is fixed (`catalyst-skills release`), not a clock |
+| remediate round cap reached | the same release, which buys one more round, not a clock |
 | missing branch | its own budgeted release loop |
 | rebase conflict | its own budgeted release loop |
 
-Your key cannot release a park; the repair verbs are operator-only. When a ticket is parked, say so, name the failure class the explainer shows, and hand the release to whoever administers the tenant.
+A person's own key releases a park, and every other hold that a retry can fix, in one step: `catalyst-skills release <ticket> --because <what changed>`. The cloud releases every governor holding the ticket or releases nothing and names what a person must do instead (a person's own pull request, a review that will not converge, the lifetime repair budget). It refuses a cause it cannot see change unless the caller says what changed. The `unstick` skill runs that loop. When a ticket is parked, name the failure class the explainer shows and whether its cause is fixed.
 
 ## Two holds that are not failures
 
@@ -53,5 +53,5 @@ Each attempt posts a phase-outcome comment (complete or FAILED, with phase, atte
 
 1. Run `node scripts/explain-ticket.mjs <ticket>`; the reason names the layer.
 2. `retry_backoff` or `routing_unavailable`: wait; it retries itself. Say when.
-3. `cooling_down`, `remediate_parked`, `no_change_hold`, `validate_class_spent`: name what releases it (an operator, a comment, a push) and who can do that.
+3. `cooling_down`, `remediate_parked`, `no_change_hold`, `validate_class_spent`: name what releases it (a release once the cause is fixed, a comment, a push) and who can do that.
 4. A system-level cause (provider down, runner image breaker, repo paused) is ONE alert, never a per-ticket escalation.

package/skills/how-catalyst-works/scripts/lib/cli.mjs

@@ -6,9 +6,10 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
 export const PACKAGE = "@catalyst-cloud/catalyst-skills";
-export const CONNECT_HINT = `CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE} login`;
+export const CONNECT_HINT = CONNECT_COMMAND;
 
 /** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME (used by tests) over HOME. */
 export function configPath() {
@@ -22,8 +23,8 @@ export function loadConfig() {
   if (!existsSync(path)) return { ok: false, reason: `no config at ${path}` };
   try {
     const cfg = JSON.parse(readFileSync(path, "utf8"));
-    if (!cfg || typeof cfg.key !== "string" || typeof cfg.account !== "string") {
-      return { ok: false, reason: `${path} is missing the key or account` };
+    if (!hasCredential(cfg) || typeof cfg.account !== "string") {
+      return { ok: false, reason: `${path} is missing a key or login, or the account` };
     }
     return { ok: true, cfg, path };
   } catch (err) {

package/skills/how-catalyst-works/scripts/lib/credential.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// lib/credential.mjs — is this machine connected? The ONE place a skill script decides it, vendored
+// byte-identical into every skill's scripts/lib/ from skill-lib/credential.mjs at the package root
+// (`npm run skill-lib:sync`; a test fails on any drift). Skills install one directory at a time, so
+// each carries its own copy. This file is a library — run a sibling script with --help for usage.
+//
+// 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
+// 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)";
+
+/** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
+export function hasCredential(cfg) {
+  if (cfg === null || typeof cfg !== "object") return false;
+  const key = cfg["key"];
+  if (typeof key === "string" && key !== "") return true;
+  const login = cfg["auth"];
+  return (
+    login !== null &&
+    typeof login === "object" &&
+    login["kind"] === "oauth" &&
+    typeof login["refreshToken"] === "string" &&
+    login["refreshToken"] !== ""
+  );
+}

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

@@ -42,4 +42,4 @@ Every script exits 2 when this machine is not connected (run `catalyst-skills lo
 - **Escalate inward.** Instrument, then you, then the desk, then the human as an ask filed through `what-needs-me` with what it blocks. Decide the technical calls yourself; take the sane default and record it; a fleet or provider condition is one note, never one ask per ticket.
 - **Reply where the message arrived,** in-thread, tagged, as the app actor. Never post as the human, never answer someone else's ask. Bookkeeping records take the contract's marker (`catalyst-skills write comment --bookkeeping`).
 - **One status summary,** kept current after every reaction: in flight, blocked and on whom, closed, next, each line with a ticket id. Where a human decision is pending, the line carries the ask's id.
-- **Say what a key cannot see.** A park is released only by an operator, and PR labels and reactions are not mirrored; the CLI says so by name and points at settings. Execution history (`explain --history`) and coding-account status (`accounts`) ARE readable — read them rather than reconstructing them from comments.
+- **Say what a key cannot see.** PR labels and reactions are not mirrored; the CLI says so by name and points at settings. A park or hold is released from the person's own login once its cause is fixed, through the `unstick` skill (`catalyst-skills release`). Execution history (`explain --history`) and coding-account status (`accounts`) ARE readable — read them rather than reconstructing them from comments.

package/skills/run-this-project/references/making-work-ready.md

@@ -48,7 +48,7 @@ The card's stage is the fourth, weakest signal: a completed phase moves the card
 
 ## Parking, and what it does not do
 
-Parking is the lever that stops the cloud offering more rounds on a ticket: moved out of the dispatch column and the ladder's stages, the ticket is excluded at the next offer. It does not kill a phase that is already running under a lease; that container finishes its phase, posts its outcome, and the next offer finds the card parked. If you park a ticket the cloud has itself parked (three consecutive failures, or the remediate round cap), record why in a bookkeeping note; releasing a cloud park is an operator action, not a card move, so that is an ask for a human with the ticket named as what it blocks.
+Parking is the lever that stops the cloud offering more rounds on a ticket: moved out of the dispatch column and the ladder's stages, the ticket is excluded at the next offer. It does not kill a phase that is already running under a lease; that container finishes its phase, posts its outcome, and the next offer finds the card parked. If you park a ticket the cloud has itself parked (three consecutive failures, or the remediate round cap), record why in a bookkeeping note. Releasing a cloud park is not a card move: once its cause is fixed, the `unstick` skill releases it with `catalyst-skills release <ticket>`, and only a refusal that names a person's action becomes an ask.
 
 Un-parking is the same dispatch move again. The counted attempts and rounds do not reset when a card comes back; the contract's thresholds say how many remain.
 

package/skills/run-this-project/references/stalls-and-escalation.md

@@ -26,7 +26,7 @@ Run `catalyst-skills explain <ticket>` first, and let its reason pick the row:
 | blocked | a live blocks relation | chase the blocker: is it dispatchable, is it an ask nobody answered, is it done but still open |
 | ask ticket, ask shape suspected | the ticket is a question | route it to `what-needs-me`; if it is really work, a human applies the release label |
 | not at dispatch stage | somebody moved the card, or it never entered | read the card's history; re-dispatch with `make-ready.mjs` if it should run |
-| cooling down, remediate parked | the cloud parked it after repeated failure or the round cap | read the last outcome card for the class; if the fix is a decision, file an ask; releasing the park is an operator action |
+| phase parked, cooling down, remediate parked | the cloud parked it after repeated failure or the round cap | read the last outcome card for the class; once its cause is fixed, the `unstick` skill releases it (`catalyst-skills release <ticket> --because <what changed>`); if the fix is a decision, file an ask |
 | no change hold | a remediate round changed nothing | a human comment on the ticket, or a new push to the branch, releases it; say what should change |
 | validate class spent, stale failure episode | the repair budget for this failure is used, or the ladder moved on | read the outcome cards; usually a decision about the approach, so an ask |
 | waiting on | a merge-gate failure with no automatic repair | read the merge-wait comment and the PR's three legs through `catalyst-github` |
@@ -52,7 +52,7 @@ Before anything reaches the human, answer three questions:
 2. **Does this need to block at all?** If a sane default exists, take it, record it, and file the ask anyway so the human can overrule; the work does not wait.
 3. **Who else can move this?** Another steward, the desk, a repository owner. Pulling in a peer is preferred over pulling in the human.
 
-Only a genuine product, priority or approval decision, or an action only a human can physically take (release a cloud park, resolve a repository setting, apply the release label, answer a merge policy question), survives to become an ask.
+Only a genuine product, priority or approval decision, or an action only a human can physically take (close a person's own pull request, read a review that will not converge, resolve a repository setting, apply the release label, answer a merge policy question), survives to become an ask.
 
 ## When a stall becomes an ask
 

package/skills/run-this-project/scripts/lib/cli.mjs

@@ -10,6 +10,7 @@ import { spawn } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
 export const PACKAGE_NAME = "@catalyst-cloud/catalyst-skills";
 export const NOT_CONFIGURED_EXIT = 2;
@@ -33,7 +34,7 @@ export function loadCustomerConfig() {
   if (!existsSync(path)) return null;
   try {
     const parsed = JSON.parse(readFileSync(path, "utf8"));
-    if (!parsed || typeof parsed !== "object" || typeof parsed.key !== "string" || typeof parsed.account !== "string") return null;
+    if (!hasCredential(parsed) || typeof parsed.account !== "string") return null;
     return parsed;
   } catch {
     return null;
@@ -44,7 +45,7 @@ export function loadCustomerConfig() {
 export function requireConfigured() {
   const cfg = loadCustomerConfig();
   if (cfg) return cfg;
-  console.error(`not connected: ${configPath()} is missing or unreadable — run: CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE_NAME} login`);
+  console.error(`not connected: ${configPath()} is missing or unreadable — run: ${CONNECT_COMMAND}`);
   process.exit(NOT_CONFIGURED_EXIT);
 }
 

package/skills/run-this-project/scripts/lib/credential.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// lib/credential.mjs — is this machine connected? The ONE place a skill script decides it, vendored
+// byte-identical into every skill's scripts/lib/ from skill-lib/credential.mjs at the package root
+// (`npm run skill-lib:sync`; a test fails on any drift). Skills install one directory at a time, so
+// each carries its own copy. This file is a library — run a sibling script with --help for usage.
+//
+// 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
+// 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)";
+
+/** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
+export function hasCredential(cfg) {
+  if (cfg === null || typeof cfg !== "object") return false;
+  const key = cfg["key"];
+  if (typeof key === "string" && key !== "") return true;
+  const login = cfg["auth"];
+  return (
+    login !== null &&
+    typeof login === "object" &&
+    login["kind"] === "oauth" &&
+    typeof login["refreshToken"] === "string" &&
+    login["refreshToken"] !== ""
+  );
+}

package/skills/unstick/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: unstick
+description: >-
+  Get a stuck Catalyst Cloud ticket moving again. Use when the person asks "why is this parked and can you release it?", "unpark this", "get things flowing again", "the outage is over, retry what failed", or hands you a ticket that is not moving. Reads why nothing runs and what holds the ticket through the catalyst-skills CLI, decides whether the recorded cause is fixed, previews the release, releases every governor holding the ticket the right way (or one failure class across a team), and raises an ask only for what a person has to do. Never releases a cause it cannot show changed without saying so.
+disable-model-invocation: true
+allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
+---
+<!-- vendored-from: @catalyst-cloud/catalyst-skills — written in this repository for customer tenants -->
+
+# Unstick
+
+You get one stuck ticket, or one set of tickets stuck for the same reason, moving again. The cloud parks or holds a ticket when retrying would only repeat a failure: after repeated failures, when the repair-round cap is spent, when a repair changed nothing, when the same validate failure recurred. Each of those is a governor. Once its cause is fixed, the person's own key releases it; nothing here needs an operator.
+
+## Run first
+
+Scripts are run, never read. Each prints `--help`; exit 2 means this machine is not connected (run `catalyst-skills login`).
+
+- `node scripts/unstick.mjs <ticket>` — one JSON document: the eligibility explanation, the execution history (every governor holding the ticket with what releases it, and past releases), and a dry-run release showing what a release would clear and refuse. Changes nothing.
+- `node scripts/unstick.mjs <ticket> --because "<what changed>"` — the same, then the real release. Add `--retry-unchanged` only when you can say what changed outside what the cloud can see.
+- `node scripts/unstick.mjs --class <failure-class> --team <key> [--because "<what changed>"]` — the same for every ticket on one team parked under one failure class (at most 25 per call).
+
+The verbs underneath are `catalyst-skills explain <ticket>`, `catalyst-skills explain <ticket> --history` and `catalyst-skills release <ticket> --because <text> [--retry-unchanged] [--dry-run]`.
+
+## Load on demand
+
+| when | read |
+| -- | -- |
+| deciding whether to release, what a refusal means, when to ask a person | `references/playbook.md` |
+| what a reason in the explanation means | the `whats-happening` skill's why-is-it-stuck reference, or `how-catalyst-works` |
+| a refusal needs a decision or a person's action | the `what-needs-me` skill |
+| a refusal names a person's pull request or its review | the `catalyst-github` skill |
+
+## Rules
+
+- **Read before you release.** Explain, then history, then a dry run. A release is never the first call.
+- **The cause decides, not the wish to move.** Release when you can name what changed since the ticket was held: a push, a comment that says what to change, an outage that ended, a secret that was rotated, an account that was re-enrolled. Put that sentence in `--because`; it is recorded against your name.
+- **Unchanged means say so.** The cloud refuses a release whose cause it cannot see change. Pass `--retry-unchanged` only with a `--because` that names the change it cannot see. If nothing changed, do not release; say so.
+- **One release per cause.** If the history shows a release for the same failure and nothing has changed since, a second release buys the same failure. Raise an ask instead.
+- **A refusal names its fix.** Do the fix when it is yours to do; everything else is one ask through `what-needs-me`, attached to an existing ask for the same decision. Never close or merge a person's pull request, and never answer an ask as the person.
+- **A shared cause is one note.** Several tickets parked by one outage or one bad image are one class release and one line in your reply, never one ask per ticket.
+- **Their tenant, as them.** Every read and write goes through the CLI and the person's own login. You never name another tenant.

package/skills/unstick/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Unstick"
+  short_description: "Find out why a Catalyst ticket is parked or held and release it once its cause is fixed; asks only for what needs a person"
+  default_prompt: "Use $unstick to find out why <ticket> is stuck and get it moving again."
+policy:
+  allow_implicit_invocation: false

package/skills/unstick/agents/portability.yaml

@@ -0,0 +1,5 @@
+identity: { pack: catalyst-cloud-skills, skill: unstick }
+effects: [external-write]
+mutating: true
+invocation: explicit
+exposure: [catalog]

package/skills/unstick/references/playbook.md

@@ -0,0 +1,51 @@
+# The unstick playbook
+
+This reference restates how a person's release of a stuck ticket works and the order you follow. The cloud does the deciding: it reads every governor holding the ticket and either releases all of them or releases nothing and names, for each one it refuses, the action that does fix it. Your job is to read, judge whether the cause is fixed, and say so honestly.
+
+## The order
+
+1. **Why is nothing running?** `catalyst-skills explain <ticket>`. If the reason is not a park or a hold (for example `blocked`, `not_at_dispatch_stage`, an ask, a missing environment check, `scope_overlap`), there is nothing to release: follow the `whats-happening` skill's why-is-it-stuck reference instead and stop here.
+2. **What holds it, and has it been released before?** `catalyst-skills explain <ticket> --history`. Read three things: the "Held by" lines (each governor and what releases it), the last failure (its class and summary), and the "Releases" lines (who released it before, why, and what happened).
+3. **Is the cause fixed?** Decide from evidence, in this order:
+   - a push to the ticket's branch, a comment on the ticket that says what to change, or main moving on since the park: the cloud can see these, and a release goes through;
+   - a change the cloud cannot see (a provider outage that ended, a rotated secret, a re-enrolled coding account, a fixed tenant setting): release with `--retry-unchanged`, and the reason you give names that change;
+   - nothing changed: do not release. Tell the person what failed and what would have to change.
+   If a previous release in the history named the same failure and nothing has changed since, the next release will fail the same way. Do not release again; raise an ask.
+4. **Preview.** `catalyst-skills release <ticket> --dry-run`. It prints what a release would clear and what it would refuse, and changes nothing.
+5. **Release.** `catalyst-skills release <ticket> --because "<the change>"`. Report what it released, verbatim, with the ticket id. A warning line (for example, that a released repair round runs again at the escalated tier and a second cap parks it again) goes in your reply too.
+6. **Act on each refusal.** A refusal is terminal for that attempt: nothing was released. Each names its fix; the table below says who does it.
+
+## What a refusal means and who fixes it
+
+| refusal | what it means | who acts |
+| -- | -- | -- |
+| `cause_unchanged` | nothing the cloud can see changed since it was held | you, if you can name a change it cannot see (`--retry-unchanged` with that `--because`); otherwise nobody should release it yet |
+| `lease_held` | a phase is running on the ticket right now | nobody; wait for the phase's outcome comment, then look again |
+| `branch_still_missing` | the ticket's branch was never pushed | it releases itself when the branch appears; check the earlier phases through `catalyst-linear` |
+| `human_owned_pr` | a person opened the pull request this ticket would work on | that person closes or merges it, or hands it to Catalyst; never close a person's pull request yourself |
+| `review_not_converging` | review and repair kept finding new problems | a person reads the findings (`catalyst-github`) 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 already raised, or pushes a fix; point at that ask, do not raise a second one |
+| `base_revision_lost` | the ticket's base commit is gone | whoever administers the tenant re-pins it; raise one ask |
+| `remediate_cap` | this tenant keeps the repair-round cap for an administrator | whoever administers the tenant; raise one ask |
+| `unknown_park` | a park this bundle does not know | raise one ask with the ticket id and the park name, verbatim |
+| `held_beyond_class` | a class release reached a ticket held by more than that class | release that ticket on its own, from step 1 |
+| `team_changed` (the ticket moved teams during the check) | the release was checked for one team and the ticket is now on another | run the release again |
+
+Raise an ask only through `what-needs-me`, with the stuck ticket in what it blocks, and attach to an existing ask for the same decision rather than filing a second one.
+
+## Several tickets, one cause
+
+When several tickets on one team are parked for the same failure class (the explanation and the history show the same class, typically an outage or a runner problem that has since ended):
+
+1. `catalyst-skills release --class <failure-class> --team <key> --dry-run` to see which tickets it reaches.
+2. `catalyst-skills release --class <failure-class> --team <key> --because "<the change>" --retry-unchanged` when the change is one the cloud cannot see.
+3. Report one line: how many released, which were refused and why, and whether more remain (run it again for the next batch).
+
+A ticket the class release refuses is listed and left alone; take it through the single-ticket order above.
+
+## What a release does not do
+
+- It does not skip a phase or accept work as done; a released phase runs again.
+- It does not reset a lifetime budget. A released repair round still counts toward the ticket's lifetime threshold, and the cloud stops a loop that claims the same unit too often in an hour.
+- It does not move the card. The ticket stays where it is and runs when the cloud next offers it.
+- It is recorded: who released, with which login, why, what it cleared and what it refused. `explain --history` shows it to everyone who reads the ticket.