@catalyst-cloud/catalyst-skills 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.7.0
+
+`explain` and `ready` now name a team that cannot start work even when the live read is not available. Your tenant's contract carries each team's dispatch gate, and this machine already keeps a copy of that contract on disk; until now only the live eligibility read could name the gate, so a network hiccup, or a cloud older than that read, left `explain` printing nothing at all. `explain` now leads with the gate and the fix from the cached contract when the live read is unavailable or sends no gate, and says which of the two it read; when both answer and disagree, the live read wins and the paragraph says the cached one disagreed. A refusal from the cloud — a credential that is not accepted, for instance — is still a refusal, never quietly replaced by a cached answer. `ready` now prints one dispatch-gate line per team: open teams read `ok`, and a team whose stages are not saved reads `FAIL` with the remedy your tenant sent and turns the verdict to NOT READY, because nothing in that team can start. A cloud that does not send the gate changes nothing.
+
+`catalyst-skills ready` now tells you when the skills on this machine, or the CLI itself, are behind the newest published release — it names the version you have, the version that is out, and the one command that updates each, as a note that never changes the verdict. Every skill file now records the bundle version it was vendored at, so a copy installed months ago is visible as such instead of only by diffing files. The check reads the npm registry's `dist-tags.latest`, capped at 1500ms and cached for six hours, and never blocks: an unreachable registry is one note that says so, and `--offline` (or `CATALYST_SKILLS_OFFLINE=1`) skips the lookup entirely.
+
+A list read now returns the whole scope or says plainly that it did not. `catalyst-skills query issues --all` and `query pulls --all` follow the cloud's page cursor to the end of the scope instead of stopping at the first page, and a read without `--all` that was cut short now prints `truncated at N of M` on stderr, where M is the full count the cloud reports for the same scope. `catalyst-skills ask list` — and the what-needs-me skill that wraps it — reads every page, so a workspace with more than a few hundred tickets no longer gets an inbox that quietly omits the asks past the first page, or scores the ones it does show against a partial view of what they hold.
+
+Every skill this bundle ships now carries a routing case proving it still fires on a sentence its own description promises, and a deterministic check that fails by name the moment a description drops a phrase a case relies on — this repository's own test suite now catches a broken trigger before it ever reaches an install. A publish also runs a security scanner over every skill's scripts first, so a script that reads a sensitive directory or embeds an instruction override blocks the release unless someone has written down why it does not.
+
+## 0.6.1
+
+The local replica writer no longer retries a failing snapshot pull forever. After a failed or incomplete pull it backs off with jitter (30s doubling to a 15-minute cap) and gives up after five consecutive failures, recording why; a pull that completes resets the count. `catalyst-skills replica status` and `catalyst-skills ready` both name the stopped state, the count, the last error, and the command that restarts it. Until the read side of a large snapshot is safe, `ready` no longer suggests starting the replica at all — it says plainly that the replica is optional and off by default for large tenants, and every read still works through the API either way.
+
+## 0.6.0
+
+A new `catalyst-onboard` skill walks you from nothing to your first ticket running, one step at a time. You install the bundle yourself and type `/catalyst-onboard`; from there your agent does each step, shows you what actually came back, and stops — no page is fetched and no instruction arrives from anywhere but the skill you installed. It reads setup as five separate parts, each with the instrument that owns it: this machine (`status` and the machine half of `ready`), you (`me`), your account's Linear workspace, the projects that have been mapped, and the repositories that have been registered. Nothing answers for a part it does not own, so a project that is not ready is reported as a project finding with the tenant owner who can fix it and the page it is on — never as something to retry here. `node scripts/where-am-i.mjs` prints the whole reading, `--next` reduces it to the one next step, and every page link it prints is built from the cloud this machine is connected to rather than typed from memory.
+
+It also says plainly what it cannot do. Approving the login, connecting Linear and installing the GitHub App are browser steps by construction and always will be. Seeing every project you could set up, mapping stages, adopting the workflow, registering a repository and declaring an environment are settings-page steps today because the routes behind them take a browser session rather than a key; the skill hands you the page for each, says it is a gap rather than the design, and never guesses at a route. Two silences are called out because both read as absence and are not: an empty project list means nothing is mapped yet, not that you have no projects, and a registered repository is registered and nothing more — that list carries no status and no project attachment, so it never proves work can be dispatched into it.
+
+`catalyst-skills environment` is new, and it is the first setup action an agent can perform end to end. The tenant-wide environment declaration — the names your builds need — has been callable with your own login since the routes shipped, and nothing could call it, so every part of setting a tenant up was a page in the app. `environment` reads the current revision, whether it is approved, and which revision a phase's checkout actually carries (a proposal nobody approved changes nothing, and the verb says so); `environment propose --file <path>` proposes one from a JSON file or stdin, `--expect-revision` refuses if someone moved it since you read it, and `--approve` approves exactly the revision the propose returned. `environment approve` on its own reads the current revision and approves that, so the compare-and-set the cloud requires never depends on a hash copied between two commands. Reading needs any active seat; proposing and approving need an admin or owner one, and the cloud's refusal says which. The route paths come from your tenant's own contract and the derived ones are checked against it, so a cloud that does not serve them yet is named as older instead of answering 404. Repository-scope declarations are still a page. `catalyst-onboard`'s step for declaring what the containers need is now a command rather than a handover, and its report reads the declaration back.
+
+The package description and the README no longer count the skills or list them in prose. A count written in a sentence cannot be kept true by anything, and the last one was wrong in the direction that made a correct install report itself as failed.
+
 ## 0.5.0
 
 The local replica can now keep the durable tenant event backbone beside its entity database. `catalyst-skills replica start` owns both synchronizers in one process, while `catalyst-skills events tail`, `events wait-for`, and `events query` read the bounded local cache with exact event-type and ticket filters. A failed event synchronizer is reported without stopping a healthy entity replica. This requires `@catalyst-cloud/sdk` 0.10.0 or newer.

