@catalyst-cloud/catalyst-skills 0.1.1 → 0.2.0

package/skills/how-catalyst-works/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: how-catalyst-works
+description:
+  How Catalyst Cloud runs a ticket on the customer's own tenant, as facts an agent loads on demand: the eight-phase ladder and what each phase produces, the eleven board slots and this team's live stage map, what happens when a phase fails (retry, backoff, Remediate, park), how the queue is ordered and routed and every reason a ticket is excluded, and the coding-account model. Use when a person asks "how does this work?", "why did it do that?", "why is this stuck?", "what runs next?" or "how does it prioritise?". Read-only; its scripts explain one ticket's eligibility in plain English, show what is running and queued, and print the tenant's stage map and thresholds straight from the contract.
+allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
+---
+<!-- vendored-from: @catalyst-cloud/catalyst-skills — written in this repository for customer tenants -->
+
+# How Catalyst works
+
+You explain the machine. A person asks why Catalyst did something, what it will do next, or how it decides; you answer from the tenant's live contract and eligibility explainer, and from the invariants in the references below. You never guess a stage name, a label, a threshold or a route: the scripts print the live values.
+
+Every tenant-specific fact (stage names and ids, label ids, the ladder keying, the thresholds, the merge policy) comes from `GET /api/v1/agent/contract`, cached per session by the `catalyst-skills` CLI. The references restate only what does not vary per tenant.
+
+## Run first
+
+Run each with `--help` before reading anything else; the scripts are black boxes, not reading material.
+
+- `node scripts/explain-ticket.mjs <ticket>` — why one ticket is or is not about to run, as one paragraph plus the raw eligibility row.
+- `node scripts/whats-running.mjs [--queue] [--accounts] [--team <key>]` — fleet activity, the agent roster and lease attributions; with `--queue` the dispatch order; with `--accounts` the coding-account line.
+- `node scripts/show-my-map.mjs [--team <key>]` — this tenant's slot-to-stage map, ladder and live thresholds.
+
+Exit codes: 0 answered, 1 not found or a usage error, 2 this machine is not connected or the cloud refused (the one line printed says which; connect first if it names the login).
+
+## Load on demand
+
+| when | read |
+| -- | -- |
+| "what are the phases, what does each produce, when is a ticket Done?" | `references/the-ladder.md` |
+| "which column is which, why does nothing dispatch, what is a slot?" | `references/stages-and-mapping.md` |
+| a phase FAILED, a card went to Remediate, a ticket is parked or on hold | `references/when-a-phase-fails.md` |
+| "what runs next, why not this one, what does this exclusion reason mean?" | `references/what-runs-next.md` |
+| "why is nothing running", walls, quarantine, which provider ran a phase | `references/coding-accounts.md` |
+
+## Rules
+
+- **Print, never recall.** A stage name, label, threshold or route in your answer must have come from a script's output in this session.
+- **A reason is a layer.** Translate an exclusion reason through `references/what-runs-next.md`; name what releases it and who can do that (a clock, a comment, a push, an operator).
+- **Unknown is not absent.** An `unknown` verdict from the explainer means the cloud could not look; report it as inconclusive.
+- **System causes are one alert.** A provider outage, the runner image breaker or a paused repository holds many tickets for one reason; never escalate it ticket by ticket.
+- **Say what a key cannot see.** Coding-account status and per-ticket execution history are not readable with an account key yet; the scripts say so and name the settings page. Do not fill the gap with a guess.
+- **Depth lives elsewhere.** What a ticket accumulates in Linear is `catalyst-linear`; what a PR accumulates and whether it is mergeable is `catalyst-github`; raising a decision is `what-needs-me`.

package/skills/how-catalyst-works/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "How Catalyst Works"
+  short_description: "Explain how Catalyst Cloud runs a ticket: the ladder, your stage map, failures, what runs next, coding accounts"
+  default_prompt: "Use $how-catalyst-works to explain why Catalyst did that, or what it will run next."
+policy:
+  allow_implicit_invocation: true

package/skills/how-catalyst-works/agents/portability.yaml

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

package/skills/how-catalyst-works/references/coding-accounts.md

