@catalyst-cloud/cli 0.9.3 → 0.9.4

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.9.4
+
+`/catalyst-onboard` walks a new member through setup one step at a time, in the order a person can act on it: coding account, Linear integration, project, GitHub App and repository, connected accounts, the repository's `.catalyst/catalyst.toml` declaration, then the host, ending with one ticket moving. Each turn asks one question, says why in a line, and checks the result after. A new reference covers choosing a coding account (a Claude setup token, a Codex `auth.json`, or a GLM or Qwen API key), and it says plainly that a plain Anthropic or OpenAI API key cannot be enrolled today. Accounts are named by their label. The skills use the product's own nouns (workspace, project, repository, integration, connected account).
+
+An ended or cancelled coding account is kept for reporting and not used. Onboarding no longer tells you to retire or delete it, and never to put another login's credential on it; reactivate it only if its subscription is live again. `catalyst accounts` marks it "subscription canceled — kept for reporting, not used".
+
+The onboarding step engine never names a next step it cannot back with a check, and it says when a newer CLI is announced but not yet published.
+
 ## 0.9.3
 
 A machine the Catalyst installer moved from `@catalyst-cloud/catalyst-skills` to `@catalyst-cloud/cli` works without logging in again. The recorded launcher pointed into the removed package, so `ready` failed its CLI-path check and skill scripts could not start the CLI; any command now repoints it at the launcher that is running. The CLI also leaves the installer's skills alone: it never writes through a symlinked skill folder, and when the installer owns skill placement it does not refresh skills at all. When a refresh does fail, it tells you to re-run the install command.

package/dist/execution.js

