@catalyst-cloud/cli 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.9.2
+
+The CLI works against a tenant serving contract 2.x. Catalyst Cloud's tenant contract moved to 2.0.0 when it removed `merge.cloudRemediateRequiredChecks`, and every earlier bundle accepted only 1.x, so `ready`, onboarding and most commands stopped with "the tenant serves contract version 2.2.0 but this bundle accepts 1.x". This bundle accepts `1.x || 2.x`. The one place that read the removed field already treated it as absent.
+
+## 0.9.1
+
+Onboarding now teaches `.catalyst/catalyst.toml`, the only file the cloud reads a repository's settings from. The skills still described `catalyst.env.json`, which the cloud has ignored since 2026-09-27, so a declaration written from them was silently dropped. The repository reference shows the file's shape (`[project]` with `linear_team`, then `[[environment.variables]]` and `[[environment.setup]]`) and the approval step: an owner or admin opens the repository's Environment page, goes to the Setup declaration tab, and clicks Approve this revision.
+
+A ticket filed through the catalyst-linear skill now carries a description: `catalyst write create` takes `--description <text>` or `--stdin`, where before it could file only a title. The skill content never asks for a personal Linear token or a direct Linear API call.
+
 ## 0.9.0
 
 Onboarding now guides your own Linear and GitHub consent. `catalyst connections personal <linear|github> start` opens the provider's consent page in your browser and `status` confirms the grant landed; the tenant's own Linear connection and GitHub App install stay separate, and personal GitHub waits until the App is installed and a repository is registered.

package/README.md

@@ -163,13 +163,13 @@ Some of these only read; the ones that write anything — or that drive you thro
 
 ## 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. 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 cloud — reading needs any active seat, proposing and approving need an admin or owner one. An admin or owner can put a repository's values in from the terminal. `catalyst-skills secret import .env --repo owner/name` stores every name in the file and lists the declared names that still have no value. `catalyst-skills secret set NAME --repo owner/name --command 'op read op://Vault/item/field'` runs the command on your machine and stores its output; with no `--command` it reads the value from stdin, or asks for it without echoing. No value is ever printed, and the cloud's audit records the command, not its output. 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:
+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 cloud — reading needs any active seat, proposing and approving need an admin or owner one. An admin or owner can put a repository's values in from the terminal. `catalyst-skills secret import .env --repo owner/name` stores every name in the file and lists the declared names that still have no value. `catalyst-skills secret set NAME --repo owner/name --command 'op read op://Vault/item/field'` runs the command on your machine and stores its output; with no `--command` it reads the value from stdin, or asks for it without echoing. No value is ever printed, and the cloud's audit records the command, not its output. That is the account's own declaration — a repository's own `.catalyst/catalyst.toml`, 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, and that line now also carries the version it was vendored at; all of them are written in this repository for customer tenants.
+The package pins the tenant contract range `1.x || 2.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
 
@@ -209,7 +209,7 @@ npm uninstall -g @catalyst-cloud/catalyst-skills
 - `catalyst-skills: GET /me failed (401): credential not accepted — mint a personal key at Settings → API keys and log in again` — the key is stale, mistyped or revoked. Mint a new one, then run `login` again.
 - `catalyst-skills: GET /me failed (403): account-not-operational` — the tenant is suspended. This is an admin conversation on the tenant, not a local fix.
 - `catalyst-skills: could not reach <url>: <detail>` — the machine cannot reach the cloud. The URL is named in the message; check `CATALYST_CLOUD_BASE_URL` or `--base-url`.
-- A line naming two contract versions after `Connected to` — the tenant serves a contract outside this bundle's `1.x` range. The config is written; update the bundle before using the other skills.
+- A line naming two contract versions after `Connected to` — the tenant serves a contract outside this bundle's `1.x || 2.x` range. The config is written; update the bundle before using the other skills.
 - `[catalyst-skills] GET /api/v1/agent/contract refused (403): this cloud is older than the bundle …` on stderr — the cloud has not yet deployed personal-key access to the contract. Update the cloud, or connect with the tenant's account key until it has.
 
 ## License

package/dist/args.js

@@ -74,7 +74,7 @@ export const FLAG_TABLES = {
     },
     write: {
         body: { value: true, help: "comment: the body text" },
-        stdin: { value: false, help: "comment: read the body from stdin" },
+        stdin: { value: false, help: "comment: read the body from stdin; create: read the description from stdin" },
         parent: { value: true, help: "comment: reply under this comment id" },
         bookkeeping: { value: false, help: "comment: prefix the contract's bookkeeping marker" },
         "as-user": { value: false, help: "post with the personal identity instead of the app actor" },
@@ -85,6 +85,7 @@ export const FLAG_TABLES = {
         remove: { value: true, repeat: true, help: "label: label name or id to remove (repeatable)" },
         team: { value: true, help: "create: team key" },
         title: { value: true, help: "create/attachment/session: title" },
+        description: { value: true, help: "create: the ticket description (markdown)" },
         label: { value: true, repeat: true, help: "create: label name or id (repeatable)" },
         priority: { value: true, help: "create: Linear priority 0-4" },
         comment: { value: true, help: "reaction: react to this comment id instead of the ticket" },
@@ -152,7 +153,7 @@ export const VERB_USAGE = {
     running: "running [--ticket T --phase P] [--json]",
     queue: "queue [--team K] [--json]",
     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]>",
+    write: "write <comment <ticket> --body|--stdin [--parent] [--bookkeeping] [--as-user] | state <ticket> --slot|--state-id|--state-type | label <ticket> --add... --remove... | create --team --title [--description|--stdin] [--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] [--offline]",
     accounts: "accounts [--json]",

package/dist/contract.js

@@ -29,8 +29,15 @@ export function writeContractCache(home, cache) {
     renameSync(tmp, path);
     return path;
 }
-/** `1.x` → major 1; `1.2.3` → exact; `unpinned` → anything. Returns null when the range is unparseable. */
+/** `1.x` → major 1; `1.2.3` → exact; `unpinned` → anything; `1.x || 2.x` → any alternative matches.
+ *  Returns null when the range (or any alternative) is unparseable. */
 export function contractVersionInRange(version, range) {
+    if (range.includes("||")) {
+        const results = range.split("||").map((part) => contractVersionInRange(version, part.trim()));
+        if (results.some((r) => r === null))
+            return null;
+        return results.some((r) => r === true);
+    }
     if (range === "unpinned")
         return true;
     const major = /^(\d+)\.x$/.exec(range);

package/dist/execution.js

@@ -312,7 +312,7 @@ export async function cmdQueue(args, ctx) {
 }
 /** The five status words `/api/v1/coding-accounts` reports, in the words a customer reads. */
 export const ACCOUNT_STATUS = {
-    "expired-or-revoked": "expired or revoked — re-enrol it before it can take work",
+    "expired-or-revoked": "expired or revoked — replace its credential on the AI accounts page (Settings → AI accounts → the account → Replace credential) before it can take work",
     walled: "walled — the provider's usage limit is spent for now",
     active: "active — observed working",
     attested: "attested — healthy at last check, no work observed since",

package/dist/oauth.js

@@ -65,41 +65,66 @@ export async function fetchDiscovery(ctx, baseUrl, opts = {}) {
     }
     return doc;
 }
+/**
+ * CTC-2136: how many device codes one login mints before it gives up. A code lives `expires_in`
+ * (300 s at WorkOS), which a first sign-in from a phone can outlast, so an expired code is replaced
+ * in the same process rather than ending the login. Ryan's call (2026-09-28): up to 3 codes.
+ */
+export const MAX_DEVICE_CODES = 3;
 /**
  * Run the device-authorization grant to completion and return the stored session block. Prints the
- * user code and where to enter it; on a TTY it also opens the completion URL. Polls at the server's
- * `interval`, honours `slow_down`, and is bounded by `AbortSignal.timeout(expires_in)` so it can
- * never poll past the device code's own lifetime.
+ * user code, where to enter it, and the one-click link when the server sends one; on a TTY it also
+ * opens the browser. Each code is polled at the server's `interval`, honouring `slow_down`, and is
+ * bounded by `AbortSignal.timeout(expires_in)` so it can never poll past its own lifetime. When a code
+ * expires, a fresh one is minted and printed, up to MAX_DEVICE_CODES in all.
  */
 export async function deviceFlowLogin(ctx, baseUrl, deps = {}) {
     const sleep = deps.sleep ?? defaultSleep;
     const discovery = await fetchDiscovery(ctx, baseUrl);
-    const auth = await deviceAuthorize(ctx, discovery);
-    ctx.stdout("");
-    ctx.stdout(`To connect this machine, visit:  ${auth.verification_uri}`);
-    ctx.stdout(`and enter the code:              ${auth.user_code}`);
-    if ((deps.isTty ?? (() => false))()) {
-        try {
-            (deps.openBrowser ?? (() => { }))(auth.verification_uri_complete);
-            ctx.stdout("Opened your browser to that page — approve there, or use the code above.");
-        }
-        catch {
-            // a browser that will not open is not a failure; the code and URL still work
+    // The browser rule is decided on the first code; a later code re-opens it only when the first did.
+    let browserOpened = false;
+    for (let round = 1; round <= MAX_DEVICE_CODES; round++) {
+        const auth = await deviceAuthorize(ctx, discovery);
+        if (round > 1)
+            ctx.stdout(`That code expired. Here is a new one (${round} of ${MAX_DEVICE_CODES}):`);
+        ctx.stdout("");
+        ctx.stdout(`To connect this machine, visit:  ${auth.verification_uri}`);
+        ctx.stdout(`and enter the code:              ${auth.user_code}`);
+        if (auth.verification_uri_complete)
+            ctx.stdout(`Or open this link, which fills the code in: ${auth.verification_uri_complete}`);
+        if (round === 1 ? (deps.isTty ?? (() => false))() : browserOpened) {
+            try {
+                (deps.openBrowser ?? (() => { }))(auth.verification_uri_complete ?? auth.verification_uri);
+                browserOpened = true;
+                ctx.stdout("Opened your browser to that page — approve there, or use the code above.");
+            }
+            catch {
+                // a browser that will not open is not a failure; the code and URL still work
+            }
         }
+        ctx.stdout("Waiting for you to approve… (Ctrl-C to cancel)");
+        const tokens = await pollDeviceCode(ctx, discovery, auth, sleep);
+        if (tokens !== "expired")
+            return tokensToAuth(ctx, tokens.access_token, tokens.refresh_token);
     }
-    ctx.stdout("Waiting for you to approve… (Ctrl-C to cancel)");
-    // Terminal states print ONE clear, actionable line and exit 2 (CliError's default). The duration
-    // comes from the device code's own `expires_in`, so it is right whatever the server set.
-    const mins = Math.round(auth.expires_in / 60);
-    const expired = () => new CliError(`the login code expired${mins >= 1 ? ` after ${mins} minute${mins === 1 ? "" : "s"}` : ""} — run: catalyst-skills login again`, "login-expired");
+    // Every code lapsed unapproved. The exit code (2, CliError's default) and the `login-expired` code are
+    // unchanged from before CTC-2136; only the line is new, and its wording is Ryan's.
+    throw new CliError(`The sign-in code expired ${MAX_DEVICE_CODES} times. Run the same command again when you are ready to approve.`, "login-expired");
+}
+/**
+ * Poll one device code until it yields a token pair or expires. Terminal refusals (`access_denied`,
+ * a non-transient error) throw; expiry, by the server's `expired_token` or the code's own
+ * `expires_in` lapsing, returns "expired" so the caller can mint the next code.
+ */
+async function pollDeviceCode(ctx, discovery, auth, sleep) {
     const deadline = AbortSignal.timeout(auth.expires_in * 1_000);
     let intervalMs = Math.max(1, auth.interval) * 1_000;
     for (;;) {
         await sleep(intervalMs);
-        // The device code's own lifetime bounds the loop: once it lapses, say so plainly rather than
+        // The device code's own lifetime bounds the loop: once it lapses, treat it as expired rather than
         // letting the next fetch's aborted signal surface as a generic network error (Codex P2).
         if (deadline.aborted)
-            throw expired();
+            return "expired";
         let res;
         try {
             res = await safeFetch(ctx, discovery.tokenUrl, { method: "POST", headers: formHeaders(), body: form({ grant_type: "urn:ietf:params:oauth:grant-type:device_code", device_code: auth.device_code, client_id: discovery.clientId }) }, deadline);
@@ -108,7 +133,7 @@ export async function deviceFlowLogin(ctx, baseUrl, deps = {}) {
             // The deadline firing mid-fetch is an expiry, not a failure; anything else is a transient
             // network blip — retry with backoff until the deadline, never abandon the login (CTC-2112 P1).
             if (deadline.aborted)
-                throw expired();
+                return "expired";
             intervalMs = backoff(intervalMs);
             continue;
         }
@@ -117,7 +142,7 @@ export async function deviceFlowLogin(ctx, baseUrl, deps = {}) {
             if (typeof pair.access_token !== "string" || typeof pair.refresh_token !== "string") {
                 throw new CliError("the login token response was missing a token", "login-shape");
             }
-            return tokensToAuth(ctx, pair.access_token, pair.refresh_token);
+            return { access_token: pair.access_token, refresh_token: pair.refresh_token };
         }
         const err = await oauthError(res, discovery.tokenUrl);
         if (err === "authorization_pending")
@@ -129,7 +154,7 @@ export async function deviceFlowLogin(ctx, baseUrl, deps = {}) {
         if (err === "access_denied")
             throw new CliError("login was denied — run: catalyst-skills login to try again", "login-denied");
         if (err === "expired_token")
-            throw expired();
+            return "expired";
         // A transient HTTP failure (request timeout, rate limit, server error) is retried, honouring
         // Retry-After for a 429; only a genuine, non-transient refusal ends the loop.
         if (res.status === 408 || res.status === 429 || res.status >= 500) {
@@ -178,7 +203,7 @@ async function deviceAuthorize(ctx, discovery) {
         device_code: d.device_code,
         user_code: d.user_code,
         verification_uri: d.verification_uri,
-        verification_uri_complete: d.verification_uri_complete ?? d.verification_uri,
+        ...(typeof d.verification_uri_complete === "string" && d.verification_uri_complete !== "" ? { verification_uri_complete: d.verification_uri_complete } : {}),
         expires_in: typeof d.expires_in === "number" ? d.expires_in : 300,
         interval: typeof d.interval === "number" ? d.interval : 5,
     };

package/dist/skill-shape.js

@@ -27,6 +27,10 @@ export const FORBIDDEN_CONTENT = [
     { name: "an internal ticket id", re: /\bC[TL]C-\d+\b/ },
     { name: "a Linear CLI name (linearis)", re: /linearis/i },
     { name: "the internal replica tool name (catalyst-replica)", re: /catalyst-replica/ },
+    // A tenant workflow writes through the tenant's agent proxy as the app actor. A personal Linear
+    // token, or a call straight to Linear's API, is the path these skills exist to replace.
+    { name: "a personal Linear API token (LINEAR_API_TOKEN / LINEAR_API_KEY)", re: /LINEAR_API_(?:TOKEN|KEY)/ },
+    { name: "Linear's API host (api.linear.app)", re: /api\.linear\.app/ },
 ];
 function walk(dir) {
     const out = [];

package/dist/write.js

@@ -149,12 +149,21 @@ export async function cmdWrite(args, ctx, deps = {}) {
             const title = flagString(args, "title");
             if (!teamKey || !title)
                 throw new UsageError("write create needs --team <key> and --title <text>");
+            let description = flagString(args, "description");
+            if (flagBool(args, "stdin")) {
+                if (description !== undefined)
+                    throw new UsageError("write create takes --description <text> or --stdin, not both");
+                description = (await (deps.readStdin ?? readStdin)()).trimEnd();
+                if (!description)
+                    throw new UsageError("write create --stdin read an empty description");
+            }
             const team = teamByKey(doc, teamKey);
             const labels = flagList(args, "label").map((n) => labelId(team, n));
             const priority = flagString(args, "priority") !== undefined ? flagInt(args, "priority", 0) : undefined;
             result = await postAgent(api, doc, "issue-create", {
                 teamId: team.id,
                 title,
+                ...(description ? { description } : {}),
                 ...(labels.length ? { labelIds: labels } : {}),
                 ...(priority !== undefined ? { priority } : {}),
                 ...(asUser ? { createAsUser: true } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Customer skill bundle for Catalyst Cloud, named from the executive's seat — get set up, see what is happening, see what needs you, run a project, unstick what is stuck — plus the catalyst CLI that reads through the Catalyst Cloud SDK, writes through the agent proxy, and connects your machine to your tenant with one command. The skills directory is the roster; this line never counts it.",
   "license": "MIT",
   "type": "module",
@@ -32,7 +32,7 @@
     "vendor"
   ],
   "catalystCloud": {
-    "tenantContractRange": "1.x",
+    "tenantContractRange": "1.x || 2.x",
     "pinnedNode": "24.21.0"
   },
   "scripts": {

package/skills/catalyst-github/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's GitHub: show a ticket's pull request with its checks, reviews and review threads, say whether it is mergeable under this repository's policy, and explain what a PR accumulates as the ticket moves (the branch, the draft, the rewrite, the force-pushes, the labels, the queue). Use when someone asks "show me the PR", "what are the checks saying", "why hasn't it merged", "what does the queue need", "what does that label mean", or wants the branch and merge conventions Catalyst follows.
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.2 — written in this repository for customer tenants -->
 
 # Catalyst's GitHub
 

package/skills/catalyst-github/references/is-it-mergeable.md

@@ -16,7 +16,7 @@ Merge evidence has three independent legs. Two are unconditional under every pol
 | reviewer | the reviewer signal the policy accepts (below) | only under a reviewer-attestation policy |
 | threads | zero unresolved review threads, and no resolved thread whose resolving commit has left the head | yes |
 
-Which checks are gating: the names the queue configuration itself requires, plus any extra gating check the cloud names. The contract serves the checks the cloud's own remediation waits on as `cloudRemediateRequiredChecks`; a check that cannot block a merge is informational and never a reason to withhold the label.
+Which checks are gating: the names the queue configuration itself requires, plus any extra gating check the cloud names. A 1.x contract also serves the checks the cloud's own remediation waits on as `cloudRemediateRequiredChecks`; a 2.x contract no longer carries it, so only the queue configuration's names gate there; a check that cannot block a merge is informational and never a reason to withhold the label.
 
 ## The policies
 

package/skills/catalyst-github/references/what-a-pr-accumulates.md

@@ -1,6 +1,6 @@
 # What a pull request accumulates as Catalyst moves a ticket
 
-Most of this page restates invariants: how Catalyst names branches, opens and rewrites pull requests, and what it pushes when. The parts that vary per tenant are read live from the contract's `merge` block and never restated here: the reviewer's login (`merge.reviewerLogin`), which clean-pass shapes are honoured (`merge.cleanPassShapes[]`), the four PR label names (`merge.prLabels`), the checks the cloud waits on (`merge.cloudRemediateRequiredChecks`), and the policy per repository (`merge.repositories[]`, else `merge.defaultPolicy`). `catalyst-skills contract --path merge` prints them.
+Most of this page restates invariants: how Catalyst names branches, opens and rewrites pull requests, and what it pushes when. The parts that vary per tenant are read live from the contract's `merge` block and never restated here: the reviewer's login (`merge.reviewerLogin`), which clean-pass shapes are honoured (`merge.cleanPassShapes[]`), the four PR label names (`merge.prLabels`), the checks the cloud waits on (`merge.cloudRemediateRequiredChecks`, on a 1.x contract only), and the policy per repository (`merge.repositories[]`, else `merge.defaultPolicy`). `catalyst-skills contract --path merge` prints them.
 
 ## The branch
 

package/skills/catalyst-linear/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 disable-model-invocation: true
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.2 — written in this repository for customer tenants -->
 
 # Catalyst Linear
 
@@ -20,7 +20,7 @@ Run each with `--help` first; scripts are executed, never read.
 - `node scripts/comment.mjs <ticket> --body <text> [--parent <id>] [--bookkeeping]` — a comment as the app actor; a machine record takes `--bookkeeping`.
 - `node scripts/move.mjs <ticket> --slot <slot>` — a card move by slot (`--state-type backlog` parks).
 - `node scripts/label.mjs <ticket> --add <name> --remove <name>` — labels, resolved through the contract.
-- `node scripts/create-ticket.mjs --team <key> --title <text>` — a new ticket; cite its identifier only after it prints.
+- `node scripts/create-ticket.mjs --team <key> --title <text> [--description <text> | --stdin]` — a new ticket; cite its identifier only after it prints.
 
 Exit codes: 0 done, 1 not found or a usage error, 2 this machine is not connected or the write was refused (budget spent, slot unmapped, label absent; the one line printed says which).
 

package/skills/catalyst-linear/references/writing-to-linear.md

@@ -9,7 +9,7 @@ This reference restates the write mechanism. The live values it depends on — t
 | a comment, threaded or top-level | `node scripts/comment.mjs <ticket> --body <text> [--parent <commentId>] [--bookkeeping]` |
 | a card move | `node scripts/move.mjs <ticket> --slot <slot>` or `--state-type backlog` |
 | a label on or off | `node scripts/label.mjs <ticket> --add <name> --remove <name>` |
-| a new ticket | `node scripts/create-ticket.mjs --team <key> --title <text>` |
+| a new ticket | `node scripts/create-ticket.mjs --team <key> --title <text> [--description <text> \| --stdin]` |
 | a decision for a human | not here: the `what-needs-me` skill raises an ask with options, a default and what it blocks |
 
 Each script wraps one `catalyst-skills write` verb, which posts to the route the contract names, as the tenant's app actor, with the personal key this machine connected with — so the write carries the person's identity for attribution, and an ask names them. No script composes a URL, and none needs a Linear credential of its own.
@@ -36,7 +36,7 @@ Two labels are a human's, not yours: the release label (which frees a ticket the
 
 ## A new ticket takes the team key
 
-`create-ticket.mjs --team <key>` names the team by the prefix its identifiers carry; the CLI resolves the team id from the contract and the cloud fences the write to your tenant on the team, not only on the credential. Cite the identifier only after the script prints it; a guessed number is usually a real, unrelated ticket. Do not file a question for a human this way: a ticket whose text reads as a decision request is held out of dispatch by shape until someone releases it, and it would never reach the human's inbox with what it blocks.
+`create-ticket.mjs --team <key>` names the team by the prefix its identifiers carry; the CLI resolves the team id from the contract and the cloud fences the write to your tenant on the team, not only on the credential. A ticket's body goes in `--description`, or on stdin with `--stdin` when it runs to several lines; a title with no body gives whoever picks the ticket up nothing to act on. Cite the identifier only after the script prints it; a guessed number is usually a real, unrelated ticket. Do not file a question for a human this way: a ticket whose text reads as a decision request is held out of dispatch by shape until someone releases it, and it would never reach the human's inbox with what it blocks.
 
 ## What is never offered
 

package/skills/catalyst-linear/scripts/create-ticket.mjs

@@ -2,14 +2,17 @@
 // create-ticket.mjs — file a new ticket on a team as the app actor. The team is named by its key;
 // the CLI resolves the team id from the contract. A decision for a human is NOT a ticket filed here:
 // that is an ask, raised through the what-needs-me skill so it carries options, a default and blocks.
+import { readFileSync } from "node:fs";
 import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wantsHelp } from "./lib/cli.mjs";
 
-const HELP = `Usage: node scripts/create-ticket.mjs --team <key> --title <text> [--label <name|id>]... [--priority <0-4>] [--as-user] [--json]
+const HELP = `Usage: node scripts/create-ticket.mjs --team <key> --title <text> [--description <text> | --stdin] [--label <name|id>]... [--priority <0-4>] [--as-user] [--json]
 
 Creates one ticket. Wraps: catalyst-skills write create. Spends one unit of the daily write budget.
 
   --team <key>          the team key (the prefix of its ticket identifiers)
   --title <text>        the ticket title
+  --description <text>  the ticket description, in markdown
+  --stdin               read the description from stdin instead (for a multi-line body)
   --label <name|id>     a label to apply (repeatable); Catalyst label names resolve via the contract
   --priority <0-4>      Linear priority: 0 none, 1 urgent, 2 high, 3 medium, 4 low
   --as-user             create with the personal identity instead of the app actor (rare)
@@ -26,14 +29,22 @@ if (wantsHelp(argv)) {
   console.log(HELP);
   process.exit(0);
 }
-const { flags } = parseFlags(argv, { bool: ["as-user", "json"], value: ["team", "title", "priority"], repeat: ["label"] });
+const { flags } = parseFlags(argv, { bool: ["stdin", "as-user", "json"], value: ["team", "title", "description", "priority"], repeat: ["label"] });
 if (!flags.team || !flags.title) usage("create-ticket needs --team <key> and --title <text> (see --help)");
+if (flags.description && flags.stdin) usage("give --description or --stdin, not both");
 
 const args = ["write", "create", "--team", flags.team, "--title", flags.title, "--json"];
+if (flags.description) args.push("--description", flags.description);
+let stdin;
+if (flags.stdin) {
+  stdin = readFileSync(0, "utf8");
+  if (!stdin.trim()) usage("stdin was empty");
+  args.push("--stdin");
+}
 for (const l of flags.label ?? []) args.push("--label", l);
 if (flags.priority !== undefined) args.push("--priority", flags.priority);
 if (flags["as-user"]) args.push("--as-user");
-const r = runCli(args);
+const r = runCli(args, { stdin });
 exitOnFailure(r);
 relayStderr(r);
 const result = parseJson(r.stdout);

package/skills/catalyst-onboard/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.2 — written in this repository for customer tenants -->
 
 # Onboard me
 
@@ -13,6 +13,8 @@ You take one person from "the skills are installed" to "a ticket is running on m
 
 Setup has seven parts and each is read by its own instrument: this **machine**, the **person**, the **account**, one **project** (a project is one Linear team), one **repository**, the **coding accounts** a phase runs on, and the **host**. Never say work can run while either of the last two is unfinished. A failure in one is not a failure in another, and a failing part names who can fix it and where. Getting that wrong is the one mistake that wastes a person's afternoon: a project problem reported as a machine problem sends them retrying a local command that was never going to help.
 
+The path also has the person confirm their org's `<org>/thoughts` repository and give the GitHub App access to it (step 5a). The script can show that repository exists, never that the App can reach it.
+
 ## Run first
 
 Scripts are run, never read. Each prints `--help`.
@@ -37,6 +39,7 @@ Start every session with it, and run it again after every step the person comple
 | the person asks how to install, update, or migrate Catalyst skills | `references/skill-sources.md` |
 | the person's repository needs environment names declared | `references/declaring-a-repository.md` |
 | the `coding accounts` or `host` part is not ok, or you are about to say work can run | `references/what-a-phase-needs.md` |
+| the script says a coding account needs a new credential | `references/replacing-a-credential.md` |
 | setup is finished and they want the standing readiness verdict | the `catalyst-setup` skill |
 | the first ticket did not start and you need the reason | the `how-catalyst-works` skill, then `unstick` |
 

package/skills/catalyst-onboard/references/declaring-a-repository.md

@@ -8,15 +8,36 @@ The cloud containers build and test the repository. They need the names of the v
 2. For each name, record the file it came from: a `.env.example` (never `.env`, which holds live values), a CI secret in a workflow's `env:` block, or a platform binding. A name you cannot tie to a file is a guess. Say so instead of listing it.
 3. Mark whether the container needs it to build and test, or only to deploy. Containers build and test. They do not deploy.
 4. Leave platform bindings and deploy-only CI secrets out by default. The platform supplies a binding at run time, and no build or test reads a deploy-only secret. Include one only when the person says the build needs it, and say why.
-5. Write the names into `catalyst.env.json` at the repository root and open a pull request. Use that exact name and place; the cloud reads no other file. It reads the file once the pull request merges to the default branch. A tenant owner or admin then approves it at Settings → Repositories → the repository → Environment, and the person enters the values on that page.
+5. Write the names into `.catalyst/catalyst.toml` and open a pull request. Use that exact path. The cloud reads no other file, and an older `catalyst.env.json` is ignored. Once the pull request merges, each push to the default branch that touches the file makes the cloud read it and propose it as a new revision. A tenant owner or admin opens Settings → Repositories → the repository → Environment → Setup declaration and clicks Approve this revision. The person enters the values on the same page's Environment variables and Secrets tabs.
 
 ## The file's shape
 
-`"version": 1` plus eight arrays, each present even when empty: `toolchains`, `systemPackages`, `setup`, `verify`, `services`, `environment`, `agentAssets`, `provenance`. The repository's Environment page in the app shows a complete, valid example. Start from it rather than from memory.
+`[project]` with `linear_team` is required. Every other section is optional. The names a build needs go under `[environment]`:
 
-- `setup` and `verify` carry this repository's own install and test commands. `command` is an argument list, not a shell string.
-- Each name under `environment` says whether it is `required`. Add `"secret": true` beside a secret.
-- Each `provenanceIds` entry points at a record under `provenance` that names the file the name came from.
+```toml
+#:schema https://staging.catalystcloud.dev/schemas/catalyst.schema.json
+
+[project]
+linear_team = "ENG"
+
+[[environment.variables]]
+name = "DATABASE_URL"
+required = true
+
+[[environment.variables]]
+name = "STRIPE_API_KEY"
+required = true
+secret = true
+
+[[environment.setup]]
+name = "install"
+run = ["npm", "ci"]
+```
+
+- `linear_team` is the key of the Linear team this repository's work belongs to.
+- Each `[[environment.variables]]` entry names one variable and says whether it is `required`. Add `secret = true` for a secret. Names only: a value never goes in this file.
+- `[[environment.setup]]` steps carry this repository's own install commands. `run` is an argument list, not a shell string, and `name` is kebab-case. `verify` steps have the same shape and carry the test commands. `toolchains`, `system_packages`, `services` and the other `[environment]` tables are optional; the schema lists their fields.
+- The `#:schema` line lets an editor check the file as you type.
 
 ## After the merge
 