package/README.md

@@ -18,7 +18,7 @@ Or by hand. One command, for every coding agent on the machine:
 npx skills@latest add coalesce-labs/catalyst-cloud-skills --all
 ```
 
-It installs all nine skills for each agent it detects (Claude Code, Codex, Cursor, OpenCode and the rest). Add `-g` to install into your home directory instead of the project. Skills installed this way do not auto-update; run `npx skills update -y` to refresh them.
+It installs every skill in the bundle for each agent it detects (Claude Code, Codex, Cursor, OpenCode and the rest). Add `-g` to install into your home directory instead of the project. Skills installed this way do not auto-update; run `npx skills update -y` to refresh them.
 
 <details><summary><strong>Alternative for Claude Code: the plugin marketplace</strong></summary>
 
@@ -77,7 +77,7 @@ That is the whole setup. Everything below explains what you just installed.
 
 ## What this is
 
-Nine skills that let your coding agent run your own Catalyst Cloud tenant (https://staging.catalystcloud.dev) from your seat: what is happening, what needs you, and what to do about it. They read your tenant through the Catalyst Cloud SDK, write to it through the tenant's agent proxy, and never compose a URL or run a tool of their own; every read, write and subscription is a `catalyst-skills` verb with `--help`. Every skill is plain Markdown under `skills/<name>/SKILL.md` in this repository, and your own login — a keyless device-code session, or a personal key — is the only credential. Your agent acts as you: the asks it raises and the comments it posts carry your name, and "what needs me" means you.
+A set of skills that let your coding agent run your own Catalyst Cloud tenant (https://staging.catalystcloud.dev) from your seat: what is happening, what needs you, and what to do about it. They read your tenant through the Catalyst Cloud SDK, write to it through the tenant's agent proxy, and never compose a URL or run a tool of their own; every read, write and subscription is a `catalyst-skills` verb with `--help`. Every skill is plain Markdown under `skills/<name>/SKILL.md` in this repository, and your own login — a keyless device-code session, or a personal key — is the only credential. Your agent acts as you: the asks it raises and the comments it posts carry your name, and "what needs me" means you.
 
 ## What connecting does
 
@@ -125,6 +125,7 @@ The replica is a Node process, not a service: the supported path is the plain co
 
 | skill | what the person says | what it does | file |
 | --- | --- | --- | --- |
+| `catalyst-onboard` | "Set me up. Onboard me. I just signed up — what do I do first?" | Walks you from nothing to your first ticket running, one step at a time: connect this machine, connect Linear, map one project, register one repository, then watch a card move. Reads each part of setup with the instrument that owns it and says who can fix anything unfinished and where. Hands over the steps only a browser can do instead of pretending to have done them. | [`SKILL.md`](skills/catalyst-onboard/SKILL.md) |
 | `whats-happening` | "What's happening? Where are we? Why is that stuck? What's next?" | The desk for a tenant: reads the contract, what is running and queued, the eligibility explainer and the open asks, and answers in one reply with ticket ids. Routes work to a project owner and decisions to `what-needs-me`. | [`SKILL.md`](skills/whats-happening/SKILL.md) |
 | `what-needs-me` | "What needs me? What am I blocking?" | The human's decision inbox, ranked by what each answer releases, and the one way an agent raises a decision on their behalf: files an ask through the cloud's ask route with the tenant's own template and records the answer so the held work releases. | [`SKILL.md`](skills/what-needs-me/SKILL.md) |
 | `run-this-project` | "Run this project for me. Own it until it closes." | Single-threaded owner of one project: subscribes to the tenant stream for its scope, reacts to each change in the same turn, makes tickets ready and moves them to dispatch, parks what should stop, chases stalls, escalates inward, and keeps one status summary current. Never polls. | [`SKILL.md`](skills/run-this-project/SKILL.md) |
@@ -135,23 +136,24 @@ The replica is a Node process, not a service: the supported path is the plain co
 | `unstick` | "Why is this parked? Unpark it. Get things flowing again." | Reads why a ticket is not running and every park or hold on it, decides whether the recorded cause is fixed, previews the release and releases it the right way from your own login — or one failure class across a team — and raises an ask only for what a person has to do. | [`SKILL.md`](skills/unstick/SKILL.md) |
 | `connect-me` | "Connect this machine to my tenant." | Connects the machine to the tenant with your own personal key, caches the tenant contract, verifies, and offers to start the replica. | [`SKILL.md`](skills/connect-me/SKILL.md) |
 
-Four skills only read (`whats-happening`, `catalyst-setup`, `catalyst-github`, `how-catalyst-works`). The five that write anything (`catalyst-linear`, `what-needs-me`, `run-this-project`, `connect-me`, `unstick`) are marked so an agent cannot invoke them on its own; the person asks for them. Every skill declares `allowed-tools` scoped to this package's own binary, so none of them needs a blanket shell grant.
+Some of these only read; the ones that write anything — or that drive you through writes, as `catalyst-onboard` does — are marked so an agent cannot invoke them on its own, and you ask for them by name. Each skill's own `SKILL.md` says which it is, in its frontmatter; no count lives in this sentence, because a count in a sentence goes wrong the first time the table above gains a row. Every skill declares `allowed-tools` scoped to this package's own binary, so none of them needs a blanket shell grant.
 
 ## What a key cannot see yet
 
-Your personal key reads everything the skills need — tickets, pull requests, the eligibility explainer, the dispatch queue, fleet activity, per-ticket execution history (`catalyst-skills explain --history <ticket>`: phase attempts, remediation rounds, park state) and coding-account status (`catalyst-skills accounts`: provider, declared and observed state, window usage, walls, quarantine — never a credential; enrolling or pausing one is `<your cloud>/settings/coding-accounts`). It also releases a parked or held ticket once its cause is fixed: `catalyst-skills release <ticket> --because <what changed>` (the `unstick` skill runs it), recorded against your name and shown in the ticket's history. One thing it cannot do, and the skills say so by name rather than guess:
+Your personal key reads everything the skills need — tickets, pull requests, the eligibility explainer, the dispatch queue, fleet activity, per-ticket execution history (`catalyst-skills explain --history <ticket>`: phase attempts, remediation rounds, park state) and coding-account status (`catalyst-skills accounts`: provider, declared and observed state, window usage, walls, quarantine — never a credential; enrolling or pausing one is `<your cloud>/settings/coding-accounts`). It also releases a parked or held ticket once its cause is fixed: `catalyst-skills release <ticket> --because <what changed>` (the `unstick` skill runs it), recorded against your name and shown in the ticket's history. And it declares what your containers need: `catalyst-skills environment` reads the tenant-wide declaration, `environment propose --file <path> --approve` proposes and approves it in one compare-and-set, and the values behind the names stay in the app where you entered them — reading needs any active seat, proposing and approving need an admin or owner one. That is the account's own declaration — a repository's own `catalyst.env.json`, which `catalyst-setup` already reports on, is a separate thing. One thing it cannot do, and the skills say so by name rather than guess:
 
 - Read pull-request labels or the reviewer's reaction. The mirror does not carry them; GitHub's own page does.
 
 ## Versions and origins
 
-The package pins the tenant contract range `1.x`, recorded in `package.json` under `catalystCloud.tenantContractRange`, and reports it in `--version`, `status` and `login`. A tenant whose contract version falls outside that range is refused with one line naming both versions; update the bundle. Every skill carries a `vendored-from:` line naming this package as its origin; all nine are written in this repository for customer tenants.
+The package pins the tenant contract range `1.x`, recorded in `package.json` under `catalystCloud.tenantContractRange`, and reports it in `--version`, `status` and `login`. A tenant whose contract version falls outside that range is refused with one line naming both versions; update the bundle. Every skill carries a `vendored-from:` line naming this package as its origin, and that line now also carries the version it was vendored at; all of them are written in this repository for customer tenants.
 
 ## What it writes on your machine
 
 - `~/.config/catalyst-cloud/customer.json`, written with mode `0600`, holding your personal key, who you are, and the CLI path.
 - `~/.config/catalyst-cloud/contract.json`, the cached tenant contract.
-- Only if you start them: `~/.config/catalyst-cloud/replica.db` with its `.pid` and `.writer.lock` sidecars, `$XDG_STATE_HOME/catalyst/events/<tenant>/backbone/` (or the home-directory fallback) with bounded daily event segments, and `~/.config/catalyst-cloud/watch-cursor.json`.
+- `~/.config/catalyst-cloud/published.json`, the cached answer to "what is the newest release" — no credential in it.
+- Only if you start them: `~/.config/catalyst-cloud/replica.db` with its `.pid`, `.writer.lock` and `.writer.state` sidecars, `$XDG_STATE_HOME/catalyst/events/<tenant>/backbone/` (or the home-directory fallback) with bounded daily event segments, and `~/.config/catalyst-cloud/watch-cursor.json`.
 
 The skill files themselves are written by whichever install command you ran, in that tool's own location. Your personal key goes into that one config file and nowhere else.
 
@@ -165,14 +167,16 @@ A plugin install updates when we ship. Skills copied by `npx skills add` do not;
 
 A `customer.json` written by an older bundle is still read unchanged; it gains the CLI path and the cached contract the next time you run `catalyst-skills login`.
 
+`catalyst-skills ready` also says when either the installed skills or the CLI is behind the latest publish, naming both versions and the command for each; it is a note, never a failure, and `--offline` (or `CATALYST_SKILLS_OFFLINE=1`) skips the lookup.
+
 ## Uninstalling
 
-Remove the skills the way you installed them: `/plugin uninstall catalyst@catalyst-cloud` in Claude Code, or delete the nine directories (`catalyst-github`, `catalyst-linear`, `catalyst-setup`, `connect-me`, `how-catalyst-works`, `run-this-project`, `unstick`, `what-needs-me`, `whats-happening`) from wherever `npx skills add` wrote them. Then remove what the CLI wrote:
+Remove the skills the way you installed them: `/plugin uninstall catalyst@catalyst-cloud` in Claude Code, or delete the skill directories (`catalyst-github`, `catalyst-linear`, `catalyst-onboard`, `catalyst-setup`, `connect-me`, `how-catalyst-works`, `run-this-project`, `unstick`, `what-needs-me`, `whats-happening`) from wherever `npx skills add` wrote them. Then remove what the CLI wrote:
 
 ```sh
 catalyst-skills replica stop