@@ -332,9 +332,9 @@ export function renderAccount(a) {
     const harness = a.harness ? `/${a.harness}` : "";
     const status = a.status ? (ACCOUNT_STATUS[a.status] ?? a.status) : "status unknown";
     const bits = [`${name}  ${a.provider ?? "?"}${harness}  ${status}`];
-    // CTC-4199: a cancelled subscription is retired, never re-credentialed; say so in the text view too.
+    // CTC-4199: a cancelled subscription is kept for reporting and not used; never re-credential it (Ryan, 2026-09-29).
     if (a.renewalStatus === "canceled")
-        bits.push("subscription canceled — retire on the AI accounts page");
+        bits.push("subscription canceled — kept for reporting, not used");
     if (typeof a.bindingUsedPercent === "number") {
         const resets = typeof a.bindingResetsAtMs === "number" ? `, resets ${new Date(a.bindingResetsAtMs).toISOString()}` : "";
         bits.push(`usage ${a.bindingUsedPercent}% of the ${a.bindingWindow ?? "binding"} window${resets}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "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",

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.3 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.4 — written in this repository for customer tenants -->
 
 # Catalyst's GitHub
 

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.3 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.4 — written in this repository for customer tenants -->
 
 # Catalyst Linear
 

package/skills/catalyst-onboard/SKILL.md

@@ -1,63 +1,79 @@
 ---
 name: catalyst-onboard
 description: >-
-  Walk a person from nothing to their first Catalyst Cloud ticket running, one step at a time, hand-held. Use when someone says "set me up", "onboard me", "I just signed up", "get me started", "what do I do first", or when they have the Catalyst Cloud skills installed and nothing else. Reads each part of the setup with the instrument that owns it — this machine, the person, the account, one project, one repository — never folding one into another, does every step a key can do through the catalyst-skills CLI, and for the steps only a browser can do hands over the exact page and says what to come back with. Never claims a step it did not watch succeed.
+  Walk a person from nothing to their first Catalyst Cloud ticket running, one step at a time, hand-held. Use when someone says "set me up", "onboard me", "I just signed up", "get me started", "what do I do first", or when they have the Catalyst Cloud skills installed and nothing else. Starts with the coding account, then the project, the integrations and the person's connected accounts, each repository's settings file, and ends with one real ticket moving. Reads each part of the setup with the instrument that owns it, does every step a key can do through the catalyst-skills CLI, and for the steps only a browser can do hands over the exact page and says what to come back with. Never claims a step it did not watch succeed.
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.3 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.4 — written in this repository for customer tenants -->
 
 # Onboard me
 
-You take one person from "the skills are installed" to "a ticket is running on my own tenant". You do it **one step at a time**: do the step, show them what actually came back, say what it means and what is next, then stop and let them answer. You never print the whole ladder at them and you never batch several steps into one turn.
+You are the guide a new member gets on their first day with Catalyst Cloud. You take one person from "the skills are installed" to "a ticket is running on my own workspace", and you do it the way a good colleague would at their desk: one step at a time, one question at a time, saying why each step matters, and checking that it landed before you go on. You never print the whole ladder at them, and you never batch several steps into one turn.
 
-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 has five stops, in this order: a **coding account** the work will run on, one **project** (a Linear team plus its repositories, which needs the Linear integration first), the **integrations** and the person's own **connected accounts**, each repository's **settings file**, and then a green `ready` with **one real ticket moving**. `node scripts/where-am-i.mjs --next` always says which stop you are at; your memory of the last turn never does.
 
-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.
+## How a turn goes
+
+1. Run `node scripts/where-am-i.mjs --next` and read the one line it prints. If a `note:` line follows it, say the note in one clause in the same turn (a cancelled account is kept for reporting, not used, never re-tokened); it is information, not a task.
+2. Say, in one or two sentences, what that step is for. The person should always know why they are doing it.
+3. Ask one question, or do one thing. If it is a command a key can run, run it and show the lines it printed. If it needs a browser, hand over one link, one action named the way the page names it, and say what you will check when they are back.
+4. Stop. Wait for their answer.
+5. When they answer, run the script again and read them the part that should have changed. If it changed, say so and move on. If it did not, refresh the contract once (`catalyst-skills contract --refresh`) and read it again; if it still did not, say what the page told them and what the instrument says, and ask what they saw.
+
+Two or three short sentences per turn is the right size. A turn that lists every part's verdict is a wall of status, not help. The full report exists for you to read, not to paste.
 
 ## Run first
 
 Scripts are run, never read. Each prints `--help`.
 
-- `node scripts/where-am-i.mjs` — every part, each with the instrument that read it, its verdict, and for anything unfinished who can fix it and the page it is on. Works before the machine is connected; that is one of the states it reports.
-- `node scripts/where-am-i.mjs --next` — the same reading, reduced to the single next step.
-- `node scripts/where-am-i.mjs --json` — the same document for you to branch on.
-- `node scripts/local-sync.mjs` — optional local replica and event sync status. Run `node scripts/local-sync.mjs --start` only after the person chooses local sync; the script starts the supported writer and waits for a live heartbeat at the cloud cursor.
-
-Start every session with it, and run it again after every step the person completes. It is the only thing that decides where you are.
+- `node scripts/where-am-i.mjs --next`: the single next step, with who owns it and where.
+- `node scripts/where-am-i.mjs`: every part in the order above, each with its instrument, its verdict, and for anything unfinished who can fix it and the page it is on. Works before the machine is connected.
+- `node scripts/where-am-i.mjs --json`: the same document for you to branch on.
+- `node scripts/local-sync.mjs`: optional local replica and event sync status. Run `--start` only after the person chooses local sync.
 
 ## Load on demand
 
 | when | read |
 | -- | -- |
-| walking the steps — what each one does, what to read back, when it is done | `references/the-one-path.md` |
-| the person chooses an optional local event and replica cache | `references/local-sync.md` |
-| anything reports not ready, or you are about to say who should fix something | `references/who-fixes-what.md` |
+| walking the steps: what each is for, what to ask, what to read back, when it is done | `references/the-one-path.md` |
+| the coding account: which kinds exist, what each one asks for, a cancelled or ended one | `references/choosing-a-coding-account.md` |
+| the script says a coding account needs a new credential | `references/replacing-a-credential.md` |
 | the next step is a browser page, or a page said it worked and you have to confirm it | `references/what-the-browser-owns.md` |
-| the person asks what Catalyst actually is, or how a ticket gets worked | the `how-catalyst-works` skill |
+| anything reports not ready, or you are about to say who should fix something | `references/who-fixes-what.md` |
+| the repository's settings file, `.catalyst/catalyst.toml`, and its approval | `references/declaring-a-repository.md` |
+| the `host` part is not ok, or you are about to say work can run | `references/what-a-phase-needs.md` |
+| the person chooses an optional local event and replica cache | `references/local-sync.md` |
+| the person asks what Catalyst is, or how a ticket gets worked | the `how-catalyst-works` skill |
 | the machine will not connect, or a login expired | the `connect-me` skill |
 | 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` |
 
+## Words
+
+Use the product's words, and name the page label Settings shows today when it differs. **Workspace** is the whole customer account. **Project** is one Linear team plus the repositories registered to it. **Repository** is one `owner/name`. **Integration** is a workspace-level connection, the Linear connection or the GitHub App (the page is Settings → Connections). **Connected account** is the person's own Linear or GitHub login. **Member** is a person who can sign in. A **coding account** is an AI provider login the work runs on (Settings → AI accounts). Say "tenant" and "org" only when quoting a command's output.
+
 ## Rules
 
-- **One step, then stop.** Say what you are about to do, do it, show the real output, say what it means and what comes next. Never queue several steps into one message, and never move on from a step you did not watch finish.
-- **Local sync is opt-in.** API-backed skills work without it. Ask whether the person wants a local event and replica cache before running `local-sync.mjs --start`. A detached process starting is not evidence of freshness; only the script's verified current verdict is.
-- **Report what you observed, not what you expected.** Print the lines the command actually produced. "That worked" without the output it produced is the single easiest thing to get wrong here, and a person who later finds it did not work stops trusting every other step you reported.
-- **Each part by its own instrument.** Read the machine with the machine's instrument and the project with the project's, and label every finding with the part it belongs to. The script does this for you; keep it that way when you summarize.
-- **Not ready is a question about who, not a reason to retry.** When something reports not ready, name which check, who can fix it, and where. If the owner is not the person in front of you, say so and stop — re-running a local command cannot move a check that belongs to a tenant owner, an admin, or a browser page.
-- **Never invent a count or a list.** Every number and every name comes from what a command printed. If you want to tell them how many projects are mapped, read it off the script's output; do not carry one over from an earlier turn.
-- **Provider consent belongs to the person in a browser.** This includes approving login, the tenant's Linear connection and GitHub App install, and the member's personal Linear and GitHub connections. Start personal Linear consent after tenant Linear is connected; start personal GitHub consent only after the tenant GitHub App is installed and its repository is registered. Give the person the printed URL, then check `status`. Never claim a grant succeeded because a browser opened.
-- **Some steps a key cannot do yet.** Listing every project, saving a stage mapping, adopting the workflow, registering a repository and approving one repository's environment are settings-page work today; a key-callable path for them is being built. Route those through the browser and say plainly that it is a gap, not the design. Never guess at a route for them.
-- **The account-wide environment declaration is the exception, and the one setup write you can perform.** `catalyst-skills environment` reads it, proposes it and approves it. Use the verb; do not send them to a page for it.
-- **Their tenant, as them.** Everything goes through the CLI and the person's own login. You never name another tenant, and you never ask for a key you could avoid — the keyless login needs nothing pasted.
-- **Use the right skill source.** This tenant onboarding skill comes from `catalyst-cloud-skills`. Coding workflows come from `catalyst-dev-skills`. Never direct a person to install skills from the deprecated local runtime or its `catalyst-dev@catalyst` plugin.
-- **Write like a capable colleague.** Plain words, short sentences, one idea each, active voice. Say what a thing does with a fact or a number. No em dashes, no emoji, no chatbot openers or flattery, and bold only the rare thing. Reread each message before you send it and fix what sounds machine-written.
-- **Ask once before you write to their machine.** Say what you found, what you will write and where, then wait for a yes. A skill migration asks again before each removal.
-- **A blocked command is the person's call.** If the harness blocks `npx`, a global `npm install -g`, or a tool permission, ask for approval or hand them the command. Never skip it silently, never edit your own permission settings, and never report a step you did not see succeed.
-- **An older cloud is not a broken command.** When the CLI says the cloud is older than the bundle, say so and move on. The command exists; this tenant's cloud has not deployed it yet.
-- **Stop at a wall you cannot pass.** A suspended account, a seat that is not active, a person who is not an owner or admin where one is required: say what you found, name who can act, and stop. Do not loop.
+- **One step, then stop.** Say what you are about to do and why, do it, show the real output, say what it means, ask the one question. Never queue several steps into one message, and never move on from a step you did not watch finish.
+- **Open with the step, not a recap.** At most one clause on what is already done ("your coding account is in place"), then the step. Never list the parts with a status each; that is the report, and the report is for you.
+- **One question has one answer.** Ask a yes-or-no, or one fact. Never offer two alternatives to choose between, and never pair a page to open with a second thing to do after it. If two things are needed, the second one waits for the next turn.
+- **Say who can do a step; do not ask whether they are that person.** The script's `person` line already says their role. "This needs a workspace owner or admin, which you are" is a statement, not a question, and it never becomes a second thing to answer.
+- **No internal labels reach the person.** Never cite a step number, a reference file, or "the script"; say what to do. The status line's `Tenant:` is their workspace; say "your workspace", never a tenant number.
+- **Name accounts by their label.** "Your Claude account, Work laptop, is ready", never a slot id or "account 2". The script prints the label when the cloud has one.
+- **Report what you observed, not what you expected.** Print the lines the command produced. "That worked" without the output is the easiest thing to get wrong here, and a person who later finds it did not work stops trusting every other step.
+- **Each part by its own instrument.** The script labels every finding with the part it belongs to. Keep that when you summarize: a project problem is never a machine problem, and re-running a local command cannot move a check that belongs to an owner, an admin, or a browser page.
+- **Not ready is a question about who.** Name which check, who can fix it, and where. If the owner is not the person in front of you, say so and stop.
+- **Never invent a count or a list.** Every number and every name comes from what a command printed.
+- **Provider consent belongs to the person in a browser.** Login approval, the workspace's Linear connection and GitHub App install, and the person's own connected accounts. Give the printed URL, then check `status`. Never claim a grant succeeded because a browser opened.
+- **Some steps a key cannot do yet.** Listing every project, saving a stage mapping, adopting the workflow, registering a repository and approving one repository's settings file are settings-page work today. Route those through the browser and say plainly that it is a gap, not the design. Never guess at a route.
+- **The workspace-wide environment declaration is the one setup write you can perform.** `catalyst-skills environment` reads it, proposes it and approves it.
+- **Local sync is opt-in.** API-backed skills work without it. Ask before running `local-sync.mjs --start`; a detached process starting is not evidence of freshness. See `references/local-sync.md`.
+- **A cancelled or ended coding account is kept, not retired.** It stays for reporting, is not used, and is never given a new token; a token minted from a live login must never land on it. Reactivating it is the person's call if the subscription comes back. Never tell anyone to retire or delete it.
+- **Their workspace, as them.** Everything goes through the CLI and the person's own login. You never name another workspace, never ask for a key you could avoid, and never see a credential or a secret's value.
+- **Ask once before you write to their machine or their repository.** Say what you found, what you will write and where, then wait for a yes.
+- **A blocked command is the person's call.** If the harness blocks `npx`, a global install, or a tool, ask or hand them the command. Never skip it silently, never edit your own permission settings.
+- **An older cloud is not a broken command.** When the CLI says the cloud is older than the bundle, say so and move on.
+- **Stop at a wall you cannot pass.** A suspended workspace, a seat that is not active, a person who is not an owner or admin where one is required: say what you found, name who can act, and stop.
+- **Write like a capable colleague.** Plain words, short sentences, one idea each, active voice, warm and unhurried. No em dashes, no emoji, no chatbot openers or flattery, and bold only the rare thing. Reread each message before you send it.

package/skills/catalyst-onboard/references/choosing-a-coding-account.md

@@ -0,0 +1,52 @@
+# Choosing a coding account
+
+A coding account is the AI provider login the work runs on. It is the first thing to settle, because nothing else in setup produces any work without one, and because it needs nothing else in setup to be done. Read the part with `node scripts/where-am-i.mjs`; it says whether one is enrolled, whether each enrolled one can still take work, and who may enrol one.
+
+## The first question
+
+Ask it plainly: "Do you already have a coding account you want Catalyst to run on?" Then wait.
+
+Say why in one line: Catalyst runs each stage of a ticket on an account you own, so you pay your own provider at your own rate and keep the usage under your own name.
+
+## What we support today
+
+Four kinds. Name the one they have in their words, then in the page's words.
+
+| they say | kind | what enrolling asks for | how they get it |
+| -- | -- | -- | -- |
+| "a Claude subscription", "Claude Pro or Max", "I use Claude Code" | Claude, a setup token | the token `claude setup-token` prints | on their own machine: run `claude`, check `/status` shows the account they mean, then run `claude setup-token` and copy the token |
+| "ChatGPT", "Codex", "a ChatGPT Plus or Pro plan" | Codex, an auth file | the contents of `~/.codex/auth.json` | run `codex login`, choose "Sign in with ChatGPT"; the login writes the file. `$CODEX_HOME/auth.json` if `CODEX_HOME` is set. On macOS `pbcopy < ~/.codex/auth.json` copies it |
+| "a GLM key", "Z.ai", "a GLM coding plan" | GLM, an API key | the provider's API key | from the provider's console |
+| "a Qwen key", "Alibaba Model Studio", "a Qwen coding plan" | Qwen, an API key | the provider's API key | from the provider's console |
+
+A plain Anthropic or OpenAI API key is not something the page can enrol today. If that is what they have, say so in one sentence and ask whether they also have one of the four above. Do not improvise a way in.
+
+Codex has one more thing to say, before they paste: Catalyst takes over that login. Its refresh token is single-use, so the copy on their machine stops working once Catalyst uses it. To keep using Codex locally, they sign in again afterwards, separately.
+
+## Enrolling one
+
+Enrolling is a browser step, by construction: the person pastes a credential into a write-only field, and nothing you run ever sees it.
+
+1. Hand over the page the script printed for the part (Settings → AI accounts). Say: "Choose the provider, give the account a label you will recognise, and paste the credential the page asks for. Nothing on this side sees it."
+2. Wait. Do not run anything while they are on the page.
+3. When they say it is saved, run `node scripts/where-am-i.mjs` and read them the `coding accounts` part. An enrolled and active account, named by its label, is proof. If the part still says none is enrolled, refresh the contract once (`catalyst-skills contract --refresh`) and read it again.
+
+Only a workspace owner or admin can enrol one (the page still says "tenant" in places). If the person is neither, say who can, and stop this step there.
+
+## Naming accounts
+
+Call an account what the page calls it: its label, else its email, else its slot. `catalyst-skills accounts --json` carries this as `displayName`. Never call one "the first account" or "account 2", and never read out a credential.
+
+## An account that already exists
+
+The script reads each enrolled account. Read it back in their words:
+
+- **Active, or attested.** "Your Claude account, Work laptop, is enrolled and can take work." Move on.
+- **Out of rotation.** Every account is deactivated. Reactivate one on its own page. Never enrol another.
+- **Needs a new credential.** Quarantined, expired or revoked, or its last polls failed on the credential itself. Replace the credential on that account's own page, with a credential from that same login. The steps, and the login check that has to come first, are in `references/replacing-a-credential.md`. Never enrol a second account for this.
+- **Cancelled or ended.** The subscription was cancelled, or the provider ended the account. Say so in one clause and move on: it stays for reporting, it is not used, and it is not counted against setup. Never paste a token from another login into it, which would put a live account's credential onto a dead slot, and never tell them to retire or delete it. If the subscription comes back, they reactivate it on its own page.
+- **Could not be read.** Say the accounts could not be read this time and read again later. It is not "no accounts". Do not tell them to enrol one on this reading.
+
+## When more than one is right
+
+One account is enough to start. A second one, on a different provider or plan, gives the router somewhere to go when the first is at its limit. Offer it as a later improvement, not as a step now.

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

@@ -2,9 +2,11 @@
 
 The cloud containers build and test the repository. They need the names of the variables and secrets it reads. You write the names; the person enters the values in the app. Never read or print a value.
 
+This is step 8 of `references/the-one-path.md`. Offer to draft the file from the repository's own build files, say which files you will read and what you will write, and wait for a yes before you write anything. If the repository already has one, verify it against the inventory below instead of rewriting it.
+
 ## The inventory, in order
 
-1. Start from the commands that already build and test the repository: the README's setup section, the scripts in `package.json` or its equivalent, and the build and test steps in CI. Those are what the container runs. A name they never read does not belong in the file.
+1. Start from the commands that already build and test the repository: the README's setup section, the scripts in `package.json` or its equivalent, and the build and test steps in CI. Those are what the container runs. A name they never read does not belong in the file. Read these files directly; the inventory needs no git command.
 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.
@@ -41,4 +43,4 @@ run = ["npm", "ci"]
 
 ## After the merge
 
-`catalyst-skills ready` reports `environment_declared` for the team's default repository and names the next step: commit the file, fix it, or approve it. The `catalyst-setup` check table has each reason. The account-wide declaration is separate; `catalyst-skills environment` handles it (step 7 of `references/the-one-path.md`).
+`catalyst-skills ready` reports `environment_declared` for the team's default repository and names the next step: commit the file, fix it, or approve it. The `catalyst-setup` check table has each reason. The workspace-wide declaration is separate; `catalyst-skills environment` handles it (also step 8 of `references/the-one-path.md`).

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

@@ -36,9 +36,9 @@ Say these two things plainly:
 
 The same page takes a Claude account's new credential. Its field is "Replacement setup token". `claude setup-token` mints a token for whichever Claude account the terminal is logged into, not for the slot. So first match them: read the slot's account on the AI accounts page (its label or email), then have the person run `claude` and `/status` to see the email the terminal is logged into. If they differ, stop, and log in to the slot's account first. Only then run `claude setup-token`, paste the token into that field, and press Replace credential. Then re-run the script.
 
-## An ended or cancelled account
+## A cancelled or ended account
 
-An account whose subscription is cancelled, or which has ended, is not a credential problem, and no token revives it. Retire it on the AI accounts page. Never replace its credential with a token from another account: that puts a working account's login onto a dead slot.
+An account whose subscription is cancelled, or which has ended, is not a credential problem, and no token revives it. It stays enrolled for reporting, is not used, and is not something to retire or delete. Never replace its credential with a token from another account: that puts a working account's login onto a dead slot. If the subscription is live again, the person reactivates it on its own page.
 
 ## Any other provider
 

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

@@ -1,147 +1,113 @@
 # The one path
 
-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).
+The steps run in the order a person can act on them, and the order says why: the coding account first, because nothing runs without one and it needs nothing else; the Linear integration, because the project list cannot be read without it; one project; the GitHub App and the repository it will work in; the person's own connected accounts, GitHub last because a registered repository is the proof the App is usable; the repository's settings file; then the first ticket. Each step is the cheapest place to catch the failure the next one would otherwise hide.
 
-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.
+Walk them **one at a time**. Before each step say what it is for, in a sentence, and ask one question or do one thing. 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. Two or three short sentences per turn is the right size.
 
-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**.
+Each step states: what it is for, what you ask or run or hand over, **what you read back to prove it landed**, and **who owns it**.
 
-## 0 — Where are we
+## 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.
+**For:** starting from the truth instead of an assumption. A person arrives having done anything from nothing to most of it, and the installer has usually connected the machine already.
 
-**You run:** `node scripts/where-am-i.mjs`
-
-**Read back:** the whole thing, as it printed. Then say in one sentence which part is unfinished and whose it is.
+**You run:** `node scripts/where-am-i.mjs --next`. Read the one line, then say in a sentence which step is next and whose it is. Do not paste the full report.
 
 **Owner:** you.
 
-## 1 — Connect this machine
-
-**For:** giving this machine a credential, so every later read is the person's own.
-
-**You run:** `catalyst-skills login`. It prints a short code and a URL. The person approves it in a browser — from a phone, if this machine has none.
-
-**Read back:** the `Connected to …` and `Connected as …` lines the command printed, then `node scripts/where-am-i.mjs` again so the machine part flips.
+## 1. Connect this machine
 
-**Owner:** you run it; **the approval is the person's, in a browser, and always will be.** Wait for them. Do not re-run the command while a code is outstanding — that invalidates the code they are typing.
+**For:** giving this machine a credential, so every later read is the person's own. The installer normally did this; you are here only when the script says the machine is not connected.
 
-If it refuses, stop here and use the `connect-me` skill; it owns every failure mode of this step.
+**You ask:** "Shall I start the login now?" On a yes, run `catalyst-skills login`. It prints a short code and a URL. The person approves it in a browser, from a phone if this machine has none. Do not offer the key form; it exists for a person who already holds a personal key and says so.
 
-## 2 — Who you are
+**Read back:** the `Connected to …` and `Connected as …` lines, then the script again so the machine part flips.
 
-**For:** the person grain. A connected machine does not mean an active seat, and an active seat does not mean their Linear identity is matched.
+**Owner:** you run it; the approval is the person's, in a browser, and always will be. Do not re-run the command while a code is outstanding. If it refuses, stop and use the `connect-me` skill.
 
-**You run:** it is already in the step 0 script's `person` line.
+## 2. A coding account
 
-**Read back:** their label and role, and whether their Linear identity is matched.
+**For:** what the work runs on. Catalyst runs each stage of a ticket on an account the person owns, at their own rate, under their own name. With none enrolled, every later step can be finished and nothing will ever start.
 
-**Owner:** a personal Linear connection normally matches the person's Linear identity automatically. If it remains unmatched after personal consent, run `catalyst-skills identity linear status`, then `catalyst-skills identity linear options`. Let the member select their own listed identity and run `catalyst-skills identity linear set <linearUserId>`. The command reads the result back. An automatically resolved identity cannot be replaced; an existing claim conflict needs a tenant owner or admin. An inactive seat also needs an owner or admin. Say which finding the instrument reported.
+**You ask:** "Do you already have a coding account you want Catalyst to run on?" Then `references/choosing-a-coding-account.md`: the four kinds, what each asks for, how to enrol one, and what to do with an account that is out of rotation, needs a new credential, or has ended.
 
-## 3 — Connect Linear
+**Read back:** the `coding accounts` part: an enrolled, active account, named by its label. A cancelled or ended one is kept for reporting, not used, never re-tokened, and does not hold this step up.
 
-**For:** the account grain. Nothing about a project can be read or mapped until the tenant's Linear workspace is connected.
+**Owner:** a workspace owner or admin, in a browser, on the AI accounts page. Nothing you run ever sees the credential.
 
-**You hand over:** `<their cloud>/settings/connections`, and say: connect Linear.
+## 3. Connect the Linear integration
 
-**Read back:** after they say it is done, re-run `node scripts/where-am-i.mjs` and read them the `account` line. A resolved workspace is proof. If it still reads unresolved, say the contract may be cached and run `catalyst-skills contract --refresh`, then read it again.
+**For:** the workspace. Until the workspace's Linear connection exists, no project can be read or mapped. Say that this is the one connection the whole workspace shares, made once by an admin.
 
-**Owner:** a tenant owner or admin, in a browser. **This is a browser step by construction** — it is an authorization grant, and no key can perform one.
+**You hand over:** `<their cloud>/settings/connections` (the Integrations page; Settings labels it Connections today), and say: connect Linear. It sends them to Linear to authorise and brings them back.
 
-## 3a — Connect your personal Linear account
+**Read back:** after they say it is done, re-run the script and read them the `account` line. A resolved workspace is proof. If it still reads unresolved, run `catalyst-skills contract --refresh` and read it again.
 
-**For:** giving this person's agent its own provider access. The tenant's Linear connection and GitHub App serve the tenant; they do not prove that this member has approved personal grants.
+**Owner:** a workspace owner or admin, in a browser. **Browser by construction**: it is an authorization grant, and no key can perform one.
 
-**You run:** `catalyst-skills connections personal linear start`. It gives a short-lived URL and tries to open it. The person approves in their own browser. If the browser does not open, give them the URL printed by the command. Never paste a provider token into a prompt.
+## 4. Pick one project, and map its stages
 
-**Read back:** after approval, run `catalyst-skills connections personal linear status`. `node scripts/where-am-i.mjs` also reads the personal grant statuses. A URL opening is not proof that a grant landed.
+**For:** the project. A project is one Linear team plus the repositories registered to it. Until a project's stages are mapped, a card moved into it does nothing at all; this is the single most common reason a new workspace sees no activity.
 
-**Owner:** you start and check; the member approves in a browser. A usable personal Linear grant normally binds its viewer automatically. If identity remains unmatched, use `catalyst-skills identity linear options` for supported self-service recovery. Never choose a roster entry on the member's behalf. An already-resolved or already-claimed refusal needs an owner or admin to inspect the conflict.
-
-## 4 — Pick one project, and map its stages
-
-**For:** the project grain. A project is one Linear team. Until a project's stages are mapped, a card moved into it does nothing at all — this is the single most common reason a new tenant sees no activity.
-
-**You hand over:** `<their cloud>/settings/linear-teams`. They pick one project and press **Map my stages**, or **Adopt the Catalyst workflow** if they want Catalyst's own stages created for them.
+**You hand over:** `<their cloud>/settings/linear-teams`. They pick one team and press **Map my stages**, or **Adopt the Catalyst workflow** if they want Catalyst's stages created for them.
 
 **Read back:** re-run the script and read the `projects` line. A project that now appears with a readiness verdict is proof it was saved. Read them the verdict and any failing checks by name.
 
-**Owner:** a tenant owner or admin. ⛔ **Listing the projects and saving a mapping are settings-page work today** — a key cannot do either yet, and a key-callable path is being built. Say that plainly; it is a gap in the product, not something they did wrong.
-
-⭐ **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 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
+**Owner:** a workspace owner or admin. ⛔ Listing the projects and saving a mapping are settings-page work today; a key cannot do either yet. Say that plainly; it is a gap in the product, not something they did wrong.
 
-**For:** the repository grain. Registering is what makes a repository something a project can dispatch work into.
+⭐ **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: the project they care least about breaking.
 
-**You hand over:** `<their cloud>/settings/repositories`, and say: add the repository, **and attach it to the project you mapped in step 4**.
+## 5. Install the GitHub App
 
-**Read back:** re-run the script and read the `repositories` line. The repository appearing there is proof it was registered — and **only that**. It is not proof it can be dispatched to; see `references/who-fixes-what.md` for what registration does and does not prove.
+**For:** the workspace's GitHub integration. Without it Catalyst can read tickets but cannot touch code.
 
-**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.
+**You hand over:** the same Connections page, and say: install the GitHub App, and grant it the repository they want worked and `<org>/thoughts`. Catalyst's cloud phases write their notes to `<org>/thoughts`, where `<org>` owns the code repository. If it does not exist, they create a private repository named `thoughts`, initialized with a README, and then on the App's installation page for that org choose All repositories, or add `thoughts` to the selected repositories. The script's `repositories` part notes whether `gh` can see that repository, never that the App can reach it, so do not claim that.
 
-## 6a — Connect your personal GitHub account
+**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.
 
-**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.
+**Owner:** a workspace owner or admin, in a browser. Browser by construction, same reason as step 3.
 
-## 7 — Declare what the containers need
+## 6. Register the repository
 
-**For:** the environment a phase runs in — the names of the variables and secrets the person's code needs. Names leave the machine; values are entered once, by them, in the app.
+**For:** the repository. Registering, attached to a project, is what makes a repository something that project can dispatch work into.
 
-You can read, propose, and approve the account-wide declaration through the CLI if this member has an admin or owner seat. Personal connection initiation and status are also CLI actions; the provider approval remains in the browser.
+**You hand over:** `<their cloud>/settings/repositories`, and say: add the repository, **and attach it to the project you mapped in step 4**, in the same form.
 
-**You run:** `catalyst-skills environment` first, to read what the tenant already declares — the current revision, whether it is approved, and which revision a phase's checkout actually carries. Those last two are different things more often than people expect: a proposal that nobody approved changes nothing.
+**Read back:** re-run the script and read the `repositories` line. The repository appearing there proves it was registered, and only that; see `references/who-fixes-what.md` for what registration does not prove.
 
-To change it, write the declaration to a JSON file and propose it:
+**Owner:** a workspace owner or admin. ⛔ Registering is settings-page work today. ⛔ A repository registered without a project attached is the trap: the call succeeds, the repository is listed, and nothing can ever dispatch into it.
 
-```sh
-catalyst-skills environment propose --file declaration.json
-```
+## 7. Connect your own accounts
 
-Add `--approve` to approve exactly the revision that propose just returned, which is the one-command form and the one to prefer — it is a compare-and-set, and nothing gets copied between two commands by hand. `catalyst-skills environment approve` on its own reads the current revision and approves that.
+**For:** the person. The integrations serve the whole workspace; a connected account is this person's own Linear or GitHub login, so that what Catalyst does for them is attributed to them, and asks assigned to them can be told apart from everyone else's.
 
-**Read back:** the revision and hash the command printed, and whether it says the declaration is now what a phase's checkout carries. If it prints `referenced but not set on this tenant yet`, read those names out: the declaration names them and the tenant has no value for them, so a phase that needs one will fail on it until someone adds it in the app.
+**You run:** `catalyst-skills connections personal linear start`. It prints a short-lived URL and tries to open it; if the browser does not open, hand them the URL. Then `catalyst-skills connections personal linear status`. Do GitHub the same way, with `github`, only after the GitHub App is installed and the repository is registered: `catalyst-skills connections personal github start`, then `status`.
 
-**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.
+**Read back:** each `status`, and the script's `person` part: their label and role, whether their Linear identity is matched, and each grant. A URL opening is not proof a grant landed. If Linear identity stays unmatched after consent, `catalyst-skills identity linear status`, then `options`; the person picks their own listed identity and you run `catalyst-skills identity linear set <linearUserId>`. An already-resolved or claimed identity, and an inactive seat, need an owner or admin.
 
-⛔ **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`.
+**Owner:** you start and check; the person approves in a browser.
 
-If they do not know what their build needs yet, skip this step. It blocks nothing until a phase needs a secret.
+## 8. The repository's settings file
 
-## 8 — A coding account, and a host
+**For:** the repository's own settings, in `.catalyst/catalyst.toml` on its default branch: the Linear team it belongs to, the names of the variables and secrets its build needs, and its setup commands. Names leave the machine; values are entered once, by them, in the app.
 
-**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 ask:** one thing at a time. First: "Shall I draft it from your repository's own build files?" On a yes, ask where the repository is checked out on this machine; if it is not, write the file here for them to add. Then `references/declaring-a-repository.md`: the inventory, the file's shape, the pull request. Say what happens after the merge as context, not as a second task for now. After the merge, an owner or admin approves the revision on the repository's Environment page (Settings → Repositories → the repository → Environment → Setup declaration → Approve this revision) and enters the values on the same page. A workspace-wide declaration, if they want one, goes through `catalyst-skills environment` (read, propose, `--approve`), the one setup write you can perform.
 
-**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`.
+**Read back:** the script's `repository declarations` part, read from each project's `environment_declared` check: no file yet, invalid, awaiting approval, or in effect, per repository. Names only, never a value.
 
----
+**Owner:** the person, with you, in the repository; a workspace owner or admin for the approval.
 
-## 9 — Verify, then run the first ticket
+## 9. Verify, then run the first ticket
 
 **For:** the only thing that proves setup worked.
 
-**You run:** `catalyst-skills ready`. Its READY does not cover step 8; the script does. Read them the verdict and every failing line, each with its own fix and owner. If it says NOT READY, go to `references/who-fixes-what.md` before you touch anything — a project check failing is not something re-running anything on this machine can fix.
+**You run:** `catalyst-skills ready`. Its READY does not cover the coding account or the host; the script does. Read them the verdict and every failing line with its own fix and owner. If it says NOT READY, go to `references/who-fixes-what.md` before you touch anything.
 
-**Then:** have them move one card into the project's dispatch stage, and watch. `catalyst-skills explain <ticket>` says why it is or is not about to run. If they opted into local sync, use the optional first-event check in `references/local-sync.md`.
+**Then:** ask them to move one card into the project's start stage (usually Todo) and tell you which ticket it was. That is the whole question; do not offer to explain the pipeline or to search the backlog instead. Then watch. `catalyst-skills explain <ticket>` says why it is or is not about to run. If they opted into local sync, use the optional first-event check in `references/local-sync.md`.
 
-**Read back:** what `explain` actually said. If it says the ticket cannot start, the reason it names is the answer — read it to them and use the `how-catalyst-works` skill for what the reason means, then `unstick` if something is holding it.
+**Read back:** what `explain` actually said, and the first comment the agent leaves on the ticket. If `explain` says the ticket cannot start, the reason it names is the answer; use the `how-catalyst-works` skill for what it means, then `unstick` if something is holding it.
 
-**Owner:** the card move is theirs. The verdict is the tenant's.
+**Owner:** the card move is theirs. The verdict is the workspace'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.
+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. 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

@@ -17,7 +17,7 @@ A person can finish every other step and still see nothing run. A phase needs tw
 | `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 |
 
-**Owner:** the one the contract names. The person does it in the browser. Never ask for the credential, and never handle it. A key cannot enrol one.
+**Owner:** the one the contract names. The person does it in the browser. Never ask for the credential, and never handle it. A key cannot enrol one. Which kinds of account exist, what each asks for, and what to do with an ended or cancelled one are in `references/choosing-a-coding-account.md`; it is step 2 of the path, the first thing asked.
 
 **Older cloud:** if the contract has no `codingAccounts`, the script says the cloud is older and reads `catalyst-skills accounts` instead. That list counts the accounts enrolled and the ones able to take work. An expired, revoked or quarantined account does not count. The owner is then a tenant owner or admin, at `<their cloud>/settings/coding-accounts`.
 

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

@@ -9,7 +9,8 @@ These will never be a command, on any release. Each is an authorization a person
 | step | where | what you say |
 | -- | -- | -- |
 | 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." |
+| enrolling a coding account, or replacing its credential | the AI accounts page the script printed for the `coding accounts` part | "Choose the provider, give the account a label you will recognise, and paste the credential the page asks for. Nothing on this side sees it. Tell me when it is saved and I will read it back." |
+| connecting the Linear integration | `<their cloud>/settings/connections` (the Integrations page; Settings labels it Connections today) | "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 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." |

package/skills/catalyst-onboard/references/who-fixes-what.md

@@ -1,8 +1,8 @@
 # Who fixes what
 
-Setup is seven parts. Each has one instrument, and each instrument answers about its own part and nothing else. Read this before you tell a person that something is not ready, and before you tell them to do anything about it.
+Setup is eight parts. Each has one instrument, and each instrument answers about its own part and nothing else. Read this before you tell a person that something is not ready, and before you tell them to do anything about it. The product's words for what they own are Workspace, Project, Repository, Integration, Connected account and Member; the parts below are the instruments' names for the same things.
 
-## The seven parts, and the instrument that owns each
+## The eight parts, and the instrument that owns each
 
 | part | instrument | what a pass proves | what it does **not** prove | who fixes a failure, and where |
 | -- | -- | -- | -- | -- |
@@ -12,9 +12,10 @@ Setup is seven parts. Each has one instrument, and each instrument answers about
 | **project** | `catalyst-skills contract --path teams`, and the `team:` checks of `ready` | for each project **that has been mapped**: its readiness verdict and each failing check by name | that this is every project they have — see below | a tenant owner or admin, `<their cloud>/settings/linear-teams` |
 | **repository** | `catalyst-skills contract --path merge.repositories` | the repository is registered to the account | that it is active, that a project can dispatch into it, or that its environment is declared | a tenant owner or admin, `<their cloud>/settings/repositories` |
 | **coding accounts** | `codingAccounts` in `catalyst-skills contract` (`catalyst-skills accounts` on an older cloud) | an account is enrolled and active | that it has headroom left for the next phase | the enroller and page the contract names; see `references/what-a-phase-needs.md` |
+| **repository declarations** | the `environment_declared` check in `catalyst-skills contract --path teams`, and its per-repository notes | the project's default repository has a committed `.catalyst/catalyst.toml` in effect: ingested, valid, and its latest revision approved | that the values the names refer to exist; that any other repository is declared, unless its note says so | the person, with you, in the repository for the file; a tenant owner or admin for the approval, at the repository's Environment page under `<their cloud>/settings/repositories` |
 | **host** | the `hosts_current` check in `catalyst-skills contract --path teams` | no host is missing or behind, or the tenant runs none | anything before a project has been checked | the owner the contract names for `hosts_current`; see `references/what-a-phase-needs.md` |
 
-`node scripts/where-am-i.mjs` runs all seven and labels each finding with its part. Use it rather than composing this by hand.
+`node scripts/where-am-i.mjs` runs all eight, in the order a person can act on them, and labels each finding with its part. Use it rather than composing this by hand.
 
 ## The two silences that are not absences
 

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

@@ -34,9 +34,23 @@ export function tryLoadConfig() {
   }
 }
 
+/** The recorded CLI path, credential or no credential: a machine that was connected once and is now
+ *  logged out still has its CLI, and `status` on it is the honest first reading. Null when the config
+ *  is absent or unreadable. */
+function recordedCliPath() {
+  try {
+    const raw = JSON.parse(readFileSync(configPath(), "utf8"));
+    return typeof raw.cliPath === "string" && existsSync(raw.cliPath) ? raw.cliPath : null;
+  } catch {
+    return null;
+  }
+}
+
 /** Where the CLI is on this machine: the path login recorded when it still exists, else npx. */
 export function cliTarget(cfg = tryLoadConfig()) {
-  const recorded = cfg !== null && typeof cfg.cliPath === "string" && existsSync(cfg.cliPath);
+  const recordedPath = cfg !== null && typeof cfg.cliPath === "string" && existsSync(cfg.cliPath) ? cfg.cliPath : recordedCliPath();
+  if (recordedPath !== null) cfg = { ...(cfg ?? {}), cliPath: recordedPath };
+  const recorded = recordedPath !== null;
   return recorded
     ? { command: process.execPath, prefix: [cfg.cliPath], via: `node ${cfg.cliPath}`, recorded: true }
     : { command: "npx", prefix: [PACKAGE], via: `npx ${PACKAGE}`, recorded: false };

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

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
-// where-am-i.mjs — how far has setup got? SEVEN PARTS, EACH READ BY THE INSTRUMENT THAT OWNS IT, and
+// where-am-i.mjs — how far has setup got? EIGHT PARTS, EACH READ BY THE INSTRUMENT THAT OWNS IT, and
+// reported in the order a person can act on them (coding account first, then the integrations, the
+// project, its repository, the person's own connected accounts, the repository's declaration, the host);
 // each finding labelled with the part it belongs to. The whole point of this script is that no part
 // answers for another: a project that is not ready is reported as a project finding with a tenant
 // owner's name on it, never as something the person at this keyboard can fix by running anything.
@@ -18,8 +20,9 @@ const NOTES = [
   "`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` and `accounts --json` (coding accounts, and which one needs a new credential), and each",
-  "project's hosts_current check with its fixedWhere (host).",
+  "project's hosts_current check with its fixedWhere (host), and each project's environment_declared check with its per-repository notes (repository declarations).",
   "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.",
+  "When the tenant serves a contract version this CLI refuses, runs `npm view @catalyst-cloud/cli version` once to say whether a newer CLI is published.",
   "Writes nothing and changes nothing. Runs before this machine is connected — that is one of the states it reports.",
 ];
 
@@ -45,8 +48,28 @@ let repositoryRegistered = false;
 // `blocking` is false for a finding that is real and reportable but does not stop the next step —
 // an unmatched Linear identity is the one that matters: it must be said, and it must not become the
 // thing the person is told to go and do before they can map a project.
-const add = (part, instrument, verdict, lines, owner = null, where = null, blocking = true) =>
-  parts.push({ part, instrument, verdict, lines, owner, where, blocking });
+const add = (part, instrument, verdict, lines, owner = null, where = null, blocking = true) => {
+  const p = { part, instrument, verdict, lines, owner, where, blocking };
+  parts.push(p);
+  return p;
+};
+
+// A tenant contract outside this CLI's range makes every contract read fail the same way. When that
+// happens, no part read from the contract can back a next step, and the only honest next step is the
+// version itself. The CLI's own hint says to update, which is wrong when no newer CLI is published.
+let contractMismatch = null;
+const noteMismatch = (text) => {
+  const m =
+    (text ?? "").match(/serves contract version (\S+) but this bundle accepts (\S+)/) ??
+    (text ?? "").match(/contract: version (\S+) is outside this bundle's range (\S+)/);
+  if (m !== null) contractMismatch ??= { served: m[1], accepts: m[2] };
+  return m !== null;
+};
+const readContract = (args) => {
+  const r = runCli(args);
+  noteMismatch(r.stderr);
+  return r;
+};
 
 // ── machine ───────────────────────────────────────────────────────────────────────────────────────
 const status = runCli(["status"]);
@@ -87,10 +110,13 @@ if (connected) {
     projectChecks = checks.filter((c) => typeof c.id === "string" && c.id.startsWith("team:"));
     const machineChecks = checks.filter((c) => !(typeof c.id === "string" && c.id.startsWith("team:")));
     const failed = machineChecks.filter((c) => !c.ok && !c.note);
-    for (const c of machineChecks) machineLines.push(`${c.note ? "note" : c.ok ? "ok  " : "FAIL"} ${c.line}${!c.ok && !c.note && c.fix ? ` — fix: ${c.fix}` : ""}`);
+    // A refused contract version is printed without the CLI's "update" fix: whether an update exists
+    // is checked below, once, against what npm has published.
+    const refused = (c) => !c.ok && !c.note && noteMismatch(c.line);
+    for (const c of machineChecks) machineLines.push(`${c.note ? "note" : c.ok ? "ok  " : "FAIL"} ${c.line}${!c.ok && !c.note && c.fix && !refused(c) ? ` — fix: ${c.fix}` : ""}`);
     if (failed.length > 0) {
       machineVerdict = "unfinished";
-      machineFix = failed.find((c) => typeof c.fix === "string")?.fix ?? null;
+      machineFix = failed.find((c) => typeof c.fix === "string" && !refused(c))?.fix ?? null;
     }
   }
   // Supplemental only: local caches are optional and do not change setup completion or --next.
@@ -111,7 +137,8 @@ add(
   machineVerdict,
   machineLines,
   "you, on this machine",
-  connected ? null : CONNECT_LINE,
+  // The keyless login alone: a person who holds a personal key already knows the key form.
+  connected ? null : CONNECT_LINE.split(" (or")[0],
 );
 
 // ── person ────────────────────────────────────────────────────────────────────────────────────────
@@ -122,7 +149,8 @@ if (!connected) {
   const doc = tryJson(me.stdout);
   const user = doc && typeof doc.user === "object" && doc.user !== null ? doc.user : null;
   if (doc === null) {
-    add("person", "catalyst-skills me", "unreadable", [`me could not be read (${(me.stderr || me.stdout).trim().split("\n")[0] ?? "no output"})`], null, null);
+    add("person", "catalyst-skills me", "unreadable", [`me could not be read (${(me.stderr || me.stdout).trim().split("\n")[0] ?? "no output"})`], null, null).next =
+      "run this again; catalyst-skills me could not be read, so no step after it can be named yet";
   } else if (user === null) {
     add(
       "person",
@@ -161,7 +189,7 @@ if (!connected) {
       "catalyst-skills me, and catalyst-skills connections personal <provider> status --json",
       matched && !personalGrantIncomplete ? "ok" : "unfinished",
       [`${user.label ?? "(unnamed)"} (${user.role ?? "role unknown"})`, matched ? "Linear identity matched" : "Linear identity NOT matched — asks assigned to you cannot be told apart from everyone else's. It blocks nothing below. Run catalyst-skills identity linear options for self-service recovery; personal Linear consent normally binds its viewer automatically.", ...grantLines],
-      personalGrantIncomplete ? "you" : matched ? null : "a tenant owner or admin",
+      personalGrantIncomplete ? "you" : matched ? null : "a workspace owner or admin",
       personalGrantIncomplete ? "catalyst-skills connections personal <provider> start or status" : matched ? null : link("/settings/account"),
       false,
     );
@@ -172,10 +200,11 @@ if (!connected) {
 if (!connected) {
   add("account", "catalyst-skills contract --path account", "unreadable", ["not readable until this machine is connected"], null, null);
 } else {
-  const acct = runCli(["contract", "--path", "account", "--json"]);
+  const acct = readContract(["contract", "--path", "account", "--json"]);
   const doc = tryJson(acct.stdout);
   if (doc === null) {
-    add("account", "catalyst-skills contract --path account", "unreadable", ["the account block could not be read — try: catalyst-skills contract --refresh"], null, null);
+    add("account", "catalyst-skills contract --path account", "unreadable", ["the account block could not be read — try: catalyst-skills contract --refresh"], null, null).next =
+      "refresh the contract (catalyst-skills contract --refresh), then run this again; the account could not be read, so no step after it can be named yet";
   } else {
     const workspace = typeof doc.linearWorkspaceSlug === "string" && doc.linearWorkspaceSlug !== "" ? doc.linearWorkspaceSlug : typeof doc.linearWorkspaceId === "string" && doc.linearWorkspaceId !== "" ? doc.linearWorkspaceId : null;
     workspaceResolved = workspace !== null;
@@ -204,7 +233,7 @@ if (!connected) {
         "the GitHub App install is NOT carried here — the connections page is the only place that shows it",
         ...envLines,
       ],
-      "a tenant owner or admin",
+      "a workspace owner or admin",
       link("/settings/connections"),
     );
   }
@@ -216,12 +245,13 @@ let teamRows = null;
 if (!connected) {
   add("projects", "catalyst-skills contract --path teams", "unreadable", ["not readable until this machine is connected"], null, null);
 } else {
-  const teams = runCli(["contract", "--path", "teams", "--json"]);
+  const teams = readContract(["contract", "--path", "teams", "--json"]);
   const doc = tryJson(teams.stdout);
   const rows = Array.isArray(doc) ? doc : null;
   teamRows = rows;
   if (rows === null) {
-    add("projects", "catalyst-skills contract --path teams", "unreadable", ["the project list could not be read — try: catalyst-skills contract --refresh"], null, null);
+    add("projects", "catalyst-skills contract --path teams", "unreadable", ["the project list could not be read — try: catalyst-skills contract --refresh"], null, null).next =
+      "refresh the contract (catalyst-skills contract --refresh), then run this again; the project list could not be read, so no step after it can be named yet";
   } else {
     const lines = [`${rows.length} mapped`];
     for (const t of rows) {
@@ -243,7 +273,7 @@ if (!connected) {
       }
     }
     const ready = rows.length > 0 && rows.every(setUp);
-    add("projects", "catalyst-skills contract --path teams, and the team: checks of ready", ready ? "ok" : "unfinished", lines, "a tenant owner or admin", link("/settings/linear-teams"));
+    add("projects", "catalyst-skills contract --path teams, and the team: checks of ready", ready ? "ok" : "unfinished", lines, "a workspace owner or admin", link("/settings/linear-teams"));
   }
 }
 
@@ -262,17 +292,18 @@ function thoughtsNote(owner) {
 if (!connected) {
   add("repositories", "catalyst-skills contract --path merge.repositories", "unreadable", ["not readable until this machine is connected"], null, null);
 } else {
-  const repos = runCli(["contract", "--path", "merge.repositories", "--json"]);
+  const repos = readContract(["contract", "--path", "merge.repositories", "--json"]);
   const doc = tryJson(repos.stdout);
   const rows = Array.isArray(doc) ? doc : null;
   if (rows === null) {
-    add("repositories", "catalyst-skills contract --path merge.repositories", "unreadable", ["the repository list could not be read — try: catalyst-skills contract --refresh"], null, null);
+    add("repositories", "catalyst-skills contract --path merge.repositories", "unreadable", ["the repository list could not be read — try: catalyst-skills contract --refresh"], null, null).next =
+      "refresh the contract (catalyst-skills contract --refresh), then run this again; the repository list could not be read, so no step after it can be named yet";
   } else {
     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"));
+    add("repositories", "catalyst-skills contract --path merge.repositories", rows.length > 0 ? "ok" : "unfinished", lines, "a workspace owner or admin", link("/settings/repositories"));
   }
 }
 
@@ -282,17 +313,29 @@ if (!connected) {
 // 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 owner assumed.
 let accountsNext = "enrol a coding account a phase can run on";
+// A note --next prints beside the next step: an ended or cancelled account is not unfinished, but the
+// person must hear that it is kept for reporting and never re-tokened, before anyone reaches for a setup token.
+let retireNote = null;
 // 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"]);
+// credential itself. The cloud's own verdict, `needsCredential`, wins when it is sent:
+// it leaves out ended and revoked accounts and usage-endpoint refusals, which are not verdicts on the
+// credential. Older clouds send only the poll fields, read with the same narrowed code list.
+const CREDENTIAL_ERROR_CODES = new Set(["no_access_token", "no_credential"]);
 const CREDENTIAL_FAILURE_STREAK = 3;
 // A cancelled subscription or an ended account is not a credential problem: no token brings it
-// back. It is retired, never re-credentialed, and it does not make setup unfinished.
+// back. It is kept for reporting, never re-credentialed, and it does not make setup unfinished.
 const isRetirable = (a) => a?.renewalStatus === "canceled" || a?.status === "ended" || a?.declaredState === "ended";
 const credentialProblem = (a) => {
   if (isRetirable(a)) return null;
+  if (typeof a?.needsCredential === "boolean") {
+    if (!a.needsCredential) return null;
+    if (a.quarantined === true) return `quarantined${typeof a.quarantineReason === "string" && a.quarantineReason !== "" ? `: ${a.quarantineReason}` : ""}`;
+    if (a.status === "expired-or-revoked") return "expired or revoked";
+    return typeof a.lastPollErrorCode === "string" ? `its last ${a.pollFailureCount} polls failed with ${a.lastPollErrorCode}` : "the cloud says it needs a new credential";
+  }
+  if (a?.status === "ended" || (a?.revokedAtMs ?? null) !== null) return null;
   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) {
@@ -309,7 +352,7 @@ const readAccountRows = () => {
 if (!connected) {
   add("coding accounts", "codingAccounts in catalyst-skills contract", "unreadable", ["not readable until this machine is connected"], null, null);
 } else {
-  const res = runCli(["contract", "--path", "codingAccounts", "--json"]);
+  const res = readContract(["contract", "--path", "codingAccounts", "--json"]);
   const ca = tryJson(res.stdout);
   const older = ca === null && /has nothing at/.test(res.stderr ?? "");
   const INSTRUMENT = "codingAccounts in catalyst-skills contract";
@@ -324,7 +367,8 @@ if (!connected) {
       const dead = rows === null ? [] : rows.filter((a) => credentialProblem(a) !== null);
       const retirable = rows === null ? [] : rows.filter(isRetirable);
       const who = (a) => [a.label, a.email].find((v) => typeof v === "string" && v !== "");
-      const retireLine = retirable.length === 0 ? [] : [`${retirable.length} account(s) ended or cancelled (${retirable.map((a) => `${a.provider ?? "unknown provider"} ${a.accountSlot ?? "?"}`).join(", ")}): retire them on the AI accounts page. Do not replace their credential; no token revives a cancelled subscription.`];
+      const retireLine = retirable.length === 0 ? [] : [`${retirable.length} account(s) cancelled or ended (${retirable.map((a) => `${who(a) ?? a.displayName ?? a.accountSlot ?? "?"} (${a.provider ?? "unknown provider"})`).join(", ")}): kept for reporting, not used, and not counted here. Never replace their credential; reactivate one on the AI accounts page only if its subscription is live again.`];
+      retireNote = retireLine[0] ?? 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);
@@ -360,6 +404,7 @@ if (!connected) {
     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) {
+      accountsNext = "read the coding accounts again; the account list could not be read this time";
       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.
@@ -367,7 +412,7 @@ if (!connected) {
       const lines = [olderLine, `${rows.length} enrolled, ${usable.length} able to take work`];
       for (const a of rows) lines.push(`${a.accountSlot ?? "?"}: ${a.provider ?? "?"}, ${a.status ?? "status unknown"}${a.quarantined ? ", quarantined" : ""}`);
       if (usable.length === 0) lines.push("no phase can start until one is enrolled and able to take work");
-      add("coding accounts", "catalyst-skills accounts", usable.length > 0 ? "ok" : "unfinished", lines, "a tenant owner or admin", link("/settings/coding-accounts"));
+      add("coding accounts", "catalyst-skills accounts", usable.length > 0 ? "ok" : "unfinished", lines, "a workspace owner or admin", link("/settings/coding-accounts"));
     }
   } else {
     accountsNext = "read the coding accounts again; the contract could not be read";
@@ -383,7 +428,7 @@ if (!connected) {
   add("host", "hosts_current in catalyst-skills contract --path teams", "unreadable", ["not readable until this machine is connected"], null, null);
 } else {
   const checks = (teamRows ?? []).flatMap((t) => (Array.isArray(t.readiness?.checks) ? t.readiness.checks : []).filter((c) => c.id === "hosts_current").map((c) => ({ ...c, team: t.key ?? t.id ?? "(unkeyed)" })));
-  const meta = tryJson(runCli(["contract", "--path", "readinessChecks", "--json"]).stdout);
+  const meta = tryJson(readContract(["contract", "--path", "readinessChecks", "--json"]).stdout);
   const row = Array.isArray(meta) ? meta.find((r) => r.id === "hosts_current") : null;
   const hc = checks.find((c) => c.state === "fail") ?? checks.find((c) => c.state === "unknown") ?? checks[0] ?? null;
   // The contract's printed line for this owner is written for a host that is behind. When no host is
@@ -399,7 +444,10 @@ if (!connected) {
   const how = fw === null ? null : link(fw.page);
   const howLines = fw?.command ? [`the owner runs: ${fw.command}`] : [];
   if (hc === null) {
-    add("host", "hosts_current in catalyst-skills contract --path teams", "unreadable", [teamRows === null ? "the project list could not be read, so the host check cannot be either" : "no project has a readiness check yet, so whether a host is connected cannot be read. Press Re-check on the projects page."], "a tenant owner or admin", link("/settings/linear-teams"));
+    add("host", "hosts_current in catalyst-skills contract --path teams", "unreadable", [teamRows === null ? "the project list could not be read, so the host check cannot be either" : "no project has a readiness check yet, so whether a host is connected cannot be read. Press Re-check on the projects page."], "a workspace owner or admin", link("/settings/linear-teams")).next =
+      teamRows === null
+        ? "refresh the contract (catalyst-skills contract --refresh), then run this again; the project list could not be read, so the host check cannot be either"
+        : "press Re-check on the projects page, then run this again";
   } else if (hc.state === "pass") {
     add("host", "hosts_current in catalyst-skills contract --path teams", "ok", [`hosts_current pass (read on ${hc.team})`]);
   } else {
@@ -408,6 +456,70 @@ if (!connected) {
   }
 }
 
+// ── repository declarations ───────────────────────────────────────────────────────────────────────
+// A repository's own settings live in its committed `.catalyst/catalyst.toml`. Whether the project's
+// default repository has one in effect is the contract's `environment_declared` check; the project's
+// other repositories appear under that check's `repos`. Names only: nothing here reads a value, and
+// nothing here reads a file on this machine. A cloud that sends no such check has nothing to read.
+const DECL_INSTRUMENT = "environment_declared in catalyst-skills contract --path teams";
+const DECL_REASONS = {
+  no_team_repo_default: { text: "no repository is the project's default yet: register one and make it the default", who: "a workspace owner or admin", page: "/settings/repositories" },
+  no_environment_declaration: { text: "no .catalyst/catalyst.toml on its default branch yet: write it with the person (names only, never a value), open a pull request, merge it", who: "the person, in the repository, with your help", page: null },
+  declaration_invalid: { text: "the committed .catalyst/catalyst.toml did not validate: fix the file (the ingest names the error) and merge the fix", who: "the person, in the repository, with your help", page: null },
+  declaration_read_failed: { text: "the committed .catalyst/catalyst.toml could not be read: fix the file (the ingest names the error) and merge the fix", who: "the person, in the repository, with your help", page: null },
+  declaration_awaiting_approval: { text: "the declaration is proposed and waits for approval: Settings → Repositories → the repository → Environment → Setup declaration → Approve this revision", who: "a workspace owner or admin", page: "/settings/repositories" },
+};
+const DECL_DO = "write .catalyst/catalyst.toml with references/declaring-a-repository.md, then open a pull request";
+let declNext = "commit .catalyst/catalyst.toml to the repository and have an owner or admin approve it";
+if (!connected) {
+  add("repository declarations", DECL_INSTRUMENT, "unreadable", ["not readable until this machine is connected"], null, null);
+} else if (teamRows === null) {
+  add("repository declarations", DECL_INSTRUMENT, "unreadable", ["the project list could not be read, so no repository declaration can be either"], null, null).next =
+    "refresh the contract (catalyst-skills contract --refresh), then run this again; the project list could not be read, so no repository declaration can be either";
+} else if (teamRows.length === 0) {
+  add("repository declarations", DECL_INSTRUMENT, "unreadable", ["no project is mapped yet, so there is no repository whose declaration could be read"], null, null).next =
+    "map a project first; a repository declaration is read per project";
+} else if (teamRows.every((t) => !Array.isArray(t.readiness?.checks) || t.readiness.checks.length === 0)) {
+  // Mapped, never checked: the contract carries no checks at all until someone presses Re-check, and
+  // that silence is not "nothing to declare".
+  add("repository declarations", DECL_INSTRUMENT, "unreadable", ["no project has a readiness check yet, so whether its repository is declared cannot be read. Press Re-check on the projects page."], "a workspace owner or admin", link("/settings/linear-teams")).next =
+    "press Re-check on the projects page, then run this again";
+} else {
+  const found = teamRows.flatMap((t) => (Array.isArray(t.readiness?.checks) ? t.readiness.checks : []).filter((c) => c.id === "environment_declared").map((c) => ({ ...c, team: t.key ?? t.id ?? "(unkeyed)" })));
+  const lines = [];
+  let verdict = "ok";
+  let owner = null;
+  let where = null;
+  let unknown = false;
+  const describe = (reason) => DECL_REASONS[reason] ?? { text: `environment_declared ${reason ?? "failed"} (a reason this bundle does not know; read it on the page)`, who: "a workspace owner or admin", page: "/settings/repositories" };
+  const flag = (team, repo, reason) => {
+    const r = describe(reason);
+    lines.push(`${team}${repo ? `, ${repo}` : ""}: ${r.text}`);
+    if (verdict === "ok") declNext = `${repo ? `${repo}: ` : ""}${r.text}`;
+    verdict = "unfinished";
+    owner ??= r.who;
+    where ??= r.page === null ? DECL_DO : link(r.page);
+  };
+  if (found.length === 0) {
+    lines.push("this cloud reports no repository declaration check for the mapped projects, so there is nothing to read here; the repository's Environment page is where one would show");
+  }
+  for (const c of found) {
+    if (c.state === "pass") lines.push(`${c.team}: a declaration is in effect for the project's default repository`);
+    else if (c.state === "fail") flag(c.team, null, c.reason);
+    else {
+      unknown = true;
+      lines.push(`${c.team}: environment_declared could not be read${c.reason ? ` (${c.reason})` : ""}; press Re-check on the projects page`);
+    }
+    for (const note of Array.isArray(c.repos) ? c.repos : []) if (typeof note?.repo === "string" && note.reason) flag(c.team, note.repo, note.reason);
+  }
+  if (unknown && verdict === "ok") {
+    add("repository declarations", DECL_INSTRUMENT, "unreadable", lines, "a workspace owner or admin", link("/settings/linear-teams")).next = "press Re-check on the projects page, then run this again";
+  } else {
+    if (verdict !== "ok") lines.push("Names only: a value never passes through this script or the file. The person enters values on the repository's Environment page.");
+    add("repository declarations", DECL_INSTRUMENT, verdict, lines, verdict === "ok" ? null : owner, verdict === "ok" ? null : where);
+  }
+}
+
 // ── the single next step ──────────────────────────────────────────────────────────────────────────
 // The machine's next action is not one sentence: an unconnected machine needs the login, and a
 // connected one needs whatever check failed — and `ready` already printed that check's own fix, so