package/skills/catalyst-onboard/references/replacing-a-credential.md

@@ -0,0 +1,47 @@
+# Replacing a coding account's credential
+
+When the script prints "<provider> account <slot> needs a new credential", replace that account's credential on its own page. Do not enroll a second account. A second account is a duplicate, and the dead one stays in place.
+
+## Why an account needs one
+
+The script flags an account in three cases:
+
+- it is quarantined;
+- it is expired or revoked;
+- its last polls failed on the credential itself, such as `no_access_token`, three or more times in a row. The script can see this only when the cloud reports each account's polls.
+
+Other accounts can be healthy at the same time. The contract can still say `enrolled`, so that line alone never proves every account works.
+
+## Who does it
+
+A tenant owner or admin, in the browser. The person copies the credential and pastes it. You never read it, print it, or paste it. The script prints the page link; use it, and never type a host.
+
+## Codex
+
+The person runs these steps on their own machine:
+
+1. Run `codex login` and choose "Sign in with ChatGPT".
+2. The login writes `~/.codex/auth.json`. If `CODEX_HOME` is set, the file is `$CODEX_HOME/auth.json`. On macOS, `pbcopy < ~/.codex/auth.json` copies it.
+3. In the browser, open Settings → AI accounts, then open that Codex account.
+4. Paste the file into "Replacement auth.json contents", then press Replace credential.
+
+Then you run `node scripts/where-am-i.mjs` again and read back the `coding accounts` part.
+
+Say these two things plainly:
+
+- Do not enroll a second account. Replace the credential on the one the script named.
+- Catalyst takes over this login. Its refresh token is single-use, so the copy on this machine stops working once Catalyst uses it. To use Codex locally, sign in to Codex again, separately, after the replacement.
+
+## Claude
+
+The same page takes a Claude account's new credential. Its field is "Replacement setup token". The person runs `claude setup-token` in their terminal, pastes the token it prints into that field, and presses Replace credential. Then re-run the script.
+
+## Any other provider
+
+Replace its credential on the same page, with the credential that page asks for.
+
+## What Replace credential does
+
+It stores the new credential and clears the account's quarantine in the same step. A tenant owner or admin can do it. An operator is not needed.
+
+A failed poll is recorded until the account is polled again. If the script still names the account right after the replacement, wait for the next poll and read it again. If it still names it, report both: what the page said, and what the script says.