-rm -f ~/.config/catalyst-cloud/customer.json ~/.config/catalyst-cloud/contract.json ~/.config/catalyst-cloud/watch-cursor.json
-rm -f ~/.config/catalyst-cloud/replica.db ~/.config/catalyst-cloud/replica.db.pid ~/.config/catalyst-cloud/replica.db.writer.lock
+rm -f ~/.config/catalyst-cloud/customer.json ~/.config/catalyst-cloud/contract.json ~/.config/catalyst-cloud/published.json ~/.config/catalyst-cloud/watch-cursor.json
+rm -f ~/.config/catalyst-cloud/replica.db ~/.config/catalyst-cloud/replica.db.pid ~/.config/catalyst-cloud/replica.db.writer.lock ~/.config/catalyst-cloud/replica.db.writer.state
 rm -rf "${XDG_STATE_HOME:-$HOME/.local/state}/catalyst/events"
 npm uninstall -g @catalyst-cloud/catalyst-skills
 ```

package/dist/args.js

@@ -26,10 +26,11 @@ export const FLAG_TABLES = {
         team: { value: true, help: "team key filter" },
         project: { value: true, help: "project id filter" },
         state: { value: true, help: "state name filter" },
-        limit: { value: true, help: "max rows (default 50)" },
+        limit: { value: true, help: "max rows (default 50); one page only unless --all" },
         since: { value: true, help: "changes: the cursor to read after" },
         source: { value: true, help: "replica | api (default: replica when fresh, else api)" },
         ticket: { value: true, help: "pulls: only PRs linked to this ticket" },
+        all: { value: false, help: "issues/pulls: follow the cloud's page cursor to the end of the scope" },
     },
     replica: {
         detach: { value: false, help: "start: run the writer in the background and write a pidfile" },
@@ -98,8 +99,18 @@ export const FLAG_TABLES = {
         answer: { value: true, help: "accept: the answering comment id" },
         role: { value: true, help: "accept: the role recording the answer" },
     },
-    ready: {},
+    ready: {
+        offline: { value: false, help: "skip the published-release check (no network)" },
+    },
     accounts: {},
+    environment: {
+        file: { value: true, help: "propose: a JSON file holding the declaration" },
+        stdin: { value: false, help: "propose: read the declaration from stdin" },
+        "expect-revision": { value: true, help: "propose: refuse unless the stored declaration is still at this revision" },
+        approve: { value: false, help: "propose: approve exactly the revision the propose returned" },
+        revision: { value: true, help: "approve: the revision to approve (with --hash; default is whatever read returns)" },
+        hash: { value: true, help: "approve: the canonical hash to approve (with --revision)" },
+    },
     release: {
         because: { value: true, help: "what changed since the ticket was held (required unless --dry-run)" },
         "retry-unchanged": { value: false, help: "release even though nothing the mirror can see changed (say what did in --because)" },
@@ -116,7 +127,7 @@ export const VERB_USAGE = {
     notice: "notice",
     me: "me [--json]",
     contract: "contract [--refresh] [--path <a.b.c>] [--json]",
-    query: "query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <cursor|head>> [--team K] [--project P] [--state S] [--limit N] [--source replica|api] [--json]",
+    query: "query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <cursor|head>> [--team K] [--project P] [--state S] [--limit N] [--all] [--source replica|api] [--json]",
     replica: "replica <start [--detach]|stop|status [--probe] [--json]|sql \"<select>\"|schema [table]> [--db <path>]",
     events: "events <tail|wait-for|query> [--type NAME] [--ticket CTC-N] [--after SEQUENCE] [--limit N] [--timeout SECONDS] [--directory PATH]",
     explain: "explain <ticket> [--history] [--json]",
@@ -126,8 +137,9 @@ export const VERB_USAGE = {
     watch: "watch [--team K] [--ticket T]... [--project P] [--exec CMD] [--cursor-file <path>] [--from cursor|head]",
     write: "write <comment <ticket> --body|--stdin [--parent] [--bookkeeping] [--as-user] | state <ticket> --slot|--state-id|--state-type | label <ticket> --add... --remove... | create --team --title [--label] [--priority] | reaction <ticket>|--comment <id> --emoji <e> | attachment <ticket> --title --url | session <ticket> [--title] [--plan-file] [--activity]>",
     ask: "ask <raise --team --title [--context] [--option]... [--default] --blocks <ticket>...|--nothing-to-block [--ask-key] | accept <askTicket> --answer <commentId> --role <role> | list [--anyone] [--json]>",
-    ready: "ready [--json]",
+    ready: "ready [--json] [--offline]",
     accounts: "accounts [--json]",
+    environment: "environment [read] [--json] | environment propose --file <path>|--stdin [--expect-revision N] [--approve] [--json] | environment approve [--revision N --hash H] [--json]",
     release: "release <ticket> --because <what changed> [--retry-unchanged] [--dry-run] [--json] | release --class <failure-class> --team <K> --because <what changed> [--retry-unchanged] [--dry-run] [--limit N] [--json]",
 };
 export function parseArgs(argv) {

package/dist/ask.js

@@ -6,7 +6,7 @@ import { requireConfig } from "./config.js";
 import { loadContract, teamByKey } from "./contract.js";
 import { UsageError } from "./errors.js";
 import { apiClient } from "./transport.js";
-import { rowsOf } from "./query.js";
+import { fetchAllPages } from "./pagination.js";
 import { fetchWorkflowStates, postAgent, resolveIssue } from "./write.js";
 export async function cmdAsk(args, ctx) {
     const [sub, ...rest] = positionals(args);
@@ -131,8 +131,11 @@ export function rankAsks(issues, doc, openState) {
     return out.sort((a, b) => b.score - a.score || a.identifier.localeCompare(b.identifier));
 }
 async function list(args, ctx, doc, api, cfg) {
-    const [issuesRes, states] = await Promise.all([api.getJson("/api/v1/issues", { query: { limit: 500 } }), fetchWorkflowStates(api)]);
-    const issues = rowsOf(issuesRes.body);
+    // ⛔ THE INBOX IS THE WHOLE SCOPE, NOT A PAGE. The mirror caps every page at 500 rows regardless of
+    // the requested limit, so a single `limit: 500` read drops every ask past the cap — and, worse,
+    // scores the asks it does show against a partial view of what they block (rankAsks below).
+    const [inbox, states] = await Promise.all([fetchAllPages(api, "/api/v1/issues", {}), fetchWorkflowStates(api)]);
+    const issues = inbox.rows;
     const terminal = new Set(states.filter((s) => ["completed", "canceled", "cancelled"].includes(s.type.toLowerCase())).map((s) => s.name.toLowerCase()));
     const openState = (issue) => !terminal.has(String(issue.state ?? "").toLowerCase());
     const all = rankAsks(issues, doc, openState);

package/dist/cli.js

@@ -14,16 +14,18 @@ import { cmdReady } from "./ready.js";
 import { cmdReplica } from "./replica.js";
 import { cmdEvents } from "./events.js";
 import { stdinIsTty } from "./prompt.js";
-import { PROVENANCE_MARKER } from "./skill-shape.js";
-import { installSkills, parseChangelogEntry, readChangelog, resolveSkillsDir, skillsSourceDir, updateNoticeLine } from "./skills.js";
+import { FIRST_STAMPED_VERSION, PROVENANCE_MARKER, parseProvenanceVersion } from "./skill-shape.js";
+import { installedBundleVersion, installSkills, parseChangelogEntry, readChangelog, resolveSkillsDir, skillsSourceDir, updateNoticeLine, } from "./skills.js";
 import { cmdWatch } from "./watch.js";
 import { cmdWrite } from "./write.js";
 import { cmdAsk } from "./ask.js";
 import { cmdRelease } from "./release.js";
-export { CONFIG_MODE, DEFAULT_BASE_URL, PACKAGE_NAME, PROVENANCE_MARKER, CliError, MeError, UsageError, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, fetchMe, formatMode, installSkills, loadConfig, normalizeBaseUrl, parseArgs, parseChangelogEntry, readChangelog, readManifest, resolveSkillsDir, saveConfig, skillsSourceDir, updateNoticeLine, writeConfig, };
+import { cmdEnvironment } from "./environment.js";
+export { CONFIG_MODE, DEFAULT_BASE_URL, FIRST_STAMPED_VERSION, PACKAGE_NAME, PROVENANCE_MARKER, CliError, MeError, UsageError, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, fetchMe, formatMode, installedBundleVersion, installSkills, loadConfig, normalizeBaseUrl, parseArgs, parseChangelogEntry, parseProvenanceVersion, readChangelog, readManifest, resolveSkillsDir, saveConfig, skillsSourceDir, updateNoticeLine, writeConfig, };
 export const CUSTOMER_SKILLS = [
     "catalyst-github",
     "catalyst-linear",
+    "catalyst-onboard",
     "catalyst-setup",
     "connect-me",
     "how-catalyst-works",
@@ -56,6 +58,7 @@ export function usageText() {
         "  catalyst-skills write <comment|state|label|create|reaction|attachment|session> ...",
         "  catalyst-skills ask <raise|accept|list> ...",
         "  catalyst-skills release <ticket> --because <what changed> [--retry-unchanged] [--dry-run] | release --class <c> --team <K> ...",
+        "  catalyst-skills environment [read] | environment propose --file <path>|--stdin [--approve] | environment approve",
         "",
         "Every verb takes --help. --json makes the output machine-readable.",
         "",
@@ -173,11 +176,13 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
             case "ask":
                 return await cmdAsk(args, ctx);
             case "ready":
-                return await cmdReady(args, ctx, { skillNames: CUSTOMER_SKILLS, loadSdk: deps.loadSdk });
+                return await cmdReady(args, ctx, { skillNames: CUSTOMER_SKILLS, loadSdk: deps.loadSdk, offline: args.flags.offline === true });
             case "accounts":
                 return await cmdAccounts(args, ctx);
             case "release":
                 return await cmdRelease(args, ctx);
+            case "environment":
+                return await cmdEnvironment(args, ctx, deps.environment ?? {});
             default:
                 ctx.stderr(`unknown command: ${args.command}`);
                 ctx.stderr(usageText());

package/dist/config.js

@@ -27,6 +27,10 @@ export function configPathFor(home) {
 export function contractPathFor(home) {
     return join(configDirFor(home), "contract.json");
 }
+/** CTC-2160 — the cached answer to "what is the newest published release" (src/published.ts). */
+export function publishedCachePathFor(home) {
+    return join(configDirFor(home), "published.json");
+}
 export function watchCursorPathFor(home) {
     return join(configDirFor(home), "watch-cursor.json");
 }

package/dist/contract.js

@@ -121,6 +121,12 @@ export function teamByKey(doc, key) {
     }
     return team;
 }
+/** The contract's team for a key, or null. `teamByKey` refuses; this one answers "is it there?" for
+ *  readers (explain's cached dispatch gate) that must stay silent for a team the contract omits. */
+export function findTeamByKey(doc, key) {
+    const wanted = key.toUpperCase();
+    return doc.teams.find((t) => (t.key ?? "").toUpperCase() === wanted) ?? null;
+}
 export function teamById(doc, id) {
     return doc.teams.find((t) => t.id === id) ?? null;
 }

package/dist/environment.js

@@ -0,0 +1,207 @@
+// environment.ts — `catalyst-skills environment`: the tenant-scope environment declaration, through
+// the contract's account-environment routes. This is the ONE setup write a person's own key can
+// perform: the cloud has admitted it since the routes shipped, and until this verb existed nothing
+// could call it, so every setup action was a settings page.
+//
+// ⛔ THE ROUTE PATHS ARE DISCOVERED, NEVER ASSUMED. `read` is the route the contract's table names;
+// `propose` and `approve` are derived from it the way the Worker derives them (one prefix, three
+// verbs) and then CHECKED against the same table. A tenant whose cloud predates the routes gets the
+// "needs a newer cloud" refusal by name rather than a 404 from a hand-copied path.
+//
+// ⭐ APPROVE IS A COMPARE-AND-SET on `(revision, canonicalHash)`, and with no flags this verb reads
+// the current state and approves exactly what it just read. Hand-copying a hash between two commands
+// is the failure that shape exists to prevent; making the caller do it anyway would reintroduce it.
+import { readFileSync } from "node:fs";
+import { flagBool, flagInt, flagString, positionals } from "./args.js";
+import { requireConfig } from "./config.js";
+import { loadContract } from "./contract.js";
+import { UsageError } from "./errors.js";
+import { needsNewerCloud } from "./execution.js";
+import { apiClient } from "./transport.js";
+/**
+ * The three account-environment paths this tenant serves.
+ *
+ * ⛔ `propose` and `approve` are NOT looked up by their own last path segment. `routePath`-style
+ * last-segment matching takes the FIRST route ending in that word, so the day a repo-scope
+ * `.../repo-environment/propose` joins the table, a lookup for "propose" could silently return it
+ * and this verb would write a repo's declaration into the account's name. Deriving both from the
+ * account prefix — and then asserting each derived path is really in the table — cannot do that.
+ */
+export function environmentRoutes(doc, cfg) {
+    const base = doc.routes.find((r) => r.method === "GET" && r.path.split("/").filter(Boolean).at(-1) === "account-environment");
+    if (!base) {
+        throw needsNewerCloud('the tenant environment declaration (the contract serves no "account-environment" route)', cfg);
+    }
+    const routes = {
+        read: base.path,
+        propose: `${base.path}/propose`,
+        approve: `${base.path}/approve`,
+    };
+    for (const verb of ["propose", "approve"]) {
+        const served = doc.routes.some((r) => r.method === "POST" && r.path === routes[verb]);
+        if (!served) {
+            throw needsNewerCloud(`the tenant environment declaration's ${verb} route (${routes[verb]} is absent from the contract)`, cfg);
+        }
+    }
+    return routes;
+}
+/** The declaration to send: a JSON file, or stdin. Never invented, and never partially parsed. */
+async function readDeclaration(args, readStdin) {
+    const file = flagString(args, "file");
+    const useStdin = flagBool(args, "stdin");
+    if (file !== undefined && useStdin)
+        throw new UsageError("environment propose takes --file <path> or --stdin, not both");
+    if (file === undefined && !useStdin) {
+        throw new UsageError("environment propose needs --file <path> or --stdin (the declaration is JSON; this verb never invents one)");
+    }
+    const text = file === undefined ? await readStdin() : readFileSync(file, "utf8");
+    if (text.trim() === "")
+        throw new UsageError(`the declaration ${file === undefined ? "on stdin" : `in ${file}`} is empty`);
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        throw new UsageError(`the declaration ${file === undefined ? "on stdin" : `in ${file}`} is not JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+export function renderRead(r) {
+    const lines = [];
+    if (r.current === null || r.current === undefined) {
+        lines.push("no tenant environment declaration yet — nothing is delivered to a phase's checkout");
+        return lines;
+    }
+    lines.push(`revision ${r.current.revision} (${r.current.canonicalHash})${r.current.proposedBy ? `, proposed by ${r.current.proposedBy}` : ""}`);
+    lines.push(r.isApproved ? `approved${r.approvedBy ? ` by ${r.approvedBy}` : ""}` : "NOT approved — it is not delivered until someone approves it");
+    lines.push(r.delivered
+        ? `delivered to phases: revision ${r.delivered.revision} (${r.delivered.canonicalHash})`
+        : "delivered to phases: nothing yet");
+    // A name the declaration references that no tenant secret or variable carries RIGHT NOW. A warning,
+    // never a refusal: the secret may be created next, and a repo may supply the name at checkout.
+    const unresolved = r.unresolvedReferences ?? [];
+    if (unresolved.length > 0) {
+        lines.push(`referenced but not set on this tenant yet: ${unresolved.join(", ")} — add them in the app, or a phase that needs one will fail on it`);
+    }
+    return lines;
+}
+function renderState(state, verb) {
+    if (!state)
+        return [`${verb}, but the cloud returned no state`];
+    return [`${verb}: revision ${state.revision} (${state.canonicalHash})`];
+}
+async function readState(api, routes) {
+    const res = await api.getJson(routes.read);
+    return res.body;
+}
+async function approveExact(api, routes, revision, canonicalHash) {
+    const res = await api.postJson(routes.approve, { revision, canonicalHash }, { accept: [404, 409] });
+    return { body: res.body, status: res.status };
+}
+export async function cmdEnvironment(args, ctx, deps = {}) {
+    const [sub = "read", ...extra] = positionals(args);
+    if (extra.length > 0)
+        throw new UsageError(`environment takes one subcommand (got an extra "${extra[0]}")`);
+    if (sub !== "read" && sub !== "propose" && sub !== "approve") {
+        throw new UsageError(`unknown environment subcommand "${sub}": read | propose | approve`);
+    }
+    const cfg = requireConfig(ctx);
+    const { doc } = await loadContract(ctx, cfg);
+    const routes = environmentRoutes(doc, cfg);
+    const api = apiClient(cfg, ctx);
+    if (sub === "read") {
+        const body = await readState(api, routes);
+        if (args.json)
+            ctx.stdout(JSON.stringify(body));
+        else
+            for (const line of renderRead(body))
+                ctx.stdout(line);
+        return 0;
+    }
+    if (sub === "propose") {
+        const declaration = await readDeclaration(args, deps.readStdin ?? readStdin);
+        const expectedRevision = args.flags["expect-revision"] === undefined ? undefined : flagInt(args, "expect-revision", 0);
+        const res = await api.postJson(routes.propose, { declaration, ...(expectedRevision !== undefined ? { expectedRevision } : {}) }, { accept: [400, 404, 409] });
+        const body = res.body;
+        // A refusal is the cloud's own sentence, printed verbatim and exited 1 — never retried, and never
+        // smoothed into a success. `conflict` means someone else moved the declaration; re-read and redo.
+        if (res.status === 409 || res.status === 400 || res.status === 404) {
+            if (args.json)
+                ctx.stdout(JSON.stringify(body));
+            else {
+                ctx.stdout(`refused (${res.status}): ${body.message ?? body.error ?? "no reason given"}`);
+                if (body.reason)
+                    ctx.stdout(`  reason: ${body.reason}`);
+                if (body.currentRevision !== undefined) {
+                    ctx.stdout(`  the declaration is now at revision ${body.currentRevision} — run \`catalyst-skills environment read\` and propose again from that`);
+                }
+            }
+            return 1;
+        }
+        const approveToo = flagBool(args, "approve");
+        if (!args.json)
+            for (const line of renderState(body.state, body.status === "unchanged" ? "unchanged" : `${body.status ?? "proposed"}`))
+                ctx.stdout(line);
+        if (!approveToo) {
+            if (args.json)
+                ctx.stdout(JSON.stringify(body));
+            else if (body.status !== "unchanged")
+                ctx.stdout("not delivered until it is approved: catalyst-skills environment approve");
+            return 0;
+        }
+        // ⭐ Approve exactly what propose just returned. The whole point of the CAS is that the approver
+        // saw the revision they are approving, and nothing here has to be copied by a human or a model.
+        const state = body.state;
+        if (!state) {
+            ctx.stderr("the cloud returned no state to approve — run: catalyst-skills environment read");
+            return 1;
+        }
+        const approved = await approveExact(api, routes, state.revision, state.canonicalHash);
+        if (args.json) {
+            ctx.stdout(JSON.stringify({ propose: body, approve: approved.body }));
+            return approved.status === 200 ? 0 : 1;
+        }
+        return renderApprove(ctx, approved);
+    }
+    // approve — with no flags, read the current state and approve exactly that.
+    const revisionFlag = args.flags.revision === undefined ? undefined : flagInt(args, "revision", 0);
+    const hashFlag = flagString(args, "hash");
+    if ((revisionFlag === undefined) !== (hashFlag === undefined)) {
+        throw new UsageError("environment approve takes --revision and --hash together, or neither (it reads the current one)");
+    }
+    let revision = revisionFlag;
+    let hash = hashFlag;
+    if (revision === undefined || hash === undefined) {
+        const current = (await readState(api, routes)).current;
+        if (current === null || current === undefined) {
+            ctx.stdout("there is no declaration to approve — propose one first: catalyst-skills environment propose --file <path>");
+            return 1;
+        }
+        revision = current.revision;
+        hash = current.canonicalHash;
+    }
+    const approved = await approveExact(api, routes, revision, hash);
+    if (args.json) {
+        ctx.stdout(JSON.stringify(approved.body));
+        return approved.status === 200 ? 0 : 1;
+    }
+    return renderApprove(ctx, approved);
+}
+function renderApprove(ctx, approved) {
+    const { body, status } = approved;
+    if (status === 200 && body.approved) {
+        for (const line of renderState(body.state, "approved"))
+            ctx.stdout(line);
+        ctx.stdout("it is now what a phase's checkout carries");
+        return 0;
+    }
+    ctx.stdout(`refused (${status}): ${body.message ?? body.error ?? "no reason given"}`);
+    if (body.currentRevision !== undefined) {
+        ctx.stdout(`  it is now at revision ${body.currentRevision}${body.currentHash ? ` (${body.currentHash})` : ""} — read it again before approving`);
+    }
+    return 1;
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}