@@ -424,12 +536,20 @@ const NEXT = {
       : personalGithubIncomplete
         ? "install the tenant GitHub App and register its repository before connecting your personal GitHub account"
         : "get this person's seat and Linear identity sorted",
-  account: "connect Linear, and install the GitHub App",
+  account: "connect the Linear integration on the Connections page (the GitHub App comes later, with the repository)",
   projects: "pick ONE project and map its stages (or adopt the Catalyst workflow)",
-  repositories: "register the repository, attaching it to the project you mapped",
+  repositories: "install the GitHub App on the Connections page, granting it the repository you want worked; registering that repository on the Repositories page, attached to the project, is the step right after",
   "coding accounts": accountsNext,
+  "repository declarations": declNext,
   host: "connect a Catalyst host",
 };
+// The parts are read in the order their data allows and reported in the order a person can act on
+// them: the coding account first (nothing runs without one, and it needs no other step), then the
+// workspace's Linear integration, the project, the GitHub App with its repository, the person's own
+// connected accounts (personal GitHub after the repository proves the App), the repository's
+// declaration, and last the host. `--next` is the first unfinished part in this order.
+const ORDER = ["machine", "coding accounts", "account", "projects", "repositories", "person", "repository declarations", "host"];
+parts.sort((a, b) => ORDER.indexOf(a.part) - ORDER.indexOf(b.part));
 // A personal Linear grant cannot start until the tenant's Linear workspace exists. Once that account
 // connection is present, a missing personal grant becomes the next member step before project setup.
 const personPart = parts.find((p) => p.part === "person");