package/skills/catalyst-onboard/references/the-one-path.md

@@ -1,12 +1,11 @@
 # The one path
 
-Eleven steps, in this order. The order is the product's own: the tenant-side steps run Linear, then the project, then GitHub, then the repository, because each one is the cheapest place to catch the failure the next one would otherwise hide. Connect the tenant's Linear workspace before starting personal Linear consent (3a). Install the tenant's GitHub App and register its repository before starting personal GitHub consent (6a).
+The steps run in this order. The order is the product's own: the tenant-side steps run Linear, then the project, then GitHub, then the repository, because each one is the cheapest place to catch the failure the next one would otherwise hide. Connect the tenant's Linear workspace before starting personal Linear consent (3a). Install the tenant's GitHub App and register its repository before starting personal GitHub consent (6a).
 
 Walk them **one at a time**. Before each step say what you are about to do and why; after it, show what actually came back. `node scripts/where-am-i.mjs --next` decides which step you are on — never your memory of the last turn.
 
 Each step below states: what it is for, what you run or hand over, **what you read back to prove it landed**, and **who owns it**.
 
-
 ## 0 — Where are we
 
 **For:** starting from the truth instead of from an assumption. A person arrives here having done anything from nothing to most of it.
@@ -71,17 +70,19 @@ If it refuses, stop here and use the `connect-me` skill; it owns every failure m
 
 ⭐ **One project at a time is safe, and lead with this.** Mapping one project changes no other project's stages and moves no other project's tickets. Encourage a pilot: pick the project they care least about breaking.
 