@@ -0,0 +1,51 @@
+# Coding accounts: slots, windows, walls, and what a key cannot read yet
+
+This reference restates the model, which does not vary per tenant. Your tenant's actual accounts, their usage and their state are NOT readable with an account key today: `node scripts/whats-running.mjs --accounts` prints that by name, with the settings page where the facts live. When a tenant-facing read ships, the same script will print the live rows and this reference stays true.
+
+## What a slot is
+
+A slot is one enrolled coding-account credential: a subscription or token that runs phases. A tenant may enrol several accounts of the same provider under the same email, because identity is the credential, not the email; the email is a display field. A revoked slot leaves the roster.
+
+## Providers and harnesses
+
+| Provider | Harness | Credential |
+| -- | -- | -- |
+| Claude | the Claude CLI | its own subscription |
+| Codex | Codex | its own subscription |
+| GLM | the Claude CLI | its own token |
+| Qwen | the Claude CLI | its own token |
+| GLM via OpenCode | OpenCode | the same GLM enrolment |
+| Qwen via OpenCode | OpenCode | the same Qwen enrolment |
+
+The harness is a property of the catalog entry, never a routing input. Which provider a phase runs on is the routing decision in `references/what-runs-next.md`; the routing rows, not the slot, name the model.
+
+## Two state axes
+
+- **Declared**: `active` or `disabled`. The operator sets it.
+- **Observed**: `healthy`, `degraded` or `unknown`. The poller sets it from what the provider reports.
+
+Two more lifecycle facts sit beside them: **quarantined** (system-set, on a credential conflict or an authentication mismatch; sticky, only an operator clears it) and **revoked** (operator-set).
+
+## Windows, walls, headroom
+
+- Subscriptions meter usage over a **5-hour** window and a **7-day** window, each with a used percentage and a reset time.
+- A **wall** is the window limit a session can die at mid-run. Before a slot is granted, a fit gate projects the phase's expected burn against the remaining headroom with a safety margin; a slot that would hit the wall is not offered.
+- **Headroom** per provider is advisory: it counts eligible and degraded slots and the best remaining percentage, and it can never promise what a reservation would refuse because both read the same eligibility predicate.
+- Holds: a Claude slot can serve several phases at once up to a per-account cap; a Codex slot serves one at a time because its refresh tokens are single-use.
+- Slot choice orders by usage band, then live-hold count, then used percent, then the latest reset, so bursts spread across accounts rather than stacking on one.
+
+A poller refreshes an active slot's usage every 5 minutes and a disabled one daily. Separately, vendor status pages are polled for provider health; that signal says nothing about your own accounts' windows, walls or quarantine.
+
+## What the settings page shows
+
+Your tenant's coding-accounts page lists each slot with a five-value status, first match wins: expired-or-revoked, walled, active, attested (healthy and active, but the provider is unobserved), unobserved. A drilldown shows the windows, the holds and the history.
+
+## What a key cannot read yet, and what to say
+
+Coding-account status (provider, declared and observed state, window percentages and resets, walls, quarantine, live holds) is served only behind the tenant's admin gate. So when a human asks "why is nothing running?":
+
+1. Run `node scripts/explain-ticket.mjs <ticket>` for a stuck ticket. `routing_unavailable` with a detail naming a slot or provider, or `no_eligible_account_slot` in the routing block, points at accounts.
+2. Say plainly that the account key cannot read account state, and give the settings link the script prints. Do not guess a wall or a quarantine from silence.
+3. Treat it as ONE fleet-level cause for every ticket it holds, never as a per-ticket escalation.
+
+The customer session never holds or mints a coding-account credential; phases run in the cloud on the enrolled accounts, and repository access is a per-phase installation token.

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