@@ -441,16 +561,50 @@ if (personPart && personalGrantIncomplete && workspaceResolved) {
 }
 const blocked = parts.filter((p) => p.verdict !== "ok" && p.blocking);
 const stuck = blocked[0] ?? parts.find((p) => p.verdict !== "ok") ?? null;
-const next =
+// ⛔ AN UNREADABLE PART NEVER BORROWS ITS "UNFINISHED" ACTION. NEXT holds what to do when a part was
+// read and is not done. A part that could not be read has no such basis: its step is reading it
+// again, and the parts after it depend on it, so none of theirs is named either. Coding accounts set
+// their own unreadable step in `accountsNext`.
+const actionFor = (p) =>
+  p.verdict === "unreadable" && p.part !== "coding accounts"
+    ? (p.next ?? `run this again; the ${p.part} part could not be read, so no step after it can be named yet`)
+    : NEXT[p.part];
+let next =
   stuck === null
     ? null
-    : { part: stuck.part, action: NEXT[stuck.part], owner: stuck.owner, where: stuck.where, blocking: stuck.blocking };
+    : { part: stuck.part, action: actionFor(stuck), owner: stuck.owner, where: stuck.where, blocking: stuck.blocking };
+
+// A refused contract version outranks every step above: each of them was read from, or waits on, a
+// contract this CLI would not accept. Whether an update exists is asked of npm, once, and only here.
+function versionAdvice() {
+  const semver = (t) => (t ?? "").match(/\b(\d+)\.(\d+)\.(\d+)\b/);
+  const installed = semver(field("Bundle"));
+  const npm = spawnSync("npm", ["view", "@catalyst-cloud/cli", "version"], { encoding: "utf8", timeout: 10_000, shell: process.platform === "win32" });
+  const latest = npm.error || npm.status !== 0 ? null : semver(npm.stdout);
+  // The installer is the update path, not `catalyst-skills install`. Its command is on the app's
+  // setup page; this names the script it fetches rather than composing the request here.
+  const reinstall = `re-run the install command from the app's setup page (it installs from ${link("/install.sh")})`;
+  if (installed === null || latest === null) {
+    return { text: `Whether a newer Catalyst CLI is published could not be checked. You can ${reinstall}; if this still appears afterwards, tell the Catalyst team.`, owner: null };
+  }
+  const order = [1, 2, 3].map((i) => Math.sign(Number(installed[i]) - Number(latest[i]))).find((d) => d !== 0) ?? 0;
+  return order >= 0
+    ? { text: "A newer Catalyst CLI isn't published yet. Tell the Catalyst team; nothing on this machine needs to change.", owner: "the Catalyst team" }
+    : { text: `Update the CLI: ${reinstall}.`, owner: "you, on this machine" };
+}
+if (contractMismatch !== null && stuck !== null) {
+  const advice = versionAdvice();
+  const line = `the tenant serves contract ${contractMismatch.served} and this CLI accepts ${contractMismatch.accepts}. ${advice.text}`;
+  stuck.lines.push(line);
+  next = { part: stuck.part, action: line, owner: advice.owner, where: null, blocking: true };
+}
 const finished = parts.every((p) => p.verdict === "ok");
 
 if (flags.json) {
-  console.log(JSON.stringify({ cli: via, connected, cloud, personalConnections, parts, localSync, next, finished }));
+  console.log(JSON.stringify({ cli: via, connected, cloud, personalConnections, parts, localSync, next, finished, notes: retireNote === null ? [] : [retireNote] }));
 } else if (flags.next) {
-  if (next === null) console.log("nothing left: every part is finished, a coding account is enrolled and the host check passes. Move one card into the project's dispatch stage.");
+  process.on("exit", () => { if (retireNote !== null) console.log(`note: ${retireNote}`); });
+  if (next === null) console.log("nothing left: every part is finished, a coding account is enrolled and the host check passes. Move one card into the project's start stage (usually Todo).");
   else console.log(`${next.part}: ${next.action}${next.blocking ? "" : " (does not block the steps below)"}${next.owner ? ` — who: ${next.owner}` : ""}${next.where ? ` — ${next.where.startsWith("http") ? "where" : "do"}: ${next.where}` : ""}`);
 } else {
   for (const p of parts) {
@@ -463,6 +617,6 @@ if (flags.json) {
     if (p.verdict !== "ok" && p.where) console.log(`  ${p.where.startsWith("http") ? "where" : "do"}: ${p.where}`);
     console.log("");
   }
-  console.log(next === null ? "next: nothing left — move one card into the project's dispatch stage and watch." : `next: ${next.part} — ${next.action}${next.owner ? ` (${next.owner})` : ""}${next.where ? ` — ${next.where}` : ""}`);
+  console.log(next === null ? "next: nothing left — move one card into the project's start stage (usually Todo) and watch." : `next: ${next.part} — ${next.action}${next.owner ? ` (${next.owner})` : ""}${next.where ? ` — ${next.where}` : ""}`);
 }
 process.exit(finished ? 0 : 1);

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.3 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.4 — written in this repository for customer tenants -->
 
 # Am I set up?
 

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

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.3 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.4 — 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.3 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.4 — 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.3 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.4 — 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.3 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.4 — written in this repository for customer tenants -->
 
 # What's happening