-
 ## 5 — Install the GitHub App
 
 **For:** the account grain again. Without it Catalyst can read tickets but cannot touch code.
 
-**You hand over:** `<their cloud>/settings/connections`, and say: install the GitHub App, and grant it the repository they want worked.
+**You hand over:** `<their cloud>/settings/connections`, and say: install the GitHub App, and grant it the repository they want worked and `<org>/thoughts` (step 5a).
 
 **Read back:** it is confirmed by step 6 succeeding — a repository cannot be registered through an app that is not installed. Say that is what you are waiting for rather than claiming you verified it here.
 
 **Owner:** a tenant owner or admin, in a browser. **Browser by construction**, same reason as step 3.
 
+## 5a — The thoughts repository
+
+**For:** Catalyst's cloud phases write their notes to `<org>/thoughts`, where `<org>` is the GitHub org that owns the code repository. If the App cannot reach it, phases run without those notes and nothing says so. **You hand over:** GitHub. Confirm `<org>/thoughts` exists; if not, create a private repository named `thoughts`, initialized with a README. Then, on the GitHub App's installation page for that org, choose All repositories, or add `thoughts` to the selected repositories. **Read back:** once a repository is registered, the script's `repositories` part carries a note from `gh repo view <org>/thoughts`. It shows the repository exists, never that the App can reach it. Say that plainly; never claim App access is verified. **Owner:** an org admin on GitHub, in a browser.
 
 ## 6 — Register the repository
 
@@ -93,7 +94,6 @@ If it refuses, stop here and use the `connect-me` skill; it owns every failure m
 
 **Owner:** a tenant owner or admin. ⛔ **Registering is settings-page work today**; a key-callable path is being built. ⛔ A repository registered without a project attached is the trap here: the call succeeds, the repository is listed, and nothing can ever dispatch into it. Make sure they attach the project in the same form, and say why.
 
-
 ## 6a — Connect your personal GitHub account
 
 **For:** letting Catalyst act as you in GitHub. This grant is separate from the tenant's GitHub App installation. **You run:** `catalyst-skills connections personal github start`, only after the GitHub App is installed and the repository is registered. The browser flow is the same as 3a. **Read back:** `catalyst-skills connections personal github status`; a connected result confirms the personal grant. **Owner:** you start and check; the member approves in a browser.