@@ -0,0 +1,54 @@
+# Stages and mapping: eleven slots, five that matter, and how to read this team's map
+
+This reference restates invariants (the slot vocabulary, which slots are load-bearing, the allowed state types, the three mapping modes). Everything about YOUR team — which Linear stage each slot maps to, its name, its type, whether it still exists — is live on the contract under `teams[].stages`. Read it with `node scripts/show-my-map.mjs [--team <key>]`; never quote a stage name or id from memory.
+
+## The eleven slots, in pipeline order
+
+`dispatch`, `intake`, `research`, `plan`, `implement`, `remediate`, `verify`, `review`, `pr`, `done`, `canceled`
+
+A slot is Catalyst's name for a position on the board. A stage is the Linear workflow state your team actually has. Mapping is the per-team table that binds each slot to one stage.
+
+## Five slots are load-bearing
+
+| Slot | Why it matters | Allowed Linear state types |
+| -- | -- | -- |
+| `dispatch` | Moving a card here is how work is dispatched. Nothing is offered from any other column. | `unstarted`, `backlog` |
+| `intake` | Where a never-seen ticket lands for the optional intake pass. | `unstarted`, `backlog` (never Linear's reserved triage type) |
+| `pr` | Where a card must sit for `merge` to be offered. | `started` |
+| `done` | Written by the merge webhook. | `completed` |
+| `canceled` | Terminal; a card here is never work. | `canceled` |
+
+An absent or wrongly-typed mapping on one of these five is a distinct silent failure: the ladder simply never moves. The other six slots are informational — a wrong value costs a warning in readiness, not a stall. That asymmetry is why "map my stages" is a five-field decision.
+
+## Three mapping modes
+
+The contract's `teams[].workflowMode` reports which one a team is in:
+
+- **adopted**: Catalyst created its recommended stage set for the team, one stage per slot, with verify and review sharing one validation stage.
+- **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".
+
+## The state id is the authority; names are display
+
+Each mapped stage carries a `stateId`, a display `name`, a `type`, `stateStillExists` and a `source` (how the mapping was chosen). Only the id is a lookup key. A Linear-to-Linear import can preserve every human-readable name while re-minting every state id, and then a name-based lookup points at nothing. So:
+
+- Move cards by slot (`catalyst-linear`'s move script does this) and let the CLI resolve the id from the contract. Never move a card "to Todo" by name.
+- `stateStillExists: false` means the mapped state is provably gone; the map needs fixing in your tenant settings before that slot can be written to. The CLI refuses such a move rather than guessing.
+- The stage names the contract shows come from the mirror's live view of Linear, not from a stored snapshot, so they are current at read time.
+
+## How to read the printed map
+
+`node scripts/show-my-map.mjs` prints, per team, one row per slot: the slot, the stage name (or `(unmapped)`, or `(state gone)`), the state type, whether the state still exists, and the source. Load-bearing slots are starred. Then the team's ask, hold and release labels with `(absent)` where the workspace has no such label, then the ladder (phases, keying, intake on or off) and the live thresholds.
+
+Reading it for a question:
+
+- "Why does nothing dispatch?" — is `dispatch` mapped, does its state still exist, and is the card actually in that stage? `node scripts/explain-ticket.mjs <ticket>` names `not_at_dispatch_stage` when the card is elsewhere.
+- "Why is merge not running?" — is the card in the `pr` slot's stage?
+- "Why did the card go to Remediate?" — `remediate` is mapped, so a failed phase moved it there (see `references/when-a-phase-fails.md`); if `remediate` is unmapped the same episode shows up as the hold label from `teams[].labels.hold` instead.
+- "The team's Backlog is not in the list" — correct. Backlog is not a slot. Parking a card is a move to the team's backlog-type state, which the CLI resolves from the team's live workflow states rather than from the map.
+
+## Readiness over the mapping
+
+The contract carries a ten-check readiness vector per team (`teams[].readiness`), including whether every mapped state exists, whether the mapping is total, whether the types are compatible, whether the labels are present, whether writes land and whether the webhook covers the team. A check the cloud could not run is `unknown`, never `pass`. `catalyst-setup` reads this vector; this skill only points at it.

package/skills/how-catalyst-works/references/the-ladder.md

@@ -0,0 +1,41 @@
+# The ladder: eight phases, what each one produces
+
+This reference restates invariants. The phase order and what each phase leaves behind do not vary per tenant. The only live values are whether intake is switched on for your tenant and which keying the advance table uses; both are on the contract under `ladder` (print them with `node scripts/show-my-map.mjs`).
+
+## The phases, in order
+
+| Phase | What it produces | Notes |
+| -- | -- | -- |
+| `intake` | nothing projected (a classification pass) | Optional head. Offered only to a ticket that has never entered the ladder, and only when the contract says `ladder.intakeEnabled` is true. |
+| `research` | `research.md` | The first ladder phase. Offered when the card sits in the team's dispatch slot. |
+| `plan` | `plan.md` | |
+| `implement` | `implement.md` | Creates the ticket branch (named exactly the ticket identifier) and opens a draft pull request. |
+| `validate` | `validation.md` | Its success moves the card to the team's review stage; verify and review are two slots that both land on that stage. |
+| `pr` | `pr.md` | The first line is the pull-request title, then a blank line, then the body. The phase rebases onto the default branch, force-pushes, writes the title and body, and marks the PR ready for review. |
+| `remediate` | `remediation.json` | An interrupt, not a step forward. It repairs a phase that failed and never advances the card past the PR slot. |
+| `merge` | a receipt, no artifact | Applies the queue-ready label once its evidence gate passes. It writes no board state. |
+
+Every artifact-bearing phase (all but `intake` and `merge`) projects its artifact into Linear as a document attached to the ticket, with a short link comment; `catalyst-linear` describes those shapes.
+
+## What moves the card
+
+An advance table maps a phase outcome to a card move: research done moves the card from the dispatch slot to the research slot, plan done from research to plan, implement done from plan to implement, validate done from implement to review, pr done from review to pr. The table is served on the contract as `ladder.advance` so you can read the exact rows; do not restate them from memory, because the tenant's keying decides whether a stage names the phase that just finished (trailing, the default) or the phase still ahead (leading).
+
+Three rows never move the card:
+
+- A **failed** phase writes no board state. The ticket stays where it was, retryable, and the failure handling in `references/when-a-phase-fails.md` takes over.
+- **`remediate` done** writes nothing by itself; the card restores to its exact pre-failure stage once a remediation round succeeds.
+- **`merge` done** writes nothing. The receipt only ever meant "the queue-ready label was applied".
+
+## Done is written by the merge, never by a phase
+
+The terminal move to the done slot is keyed to the real pull-request-merged event from GitHub, not to any phase receipt. When the PR merges, the mirror's own ingest path moves the ticket to Done within a few seconds, with no session and no human sweep, and a bounded periodic sweep backstops a dropped webhook. So:
+
+- A ticket still not Done a minute after its PR merged is a finding, not a chore to hand-close.
+- Done is not the same as live. A change to something that is deployed separately is inert until that deployment happens; the ticket state says the code merged, nothing more.
+
+## How to read a ticket's position on the ladder
+
+1. The card's stage tells you which phase last finished (under trailing keying) — read the team's map with `node scripts/show-my-map.mjs --team <key>` to translate a stage name into a slot.
+2. The phase-outcome comments on the ticket tell you which attempts ran and how they ended; the document attachments are the artifacts themselves.
+3. `node scripts/explain-ticket.mjs <ticket>` tells you what the cloud will run next, or why it will not.

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

@@ -0,0 +1,77 @@
+# What runs next: queue order, concurrency, routing, and every exclusion reason
+
+This reference restates invariants. The live queue is `node scripts/whats-running.mjs --queue [--team <key>]`; one ticket's verdict is `node scripts/explain-ticket.mjs <ticket>`. The reason phrases below match the CLI's own table, so a reason you see printed can be looked up here.
+
+## Queue order
+
+Each team's dispatch queue is derived by the tenant's own store, continuously, from the board:
+
+1. Queued tickets (cards in the dispatch slot) rank by **priority ascending, then created time ascending, then identifier ascending**.
+2. Mid-ladder tickets (any ticket with a phase already completed) join the candidate set and order **by completed-phase count descending**, so a ticket close to the end goes before one that just started. That count is an ordering surrogate only; it never decides membership or eligibility.
+
+The queue re-derives within seconds of any board change and at the top of every periodic pass as a backstop. `dispatch_queue.source` reads `self-derived` when the tenant store built it itself, which is the normal case.
+
+## Concurrency
+
+- Each repository has a concurrency cap (default 20 running phases). An operator can raise or lower it; a paused repository resolves to a cap of zero without touching the stored value, so resuming restores it.
+- Dispatch buckets by repository and splits slots across teams so no team starves another. A slot that is running, might be running, or is restarting is never free capacity.
+- Comment-wake work (an agent answering a human comment) shares the same cap as ladder work.
+
+## The routing decision, in five checks
+
+When a phase is about to start, a route is chosen per candidate, in order, and the first survivor wins:
+
+1. capability match (can this route run this phase);
+2. a model is configured;
+3. the provider is available;
+4. if the candidate needs a coding-account slot: an eligible slot exists and the headroom floor is met;
+5. degraded, equivalent or stage-default parameters resolve.
+
+No survivor is `no_eligible_account_slot` when any candidate was skipped on capacity, else `routing_unavailable` (a misconfiguration). See `references/coding-accounts.md` for what a slot is.
+
+## Every exclusion reason, one line each
+
+| Reason | Meaning |
+| -- | -- |
+| `ticket_terminal` | the ticket is in a done or canceled state |
+| `pipeline_complete` | every phase has already completed |
+| `not_at_dispatch_stage` | the card is not in the team's dispatch column; move it there to dispatch |
+| `not_at_pr_stage` | merge is next but the card is not in the PR column (waived when a tenant automation bounced it off PR and the bounce was recorded) |
+| `blocked` | a live blocking relation; the blocker closes first |
+| `cooling_down` | the offered phase is parked; an operator or a callback releases it, not a clock |
+| `lease_held` | a live container already holds this phase |
+| `intake_lease_held` | a later phase is offered while an intake container still holds the ticket |
+| `ask_ticket` | it carries an ask label; a question is never work |
+| `ask_shape_suspected` | its own text reads as a decision request; a human releases it with the release label from the contract's `vocabulary` |
+| `externally_claimed` | a worker outside the cloud claimed it |
+| `environment_check_required` | the repository's environment check has not run |
+| `environment_check_running` | the environment check is in flight |
+| `environment_check_failed` | the environment check failed |
+| `environment_check_expired` | the environment verdict aged out |
+| `environment_check_hash_mismatch` | the environment changed since the verdict |
+| `scope_overlap` | its declared file scope intersects a ticket in flight (implement only; enforced once a team activates a scope policy) |
+| `waiting_on` | a merge-gate failure with no remediable cause holds the card at PR |
+| `branch_missing` | the ticket branch has never been seen |
+| `branch_gone` | the ticket branch was deleted |
+| `pr_merged` | its PR merged and no other PR is open |
+| `no_change_hold` | a remediate round changed nothing; a human comment or a new push releases it |
+| `validate_class_spent` | this validate failure already spent its one repair round |
+| `stale_failure_episode` | the ladder advanced after the failure, so the round would repair a phase already passed |
+| `runner_image_breaker` | fleet-wide: the live runner image fails every phase at startup; clears when the pin moves |
+| `no_branch_to_remediate` | a remediate round is queued on a ticket with no branch |
+| `retry_backoff` | retrying in place, waiting out its 2/5/15-minute rung |
+| `routing_unavailable` | claimed then refused at kickoff: no route, no eligible slot, or the provider is unavailable; the detail names which |
+| `repo_paused` | an operator paused the repository |
+| `remediate_parked` | the remediate phase is parked, so the failing phase has nowhere to be repaired |
+
+## 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.
+
+One advisory gates nothing: `human_addressed_unlabeled_ask_suspect` (assigned to a human with no delegate; possibly an unlabelled ask).
+
+## The three levers a human has
+
+1. **Priority** on the ticket reorders the queue.
+2. **The dispatch column**: moving a card into the dispatch slot dispatches it; moving it to the team's backlog-type state parks it and stops rounds.
+3. **Holds**: the hold labels on the pull request (from the contract's `merge.prLabels`) keep a green PR out of the merge queue; a human comment on the ticket clears the validate hold and the no-change hold.

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

@@ -0,0 +1,57 @@
+# When a phase fails: four layers, in order
+
+This reference restates the mechanism, which does not vary per tenant. The numbers quoted are the fleet defaults; the live values are served on the contract under `thresholds` and `node scripts/show-my-map.mjs` prints them. Quote the printed values, not these.
+
+A failed phase writes no board state on its own: the ticket stays at its current stage, retryable. What happens next is decided by four stacked layers.
+
+## Layer 1: retry in place
+
+Some failures are not the ticket's fault, so the SAME phase is simply re-offered and no remediation round is minted:
+
+- the phase failed before any branch existed (research, plan or implement on a ticket whose own record shows no branch);
+- an infrastructure failure at any phase: a vendor 5xx, a dropped stream, a refused setup, an environment gap, a phase timeout, an unwritable workspace.
+
+Nothing is written for the retry; the ordinary dispatch path re-offers the phase. A remediation round on a branchless ticket could only fail to find the branch while spending a counted attempt, which is why this layer exists.
+
+## Layer 2: backoff
+
+Every retry-in-place, and a routing refusal at kickoff, waits out a rung of a backoff ladder before the phase is re-offered: 2 minutes, then 5, then 15, indexed by the consecutive-failure count and clamped at the last rung. While waiting, the eligibility explainer shows `retry_backoff` (or `routing_unavailable` with a kickoff detail). `node scripts/explain-ticket.mjs <ticket>` prints it. The live ladder is `thresholds.retryBackoffMs`.
+
+## Layer 3: move to Remediate
+
+Any failure that is not retry-in-place moves the card to the team's remediate stage and queues a remediation round. The round is an interrupt phase (`remediate`) that repairs what failed; when a round succeeds, the card restores to its exact pre-failure stage. A team with no remediate stage mapped gets the hold label from `teams[].labels.hold` instead of a state move.
+
+Rounds are capped: after `thresholds.remediateRoundCap` rounds (default 3) in one failure episode, no further round is queued. A remediation round that itself fails never queues another round. A round that changes nothing puts the ticket on a no-change hold, released by a human comment on the ticket or a new push, never by a clock. A validate failure with the same fingerprint spends only one repair round per episode.
+
+Two structural cases the round machinery refuses: a `remediate` round is never offered on a ticket with no recorded branch (`no_branch_to_remediate`), and one dispatched anyway is cancelled at the clone.
+
+## Layer 4: park
+
+After `thresholds.parkAfterConsecutiveFailures` consecutive failures (default 3) the phase is parked. A parked phase shows as `cooling_down` in the explainer; the ticket's `remediate` phase being parked shows as `remediate_parked`.
+
+Which parks release themselves:
+
+| Park | Releases by |
+| -- | -- |
+| repeated failure | an operator, not a clock |
+| remediate round cap reached | an operator, not a clock |
+| missing branch | its own budgeted release loop |
+| rebase conflict | its own budgeted release loop |
+
+An account key cannot release a park today; 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.
+
+## Two holds that are not failures
+
+- **Validate budget hold**: a validate failure that has spent its repair round holds the card; a human comment on the ticket clears it.
+- **Runner image breaker**: fleet-wide, not per ticket. When three distinct tickets fail the same startup class on the live runner image, dispatch pauses for the affected tickets, one anomaly alert is raised per tenant, and dispatch resumes automatically when the image pin moves. The explainer shows `runner_image_breaker`. Never escalate this one ticket at a time.
+
+## What a human sees on the ticket
+
+Each attempt posts a phase-outcome comment (complete or FAILED, with phase, attempt, artifact, a summary and any park or hold block) and each remediation round posts a remediate-attempt comment naming the failure class it is repairing. `catalyst-linear` describes the shapes. The round count of the cap and the park history are not readable with an account key yet; `catalyst-skills explain --history <ticket>` says so and names where to read them.
+
+## Rule of thumb for answering "why is it stuck?"
+
+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.
+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/explain-ticket.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// explain-ticket.mjs — why one ticket is, or is not, about to run: the cloud's own eligibility row
+// for it, rendered as one paragraph, plus the raw row so the failure block is not lost.
+import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wantsHelp } from "./lib/cli.mjs";
+
+const HELP = `Usage: node scripts/explain-ticket.mjs <ticket> [--json]
+
+Asks Catalyst Cloud for the ticket's eligibility row (position, status, the exclusion reason in plain
+English, the last failure, advisories) and prints it as one paragraph. Wraps: catalyst-skills explain.
+
+  <ticket>   the Linear identifier, e.g. KEY-123
+  --json     print the CLI's JSON document instead of the paragraph
+
+Exit 0 explained (even when the ticket is excluded), 1 when the ticket is unknown to the mirror or
+a usage error, 2 when this machine is not connected to a tenant or the cloud refused the read
+(the line says which).`;
+
+const argv = process.argv.slice(2);
+if (wantsHelp(argv)) {
+  console.log(HELP);
+  process.exit(0);
+}
+const { flags, positionals } = parseFlags(argv, { bool: ["json"] });
+const ticket = positionals[0];
+if (!ticket) usage("explain-ticket needs a ticket identifier (see --help)");
+
+const r = runCli(["explain", ticket, "--json"]);
+exitOnFailure(r);
+relayStderr(r);
+const doc = parseJson(r.stdout);
+if (!doc || typeof doc.explanation !== "string") {
+  console.log(r.stdout.trimEnd());
+  process.exit(1);
+}
+if (flags.json) {
+  console.log(JSON.stringify(doc));
+} else {
+  console.log(doc.explanation);
+  if (doc.row) console.log(`row: ${JSON.stringify(doc.row)}`);
+}
+process.exit(doc.row ? 0 : 1);

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

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: it spawns the catalyst-skills CLI
+// this machine connected with (the path recorded in customer.json, else npx) and hands back its
+// output. Scripts import it; a person runs it with --help to see what it does. No dependencies.
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+export const PACKAGE = "@catalyst-cloud/catalyst-skills";
+export const CONNECT_HINT = `CATALYST_CLOUD_TOKEN=<account key> npx ${PACKAGE} login`;
+
+/** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME (used by tests) over HOME. */
+export function configPath() {
+  const home = process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? process.env.USERPROFILE ?? "";
+  return join(home, ".config", "catalyst-cloud", "customer.json");
+}
+
+/** The config, or a one-line reason it could not be read. Never throws. */
+export function loadConfig() {
+  const path = configPath();
+  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` };
+    }
+    return { ok: true, cfg, path };
+  } catch (err) {
+    return { ok: false, reason: `${path} is unreadable: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+
+/** Exit 2 with the one line every script prints when this machine is not connected to a tenant. */
+export function notConfigured(reason) {
+  console.error(`not connected to a Catalyst Cloud tenant (${reason}) — run: ${CONNECT_HINT}`);
+  process.exit(2);
+}
+
+/**
+ * Run one catalyst-skills verb. Returns { code, stdout, stderr }. The CLI is `node <cliPath>` when
+ * the config recorded one that still exists, else `npx @catalyst-cloud/catalyst-skills`.
+ * Exits 2 (not configured) before spawning anything when the config is absent or unreadable.
+ */
+export function runCli(args, { stdin } = {}) {
+  const loaded = loadConfig();
+  if (!loaded.ok) notConfigured(loaded.reason);
+  const { cfg } = loaded;
+  let cmd;
+  let argv;
+  let shell = false;
+  if (typeof cfg.cliPath === "string" && existsSync(cfg.cliPath)) {
+    cmd = process.execPath;
+    argv = [cfg.cliPath, ...args];
+  } else {
+    cmd = process.platform === "win32" ? "npx.cmd" : "npx";
+    argv = [PACKAGE, ...args];
+    shell = process.platform === "win32";
+  }
+  const r = spawnSync(cmd, argv, {
+    encoding: "utf8",
+    input: stdin,
+    env: process.env,
+    shell,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (r.error) {
+    console.error(`could not run ${cmd}: ${r.error.message} — re-run ${CONNECT_HINT} to record the CLI path`);
+    process.exit(2);
+  }
+  return { code: r.status ?? 1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
+}
+
+/** Print the CLI's stderr (the source line, the contract line, any refusal) on our stderr. */
+export function relayStderr(r) {
+  const text = r.stderr.trimEnd();
+  if (text) console.error(text);
+}
+
+/** A non-zero CLI result ends the script with the same code, its stdout shown so nothing is lost. */
+export function exitOnFailure(r) {
+  if (r.code === 0) return;
+  relayStderr(r);
+  const out = r.stdout.trimEnd();
+  if (out) console.log(out);
+  process.exit(r.code);
+}
+
+export function parseJson(text) {
+  try {
+    return JSON.parse(text.trim());
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A small flag parser: `spec.value` names flags that take a value, `spec.bool` boolean flags,
+ * `spec.repeat` value flags that may repeat (collected into arrays). Unknown flags are a usage error.
+ */
+export function parseFlags(argv, spec = {}) {
+  const value = new Set(spec.value ?? []);
+  const bool = new Set(spec.bool ?? []);
+  const repeat = new Set(spec.repeat ?? []);
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--") {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+    if (!a.startsWith("--")) {
+      positionals.push(a);
+      continue;
+    }
+    let name = a.slice(2);
+    let inline;
+    const eq = name.indexOf("=");
+    if (eq !== -1) {
+      inline = name.slice(eq + 1);
+      name = name.slice(0, eq);
+    }
+    if (bool.has(name)) {
+      flags[name] = true;
+    } else if (value.has(name) || repeat.has(name)) {
+      const v = inline ?? argv[++i];
+      if (v === undefined || v === "") usage(`--${name} needs a value`);
+      if (repeat.has(name)) (flags[name] ??= []).push(v);
+      else flags[name] = v;
+    } else {
+      usage(`unknown option --${name}`);
+    }
+  }
+  return { flags, positionals };
+}
+
+export function usage(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+export function wantsHelp(argv) {
+  return argv.includes("--help") || argv.includes("-h");
+}
+
+const runDirectly = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (runDirectly) {
+  if (wantsHelp(process.argv.slice(2)) || process.argv.length <= 2) {
+    console.log(
+      [
+        "lib/cli.mjs — shared helper for this skill's scripts (not a command of its own)",
+        "",
+        "Reads ~/.config/catalyst-cloud/customer.json and runs the catalyst-skills CLI recorded there",
+        `(or npx ${PACKAGE} when no path is recorded). Exit 2 when the machine is not connected.`,
+        "",
+        `Connect first with: ${CONNECT_HINT}`,
+        `Config in use: ${configPath()}`,
+      ].join("\n"),
+    );
+    process.exit(0);
+  }
+}

package/skills/how-catalyst-works/scripts/show-my-map.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// show-my-map.mjs — this tenant'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";
+
+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 LOAD_BEARING = new Set(["dispatch", "intake", "pr", "done", "canceled"]);
+
+const argv = process.argv.slice(2);
+if (wantsHelp(argv)) {
+  console.log(HELP);
+  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 slotsRead = contractPath("slots");
+if (slotsRead.stderr.trim()) console.error(slotsRead.stderr.trimEnd());
+const slots = slotsRead.value;
+let teams = contractPath("teams").value;
+const ladder = contractPath("ladder").value;
+const thresholds = contractPath("thresholds").value;
+
+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`);
+    process.exit(1);
+  }
+}
+
+if (flags.json) {
+  console.log(JSON.stringify({ slots, teams, ladder, thresholds }));
+  process.exit(0);
+}
+
+const pad = (s, n) => String(s).padEnd(n);
+for (const team of teams) {
+  console.log(`== team ${team.key ?? "(no key)"} — ${team.name ?? team.id} — workflow ${team.workflowMode}, git automation ${team.gitAutomation}, readiness ${team.readiness?.status ?? "unknown"}`);
+  console.log(`   ${pad("slot", 12)}${pad("stage", 22)}${pad("type", 12)}${pad("exists", 8)}source`);
+  for (const slot of slots) {
+    const s = team.stages?.[slot];
+    const mark = LOAD_BEARING.has(slot) ? "*" : " ";
+    if (!s) {
+      console.log(`  ${mark}${pad(slot, 12)}(unmapped)`);
+      continue;
+    }
+    const name = s.stateStillExists ? (s.name ?? "(unnamed)") : "(state gone)";
+    console.log(`  ${mark}${pad(slot, 12)}${pad(name, 22)}${pad(s.type ?? "-", 12)}${pad(s.stateStillExists ? "yes" : "NO", 8)}${s.source}`);
+  }
+  const labels = team.labels ?? {};
+  const describe = (list) => (list ?? []).map((l) => `${l.name}${l.preferredId ? "" : " (absent)"}`).join(", ") || "none";
+  console.log(`   labels: ask ${describe(labels.ask)}; hold ${describe(labels.hold)}; release ${describe(labels.release)}`);
+}
+
+console.log("== ladder");
+console.log(`   phases: ${(ladder.phases ?? []).join(" → ")}`);
+console.log(`   keying: ${ladder.keying} (${ladder.keyingScope}); intake ${ladder.intakeEnabled ? "enabled" : "off"}`);
+
+console.log("== thresholds (live, fleet-wide)");
+const minutes = (ms) => `${Math.round(ms / 60000)} min`;
+console.log(`   park after ${thresholds.parkAfterConsecutiveFailures} consecutive failures`);
+console.log(`   remediate round cap ${thresholds.remediateRoundCap} (escalated budget ${thresholds.remediateEscalatedRoundBudget}, rewind budget ${thresholds.remediateRewindBudget})`);
+console.log(`   retry backoff ${(thresholds.retryBackoffMs ?? []).map(minutes).join(", ")}`);
+console.log(`   write budget ${thresholds.hostDailyWriteBudget} per host per day`);