package/dist/execution.js

@@ -3,8 +3,8 @@
 // exclusion reason and unknown the cloud names; an unlisted reason prints its raw string, never nothing.
 import { flagBool, flagString, positionals } from "./args.js";
 import { normalizeBaseUrl, requireConfig } from "./config.js";
-import { loadContract } from "./contract.js";
-import { CliError, UsageError } from "./errors.js";
+import { findTeamByKey, loadContract } from "./contract.js";
+import { CliError, MeError, UsageError } from "./errors.js";
 import { apiClient } from "./transport.js";
 /** Every exclusion reason the eligibility evaluator names, in plain English. */
 export const EXCLUSION_REASONS = {
@@ -68,6 +68,27 @@ export function describeReason(reason) {
         return "no reason was given";
     return EXCLUSION_REASONS[reason] ?? UNKNOWN_REASONS[reason] ?? `reason "${reason}" (not in this bundle's table; read it as the cloud spelled it)`;
 }
+/** The contract spells the same concept `status`; normalize onto the `cause` the renderer uses.
+ *  `"open"` and an absent/shapeless gate both mean "nothing to report" — null. An unrecognized
+ *  status is passed through as `cause`, never swallowed (D2/D3 — CTC-2208). */
+export function gateFromContract(g) {
+    if (!g || typeof g.status !== "string")
+        return null;
+    if (g.status === "open")
+        return null;
+    return { cause: g.status, missingSlots: g.missingSlots, remedy: g.remedy, source: "contract" };
+}
+/** True when the live eligibility read failed in a way a cached gate may stand in for: the read was
+ *  UNAVAILABLE (network/timeout/non-JSON, or a 404/5xx). A cloud that ANSWERED — 401/403/400 — is
+ *  refusing, not silent, and a cached gate must never hide that refusal behind an unrelated mapping
+ *  story (D4 — CTC-2208). */
+export function liveReadMayFallBack(err) {
+    if (err instanceof MeError)
+        return true;
+    if (err instanceof CliError)
+        return err.status === undefined || err.status === 404 || err.status >= 500;
+    return false;
+}
 export function renderDispatchGate(ticket, team, gate) {
     const slots = (gate.missingSlots ?? []).join(", ");
     const why = gate.cause === "mapping_state_unresolved"
@@ -136,26 +157,87 @@ export async function cmdExplain(args, ctx) {
         throw new UsageError(`"${ticket}" is not a ticket identifier (expected KEY-123)`);
     const team = ticket.slice(0, dash).toUpperCase();
     const api = apiClient(cfg, ctx);
-    const res = await api.getJson("/api/v1/work-eligibility", {
-        query: { team, capabilities: doc.ladder.phases.join(",") },
-    });
-    const rows = res.body.eligibility?.rows ?? res.body.rows ?? [];
-    const row = rows.find((r) => String(r.ticket ?? "").toUpperCase() === ticket.toUpperCase()) ?? null;
-    // No dispatch row is not proof of non-existence: probe the mirror so a Backlog ticket reads as known.
-    // The mirror compares identifiers exactly, so normalize (uppercase) as the row lookup above does —
-    // otherwise `explain eng-7` probes a lowercase id, 404s, and reports an existing ENG-7 as unknown.
+    // The cached contract's own gate for this team. Read BEFORE the live call so it can stand in when
+    // that call cannot be made at all. A team absent from the contract simply has none.
+    const cachedGate = gateFromContract(findTeamByKey(doc, team)?.dispatchGate);
+    let row = null;
     let knownState = null;
+    let liveGate = null;
+    let liveFailure = null;
+    let liveGateRaw = null;
+    // This `try` wraps the eligibility read ALONE. It used to span the mirror probe below as well,
+    // which broke both reads at once: a probe outage was reported as "the live eligibility read was
+    // unavailable", and an eligibility outage skipped the probe entirely so `knownState` stayed null
+    // and a mistyped id inherited the team-wide gate — the very bug 4defc34 was written to fix.
+    try {
+        const res = await api.getJson("/api/v1/work-eligibility", { query: { team, capabilities: doc.ladder.phases.join(",") } });
+        const rows = res.body.eligibility?.rows ?? res.body.rows ?? [];
+        row = rows.find((r) => String(r.ticket ?? "").toUpperCase() === ticket.toUpperCase()) ?? null;
+        liveGateRaw = res.body.eligibility?.dispatchGate ?? null;
+    }
+    catch (err) {
+        // A cached gate is an answer the live read cannot give right now — but ONLY for a failure that
+        // means "unavailable". A 401/403/400 is the cloud answering, and must still refuse (CTC-2208 D4).
+        if (!cachedGate || !liveReadMayFallBack(err))
+            throw err;
+        liveFailure = err instanceof Error ? err : new Error(String(err));
+    }
+    // No dispatch row is not proof of non-existence: probe the mirror so a Backlog ticket reads as
+    // known. The mirror compares identifiers exactly, so normalize as the row lookup above does —
+    // otherwise `explain eng-7` probes a lowercase id, 404s, and reports an existing ENG-7 unknown.
+    // Deliberately OUTSIDE the `try`: the probe is the ONLY read that can prove this id exists, so it
+    // must still run when the eligibility read was unavailable, and its own failure must surface as
+    // itself — a refusal naming the /issues/ read — never as a gate paragraph or as an eligibility
+    // failure. That is the pre-4defc34 behaviour for this call and it is restored unchanged.
     if (!row) {
         const probe = await api.getJson(`/api/v1/issues/${encodeURIComponent(ticket.toUpperCase())}`, { accept: [404] });
         if (probe.status !== 404)
             knownState = typeof probe.body?.state === "string" ? probe.body.state : "unknown";
     }
-    // The gate is TEAM-wide: it can say why a real ticket in that team cannot start, never that this id
-    // exists. Applied only when the mirror probe above found the ticket; a 404 keeps the unknown wording.
-    const gate = !row && knownState ? (res.body.eligibility?.dispatchGate ?? null) : null;
-    const explanation = renderExplain(ticket, row, team, knownState, gate);
+    // The gate is TEAM-wide: it can say why a real ticket in that team cannot start, never that this
+    // id exists. Applied only when the probe found the ticket; a 404 keeps the unknown wording.
+    liveGate = !row && knownState && liveGateRaw ? { ...liveGateRaw, source: "live" } : null;
+    // The cached gate is team-wide too, so it answers on exactly the same condition as the live one:
+    // the mirror found the ticket and no row explains it. An unavailable eligibility read licenses the
+    // FALLBACK, never the claim that this id exists.
+    const usingCached = !liveGate && !row && knownState !== null;
+    const gate = liveGate ?? (usingCached ? cachedGate : null);
+    // Both sides spoke and disagreed: the live read wins, and the paragraph says the cache disagreed.
+    // Computed together with its sentence so the "live is non-null here" fact never needs re-asserting.
+    let overridden = null;
+    let overriddenNote = null;
+    if (liveGate && cachedGate && liveGate.cause !== cachedGate.cause) {
+        overridden = cachedGate;
+        overriddenNote = `The cached tenant contract says ${cachedGate.cause}; this live eligibility read says ${liveGate.cause} and wins.`;
+    }
+    // A live read that produced a row contradicts a cached "nothing in this team can start".
+    const contradictedByRow = !liveFailure && row && cachedGate ? cachedGate : null;
+    const parts = [renderExplain(ticket, row, team, knownState, gate)];
+    if (gate && gate === cachedGate) {
+        parts.push(liveFailure
+            ? `Read from the cached tenant contract: the live eligibility read was unavailable (${liveFailure.message}).`
+            : "Read from the cached tenant contract: this cloud's eligibility read sent no dispatch gate.");
+    }
+    if (overriddenNote)
+        parts.push(overriddenNote);
+    // The mirror answered and the eligibility read did not: say so, rather than let a network outage
+    // read as a confident verdict from an explainer this run never actually reached.
+    if (liveFailure && gate !== cachedGate) {
+        parts.push(`The live eligibility read was unavailable (${liveFailure.message}); only the mirror answered.`);
+    }
+    if (contradictedByRow) {
+        parts.push(`The cached tenant contract says ${contradictedByRow.cause} for team ${team}; this live eligibility read has a row for ${ticket} and wins.`);
+    }
+    const explanation = parts.join(" ");
     if (args.json) {
-        ctx.stdout(JSON.stringify({ ticket, row, ...(gate ? { dispatchGate: gate } : {}), explanation }));
+        ctx.stdout(JSON.stringify({
+            ticket,
+            row,
+            ...(gate ? { dispatchGate: gate } : {}),
+            ...(overridden || contradictedByRow ? { dispatchGateOverridden: overridden ?? contradictedByRow } : {}),
+            ...(liveFailure ? { liveReadFailed: liveFailure.message } : {}),
+            explanation,
+        }));
     }
     else {
         ctx.stdout(explanation);