@@ -118,16 +118,15 @@ Add `--approve` to approve exactly the revision that propose just returned, whic
 
 **Owner:** you can read it from any active seat; proposing and approving need an admin or owner seat, and the cloud refuses with that sentence if the person does not have one — read the refusal to them rather than retrying.
 
-⛔ **Values never pass through you.** The declaration carries the *names* a build needs. The values are entered by the person, once, in the app, and nothing you run ever sees them. Say that plainly; a person asked for a secret by an agent is right to be suspicious. The names one repository needs go in its own committed `catalyst.env.json`. See `references/declaring-a-repository.md`.
+⛔ **Values never pass through you.** The declaration carries the *names* a build needs. The values are entered by the person, once, in the app, and nothing you run ever sees them. Say that plainly; a person asked for a secret by an agent is right to be suspicious. The names one repository needs go in its own committed `.catalyst/catalyst.toml`. See `references/declaring-a-repository.md`.
 
 If they do not know what their build needs yet, skip this step. It blocks nothing until a phase needs a secret.
 
-
 ## 8 — A coding account, and a host
 
 **For:** what a phase runs on. Without an enrolled coding account and a passing host check, every step above can be done and nothing starts.
 
-**You run:** it is already in the script, as the `coding accounts` and `host` parts. What each reading means, who owns it, and what to hand over are in `references/what-a-phase-needs.md`. The contract names who enrols the account and who owns the host.
+**You run:** it is already in the script, as the `coding accounts` and `host` parts. What each reading means, who owns it, and what to hand over are in `references/what-a-phase-needs.md`. The contract names who enrols the account and who owns the host. If the script says an account needs a new credential, the steps are in `references/replacing-a-credential.md`.
 
 ---
 
@@ -143,7 +142,6 @@ If they do not know what their build needs yet, skip this step. It blocks nothin
 
 **Owner:** the card move is theirs. The verdict is the tenant's.
 
-
 ## When you are done
 
 Say what is set up, name anything still unfinished with its owner, and never say work can run while the `coding accounts` or `host` part is unfinished, and tell them the standing question "am I set up?" now belongs to the `catalyst-setup` skill, and "what's happening?" to `whats-happening`. You do not need to be invoked again.

package/skills/catalyst-onboard/references/what-a-phase-needs.md

@@ -6,13 +6,13 @@ A person can finish every other step and still see nothing run. A phase needs tw
 
 **For:** a phase runs on one of the tenant's own enrolled coding accounts. With none active, no phase can start.
 
-**Instrument:** `codingAccounts` in `catalyst-skills contract`. It carries a `state`, a printable `line`, who enrolls an account (`enrolledByLine`) and the `page`. The script prints all of them. It never shows a credential or an email.
+**Instrument:** `codingAccounts` in `catalyst-skills contract`. It carries a `state`, a printable `line`, who enrolls an account (`enrolledByLine`) and the `page`. The script prints all of them. It never shows a credential or an email. When the state is `enrolled`, the script also reads `catalyst-skills accounts` to check each account's credential.
 
 **What each state means:**
 
 | state | what it says | what to do |
 | -- | -- | -- |
-| `enrolled` | at least one account is active | nothing |
+| `enrolled` | at least one account is active. Another account can still have a dead credential | read the account lines. If one says "<provider> account <slot> needs a new credential", that is the next step: follow `references/replacing-a-credential.md`. If the part reads `unreadable`, the accounts could not be checked in detail; say so and read it again later. Otherwise nothing |
 | `none_enrolled` | no account is enrolled | hand over the page; the enroller the contract names enrols one |
 | `inactive` | accounts exist, but every one is out of rotation | reactivate one on the page. Never tell them to enrol another |
 | `unread` | the cloud could not read the accounts | say it could not be read. It is not "no accounts". Do not tell them to enrol one; read it again later |

package/skills/catalyst-onboard/references/what-the-browser-owns.md

@@ -10,7 +10,8 @@ These will never be a command, on any release. Each is an authorization a person
 | -- | -- | -- |
 | approving the login | the URL and short code that `catalyst-skills login` printed | "I have started the login. It printed this code and this URL — approve it in your browser, or on your phone, and tell me when it is done." |
 | connecting Linear | `<their cloud>/settings/connections` | "Open this page and connect Linear. It will send you to Linear to authorize it and bring you back." |
-| installing the GitHub App | `<their cloud>/settings/connections` | "Open the same page and install the GitHub App, granting it the repository you want worked." |
+| installing the GitHub App | `<their cloud>/settings/connections` | "Open the same page and install the GitHub App, granting it the repository you want worked and `<your GitHub org>/thoughts`." |
+| creating or confirming `<your GitHub org>/thoughts`, and letting the GitHub App reach it | GitHub, then the GitHub App's installation page for that org | "Catalyst's cloud phases write their notes to `<your GitHub org>/thoughts`, in the org that owns the code repository. Check it exists. If not, create a private repository named `thoughts`, initialized with a README. Then, on the GitHub App's installation page for that org, choose All repositories, or add `thoughts` to the selected repositories." |
 | connecting personal Linear | the URL printed by `catalyst-skills connections personal linear start` | "Approve your own Linear account in this browser. I will check the grant status afterward." |
 | connecting personal GitHub, after the tenant GitHub App is installed and its repository is registered | the URL printed by `catalyst-skills connections personal github start` | "Approve your own GitHub account in this browser. I will check the grant status afterward." |
 
@@ -26,7 +27,7 @@ These are settings pages today because the routes behind them take a browser ses
 | checking a project's readiness, or re-checking it | the same page | "I can read the verdict your tenant last stored, from the contract. Asking for a fresh check is on that page." |
 | mapping stages, or adopting the workflow | the same page, per project | "Pick one project, then **Map my stages** — or **Adopt the Catalyst workflow** if you want Catalyst's stages created for you." |
 | registering a repository | `<their cloud>/settings/repositories` | "Add the repository here, and attach it to the project you just mapped, in the same form." |
-| approving the environment **for one repository**, and entering its values | that repository's environment section under `<their cloud>/settings/repositories` | "The names come from `catalyst.env.json` in the repository, which I can write with you. Approving it and entering the values happen here, once, by you. Nothing I run ever sees a value." (Account-wide names are **not** on this list: `catalyst-skills environment` does those.) |
+| approving the environment **for one repository**, and entering its values | that repository's Environment page under `<their cloud>/settings/repositories`: the Setup declaration tab's Approve this revision button approves, and the Environment variables and Secrets tabs take the values | "The names come from `.catalyst/catalyst.toml` in the repository, which I can write with you. Approving it and entering the values happen here, once, by you. Nothing I run ever sees a value." (Account-wide names are **not** on this list: `catalyst-skills environment` does those.) |
 
 ⛔ **Do not compose a request for any of these.** A skill script never makes a request of its own; only the CLI does, and the CLI has no verb for them. If you find yourself constructing a URL, stop.
 

package/skills/catalyst-onboard/scripts/where-am-i.mjs

@@ -6,6 +6,7 @@
 //
 // Every count and every name below is read off what a verb printed. Nothing here is written down.
 import { cliTarget, CONNECT_LINE, parseFlags, printHelp, runCli, tryJson, tryLoadConfig } from "./lib/cli.mjs";
+import { spawnSync } from "node:child_process";
 import { runLocalSync } from "./local-sync.mjs";
 
 const SPEC = {
@@ -16,8 +17,9 @@ const NOTES = [
   "Reads, in this order: `status` (machine), `ready --json` (machine checks and project checks, kept apart),",
   "`replica status --probe --json` and `events status --probe --json` (optional local freshness),",
   "`me --json` and personal connection statuses (person), `contract --path …` for the account, the projects and the repositories,",
-  "`contract --path codingAccounts` (coding accounts; `accounts --json` on an older cloud), and each",
+  "`contract --path codingAccounts` and `accounts --json` (coding accounts, and which one needs a new credential), and each",
   "project's hosts_current check with its fixedWhere (host).",
+  "Also runs `gh repo view <owner>/thoughts` for each registered repository's owner, as a note: it shows the repository exists, never that the GitHub App can reach it.",
   "Writes nothing and changes nothing. Runs before this machine is connected — that is one of the states it reports.",
 ];
 
@@ -246,6 +248,17 @@ if (!connected) {
 }
 
 // ── repositories ──────────────────────────────────────────────────────────────────────────────────
+// Cloud phases write their notes to <owner>/thoughts, where <owner> owns the code repository. The
+// person's own `gh` can say whether that repository exists. It cannot say whether the GitHub App can
+// reach it, so this note never claims that, and it never changes a verdict.
+function thoughtsNote(owner) {
+  const repo = `${owner}/thoughts`;
+  const res = spawnSync("gh", ["repo", "view", repo, "--json", "name"], { encoding: "utf8", timeout: 15_000, env: { ...process.env, GH_PROMPT_DISABLED: "1" } });
+  if (res.error) return `note ${repo}: not checked (the gh command could not run here). Confirm it exists on GitHub (step 5a).`;
+  if (res.status === 0) return `note ${repo}: exists; App access not verifiable from here. Confirm the GitHub App installation includes it (step 5a).`;
+  const why = (res.stderr || res.stdout).trim().split("\n")[0] || `gh exited ${res.status}`;
+  return `note ${repo}: gh could not see it (${why}). It does not exist, or this GitHub login cannot see it. Create or confirm it (step 5a).`;
+}
 if (!connected) {
   add("repositories", "catalyst-skills contract --path merge.repositories", "unreadable", ["not readable until this machine is connected"], null, null);
 } else {
@@ -258,6 +271,7 @@ if (!connected) {
     const lines = [`${rows.length} registered`, ...rows.map((r) => `${r.owner ?? "?"}/${r.name ?? "?"}`)];
     repositoryRegistered = rows.length > 0;
     lines.push("⛔ REGISTRATION only. This carries no status and no project attachment, so it never proves a repository can be dispatched into.");
+    for (const owner of [...new Set(rows.map((r) => r.owner).filter((o) => typeof o === "string" && o !== ""))]) lines.push(thoughtsNote(owner));
     add("repositories", "catalyst-skills contract --path merge.repositories", rows.length > 0 ? "ok" : "unfinished", lines, "a tenant owner or admin", link("/settings/repositories"));
   }
 }
@@ -266,8 +280,28 @@ if (!connected) {
 // A phase runs on one of the tenant's enrolled coding accounts. With none, every step above can be
 // finished and nothing will ever start, so this part blocks the "ready" line like any other.
 // The contract says the state, its sentence, who enrolls one and on which page. An older cloud's
-// contract has no `codingAccounts`, and only then is the account list read and the owner assumed.
+// contract has no `codingAccounts`, and only then is the owner assumed.
 let accountsNext = "enrol a coding account a phase can run on";
+// The contract counts accounts by declared rotation, so one healthy account can hide another whose
+// credential is dead. When it says `enrolled`, each account is read as well. An account needs a new
+// credential when it is quarantined, expired or revoked, or when its last polls failed on the
+// credential itself. The poll fields are read only when the cloud sends them.
+const CREDENTIAL_ERROR_CODES = new Set(["no_access_token", "no_credential", "http_401", "http_403", "usage_unauthorized", "usage_forbidden"]);
+const CREDENTIAL_FAILURE_STREAK = 3;
+const credentialProblem = (a) => {
+  if (a?.quarantined === true) return `quarantined${typeof a.quarantineReason === "string" && a.quarantineReason !== "" ? `: ${a.quarantineReason}` : ""}`;
+  if (a?.status === "expired-or-revoked") return "expired or revoked";
+  if (CREDENTIAL_ERROR_CODES.has(a?.lastPollErrorCode) && typeof a?.pollFailureCount === "number" && a.pollFailureCount >= CREDENTIAL_FAILURE_STREAK) {
+    return `its last ${a.pollFailureCount} polls failed with ${a.lastPollErrorCode}`;
+  }
+  return null;
+};
+const readAccountRows = () => {
+  const acc = runCli(["accounts", "--json"]);
+  const doc = tryJson(acc.stdout);
+  const rows = Array.isArray(doc) ? doc : Array.isArray(doc?.accounts) ? doc.accounts : null;
+  return { rows, error: rows === null ? (acc.stderr || acc.stdout).trim().split("\n")[0] || "no output" : null };
+};
 if (!connected) {
   add("coding accounts", "codingAccounts in catalyst-skills contract", "unreadable", ["not readable until this machine is connected"], null, null);
 } else {
@@ -279,8 +313,32 @@ if (!connected) {
     const line = typeof ca.line === "string" ? ca.line : `state ${ca.state}`;
     const owner = typeof ca.enrolledByLine === "string" ? ca.enrolledByLine : null;
     const where = typeof ca.page === "string" ? link(ca.page) : null;
-    if (ca.state === "enrolled") {
-      add("coding accounts", INSTRUMENT, "ok", [line, `${ca.activeCount ?? "?"} active`]);
+    if (ca.state === "enrolled" || ca.state === "needs_credential") {
+      const DETAIL = `${INSTRUMENT}, and catalyst-skills accounts`;
+      const head = [line, `${ca.activeCount ?? "?"} active`];
+      const { rows, error } = readAccountRows();
+      const dead = rows === null ? [] : rows.filter((a) => credentialProblem(a) !== null);
+      if (rows === null) {
+        accountsNext = "read the coding accounts again; each account's credential could not be checked";
+        add("coding accounts", DETAIL, "unreadable", [...head, `coding accounts could not be checked in detail (${error}). Whether each one still has a working credential is unknown. Do not enroll one on this reading.`], null, null);
+      } else if (dead.length > 0) {
+        const name = (a) => `${a.provider ?? "unknown provider"} account ${a.accountSlot ?? "?"}`;
+        const more = dead.length > 1 ? ` (and ${dead.length - 1} more)` : "";
+        accountsNext = `${name(dead[0])} needs a new credential${more}. Replace it on the AI accounts page (Settings → AI accounts → the account → Replace credential). Do not enroll another account.`;
+        add(
+          "coding accounts",
+          DETAIL,
+          "unfinished",
+          [...head, ...dead.map((a) => `${name(a)} needs a new credential: ${credentialProblem(a)}`), "Replace its credential on its own page. Do not enroll another account. The steps are in references/replacing-a-credential.md."],
+          owner,
+          where,
+        );
+      } else if (ca.state === "needs_credential") {
+        accountsNext = "replace the credential of the coding account the page marks; do not enroll another account";
+        add("coding accounts", DETAIL, "unfinished", [...head, "The contract says an account needs a new credential, and the account list does not say which. Open the page and look for it."], owner, where);
+      } else {
+        add("coding accounts", DETAIL, "ok", [...head, `${rows.length} checked, none needs a new credential`]);
+      }
     } else if (ca.state === "inactive") {
       accountsNext = "reactivate a coding account that is out of rotation; do not enroll another one";
       add("coding accounts", INSTRUMENT, "unfinished", [line, "Every account is out of rotation. Reactivate one. Do not enroll another account."], owner, where);
@@ -292,12 +350,10 @@ if (!connected) {
       add("coding accounts", INSTRUMENT, "unreadable", [line, "This is not a missing account. Do not enroll one on this reading. Run this again later."], null, null);
     }
   } else if (older) {
-    const acc = runCli(["accounts", "--json"]);
-    const doc = tryJson(acc.stdout);
-    const rows = Array.isArray(doc) ? doc : Array.isArray(doc?.accounts) ? doc.accounts : null;
+    const { rows, error } = readAccountRows();
     const olderLine = "this cloud is older than the bundle: its contract does not say whether a coding account is enrolled, so the account list is read instead";
     if (rows === null) {
-      add("coding accounts", "catalyst-skills accounts", "unreadable", [olderLine, `coding accounts could not be read (${(acc.stderr || acc.stdout).trim().split("\n")[0] || "no output"})`], null, null);
+      add("coding accounts", "catalyst-skills accounts", "unreadable", [olderLine, `coding accounts could not be read (${error})`], null, null);
     } else {
       // An expired or revoked slot, or a quarantined one, cannot take work until an admin acts on it.
       const usable = rows.filter((a) => a?.status !== "expired-or-revoked" && a?.quarantined !== true);

package/skills/catalyst-setup/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Am I set up? Machine readiness (Node, the tenant connection, the cached contract, the CLI path, the skills, the SDK, the optional replica) plus tenant readiness from the contract's per-team checks, in one verdict: what passes, what is blocked, what is merely waiting, and who can click what. Use when someone asks "am I set up", "what is missing", "why does nothing happen", "is the replica running", or right after connecting a new machine. Reports; never repairs.
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.2 — written in this repository for customer tenants -->
 
 # Am I set up?
 

package/skills/catalyst-setup/references/what-each-check-means.md

@@ -22,7 +22,7 @@ The contract's `readinessChecks[]` is the list of record. A check that appears t
 | `writes_land` | Catalyst has written to this team successfully | "no write observed" is waiting, not failing: it clears the first time Catalyst moves a ticket. "Write refused" means Linear rejected the last write: check the connection and the team's permissions | owner or admin when refused; otherwise nobody |
 | `webhook_covers_team` | events for this team are arriving | confirmed once a repository is registered and events flow; "no delivery observed" is waiting | owner or admin, by registering the repository |
 | `hosts_current` | no connected host runs an older mapping revision | a host that is behind re-loads the mapping on its next connect; a host that did not report its revision is flagged rather than assumed current; "no host connected" is waiting | whoever runs that host |
-| `environment_declared` | a committed environment declaration for the team's default repository is in effect (`catalyst.env.json` at the repository root was ingested, is valid, and its latest proposal is approved) | `no_team_repo_default`: register a repository and make it the team's default; `no_environment_declaration`: commit the declaration file to that repository; `declaration_invalid` / `declaration_read_failed`: fix the file (the ingest names the error); `declaration_awaiting_approval`: an owner or admin approves the proposal in Settings → Environment | owner or admin, except committing the file, which is whoever can push to the repository |
+| `environment_declared` | a committed environment declaration for the team's default repository is in effect (`.catalyst/catalyst.toml` on the default branch was ingested, is valid, and its latest proposal is approved) | `no_team_repo_default`: register a repository and make it the team's default; `no_environment_declaration`: commit `.catalyst/catalyst.toml` with its `[environment]` names to that repository's default branch; `declaration_invalid` / `declaration_read_failed`: fix the file (the ingest names the error); `declaration_awaiting_approval`: an owner or admin opens Settings → Repositories → the repository → Environment → Setup declaration and clicks Approve this revision | owner or admin, except committing the file, which is whoever can push to the repository |
 | `tools_resolvable` | every MCP server and CLI the team's approved environment declaration names can be resolved for that team's repository | `tool_reference_unresolved`: the declaration names a vault secret that does not exist — add it at the right scope or correct the declaration; `toolchain_cli_missing`: a declared CLI is not in the runner image, which is not self-service; `tool_declarations_unread` reads as `unknown` and clears itself | owner or admin, in the declaration or Settings → Environment |
 | `reviewer_required` | this team's repository can merge under its own merge policy with the reviewers configured | it fails only under a strict merge policy with no reviewer — configure one at Settings → Repositories → Code reviews, or change the repository's merge policy; work still runs, only the merge waits | owner or admin, in settings |
 | `reviewer_configured` | a code reviewer is configured for this team's repository at all, whatever the current policy requires | a *failing* `reviewer_configured` never blocks or degrades a team — with no reviewer, pull requests merge on green checks and resolved threads alone; configure one at Settings → Repositories → Code reviews. An `unknown` one (`merge_reviewer_unread`: the reviewer registry could not be read) still degrades the team, like any unknown | owner or admin, in settings; nobody is required when it fails |

package/skills/connect-me/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.2 — written in this repository for customer tenants -->
 
 # Connect me
 

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

@@ -4,7 +4,7 @@ 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@0.9.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.2 — written in this repository for customer tenants -->
 
 # How Catalyst works
 

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

@@ -24,7 +24,7 @@ The harness is a property of the catalog entry, never a routing input. Which pro
 - **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).
+Two more lifecycle facts sit beside them: **quarantined** (system-set, on a credential conflict or an authentication mismatch; Replace credential on the account's page clears it, and a tenant owner or admin can do that, so an operator is not required) and **revoked** (operator-set).
 
 ## Windows, walls, headroom
 

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

@@ -30,7 +30,7 @@ The contract's `teams[].workflowMode` reports which one a team is in:
 
 `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.
 
-Stage mappings live in the app, at Settings → Linear teams. The cloud does not read `.catalyst/catalyst.toml` yet, so a mapping written there changes nothing today. An older `.catalyst/config.json` is not imported.
+Stage mappings live in the app, at Settings → Linear teams. The cloud reads each repository's `.catalyst/catalyst.toml`, but that file has no stage-mapping section, so a mapping written there changes nothing. An older `.catalyst/config.json` is not imported.
 
 ## The state id is the authority; names are display
 

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

@@ -5,7 +5,7 @@ description: >-
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.2 — written in this repository for customer tenants -->
 
 # Run this project
 

package/skills/unstick/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.2 — written in this repository for customer tenants -->
 
 # Unstick
 

package/skills/what-needs-me/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.2 — written in this repository for customer tenants -->
 
 # What needs me
 

package/skills/whats-happening/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   The desk for a Catalyst Cloud tenant. Use when the person asks "what's happening?", "where are we?", "why is that stuck?", "what closed?", "what's next?", or asks for something to be done rather than known. Reads the tenant contract, what is running and queued, the eligibility explainer and the open asks through the catalyst-skills CLI, and answers in one reply with ticket ids. Routes work to a project owner and decisions to what-needs-me. Never composes a URL, never polls, never answers as the human.
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.2 — written in this repository for customer tenants -->
 
 # What's happening