@catalyst-cloud/cli 0.9.2 → 0.9.4

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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.
+
+Onboarding no longer tells you to re-credential an ended or cancelled coding account: it says to retire it on the AI accounts page, and such an account no longer leaves setup unfinished. Before you mint a replacement token, it has you check that your terminal is logged into the account the slot belongs to. `catalyst accounts` names each account by its label, else its email, with the slot id second, adds `displayName` to `--json`, and marks a cancelled subscription "subscription canceled — retire on the AI accounts page".
+
 ## 0.9.2
 
 The CLI works against a tenant serving contract 2.x. Catalyst Cloud's tenant contract moved to 2.0.0 when it removed `merge.cloudRemediateRequiredChecks`, and every earlier bundle accepted only 1.x, so `ready`, onboarding and most commands stopped with "the tenant serves contract version 2.2.0 but this bundle accepts 1.x". This bundle accepts `1.x || 2.x`. The one place that read the removed field already treated it as absent.

package/dist/cli.js

@@ -2,7 +2,7 @@
 // their own modules; this file keeps every export the 0.1 tests and the bin import.
 import { existsSync } from "node:fs";
 import { parseArgs, positionals, verbHelp } from "./args.js";
-import { CONFIG_MODE, DEFAULT_BASE_URL, LEGACY_PACKAGE_NAME, PACKAGE_NAME, cliPath, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, formatMode, loadConfig, modernCliPath, normalizeBaseUrl, readManifest, requireConfig, saveConfig, writeConfig, } from "./config.js";
+import { CONFIG_MODE, DEFAULT_BASE_URL, LEGACY_PACKAGE_NAME, PACKAGE_NAME, cliPath, configPathFor, contractPathFor, defaultCtx, defaultReplicaDbFor, defaultSkillsDirFor, formatMode, installerOwnsSkills, INSTALL_COMMAND, loadConfig, modernCliPath, normalizeBaseUrl, readManifest, requireConfig, saveConfig, writeConfig, } from "./config.js";
 import { loadContract, pickPath } from "./contract.js";
 import { CliError, MeError, UsageError } from "./errors.js";
 import { fetchMe } from "./transport.js";
@@ -100,8 +100,14 @@ function migrateLegacyCliPath(ctx) {
     }
     if (!cfg)
         return;
-    const next = modernCliPath(cfg.cliPath);
-    if (next === null)
+    let next = modernCliPath(cfg.cliPath);
+    // An upgrade from @catalyst-cloud/catalyst-skills to @catalyst-cloud/cli removes the old package
+    // folder, so the recorded launcher no longer exists and has no sibling. Point it at the launcher
+    // that is running now, so `ready` and every skill script work without another login.
+    if (next === null && typeof cfg.cliPath === "string" && cfg.cliPath !== "" && !existsSync(cfg.cliPath)) {
+        next = cliPath();
+    }
+    if (next === null || next === cfg.cliPath)
         return;
     cfg.cliPath = next;
     try {
@@ -134,13 +140,23 @@ function maybePrintUpdateNotice(args, ctx) {
         const entry = parseChangelogEntry(readChangelog(), manifest.version);
         say(updateNoticeLine(previous, manifest.version, entry));
     }
+    if (installerOwnsSkills(ctx.home, ctx.env)) {
+        cfg.lastSkillBundleVersion = manifest.version;
+        try {
+            saveConfig(ctx.home, cfg);
+        }
+        catch {
+            // Best effort: the notice prints again next time, and nothing else depends on it.
+        }
+        return;
+    }
     const skillsDir = resolveSkillsDir(args, ctx, cfg);
     let refreshed;
     try {
         refreshed = installSkills(skillsDir, { force: false, onlyExisting: true });
     }
     catch (err) {
-        ctx.stderr(`[catalyst-skills] could not refresh the skills at ${skillsDir} (${err instanceof Error ? err.message : String(err)}) — the ${manifest.version} skills are not installed yet; run: catalyst-skills install`);
+        ctx.stderr(`[catalyst-skills] could not refresh the skills at ${skillsDir} (${err instanceof Error ? err.message : String(err)}) — the ${manifest.version} skills are not installed yet; re-run the install command: ${INSTALL_COMMAND}`);
         return;
     }
     if (refreshed.installed.length > 0)

package/dist/config.js

@@ -91,6 +91,8 @@ export function updatePackageName(root = packageRoot()) {
         return LEGACY_PACKAGE_NAME;
     return PACKAGE_NAME;
 }
+/** The Catalyst installer, which owns skill placement and switches a machine between packages. */
+export const INSTALL_COMMAND = "curl -fsSL https://staging.catalystcloud.dev/install.sh | sh";
 /** The one upgrade command every hint prints: update the installed package, then log in again so
  *  customer.json records the new launcher path. */
 export function upgradeCommand(root) {
@@ -115,6 +117,20 @@ export function normalizeBaseUrl(url) {
 export function apiBase(cfg) {
     return `${normalizeBaseUrl(cfg.baseUrl)}/api/v1`;
 }
+/** True when the Catalyst installer owns skill placement on this machine: it exports
+ *  CATALYST_SKILLS_DIR, or it wrote the machine paths file (every v1 record carries a skills role).
+ *  The CLI then never refreshes skill folders itself; the installer's own refresh does. */
+export function installerOwnsSkills(home, env = {}) {
+    if (env.CATALYST_SKILLS_DIR !== undefined && env.CATALYST_SKILLS_DIR !== "")
+        return true;
+    try {
+        const file = machinePathsFile({ env: { ...env, HOME: home } });
+        return Boolean(file && machineFilePresent(file));
+    }
+    catch {
+        return false;
+    }
+}
 function machineFilePresent(file) {
     try {
         lstatSync(file);

package/dist/execution.js

@@ -318,12 +318,23 @@ export const ACCOUNT_STATUS = {
     attested: "attested — healthy at last check, no work observed since",
     unobserved: "unobserved — enrolled, but nothing has been seen from it yet",
 };
+/** The name a person or agent calls an account by: its label, else its email, else its slot id. */
+export function accountDisplayName(a) {
+    for (const v of [a.label, a.email])
+        if (typeof v === "string" && v.trim() !== "")
+            return v.trim();
+    return a.accountSlot ?? "?";
+}
 /** One slot as a line a human reads: who it is, what state it is in, and what it is spending on. */
 export function renderAccount(a) {
-    const name = a.label ? `${a.accountSlot ?? "?"} (${a.label})` : (a.accountSlot ?? "?");
+    const display = accountDisplayName(a);
+    const name = display === (a.accountSlot ?? "?") ? display : `${display} (${a.accountSlot ?? "?"})`;
     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 kept for reporting and not used; never re-credential it (Ryan, 2026-09-29).
+    if (a.renewalStatus === "canceled")
+        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}`);
@@ -356,7 +367,8 @@ export async function cmdAccounts(args, ctx) {
         throw needsNewerCloud("coding-account status", cfg);
     const accounts = Array.isArray(res.body) ? res.body : (res.body?.accounts ?? []);
     if (args.json) {
-        ctx.stdout(JSON.stringify(res.body));
+        const named = accounts.map((a) => ({ ...a, displayName: accountDisplayName(a) }));
+        ctx.stdout(JSON.stringify(Array.isArray(res.body) ? named : { ...res.body, accounts: named }));
         return 0;
     }
     if (accounts.length === 0) {

package/dist/skills.js

@@ -1,6 +1,6 @@
 // skills.ts — copying the bundled skills into the user's skills directory, and the one-line update
 // notice a new version prints on its next session.
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { defaultSkillsDirFor, upgradeCommand } from "./config.js";
@@ -31,6 +31,10 @@ export function installSkills(targetDir, opts, sourceDir = skillsSourceDir()) {
         if (!existsSync(join(src, "SKILL.md")))
             continue;
         const dst = join(targetDir, name);
+        // A symlinked entry belongs to whoever linked it (the Catalyst installer links its skills in);
+        // this package never writes through one, and says nothing about it.
+        if (isSymlink(dst))
+            continue;
         const existingMd = join(dst, "SKILL.md");
         if (opts.onlyExisting && !existsSync(existingMd))
             continue;
@@ -47,6 +51,14 @@ export function installSkills(targetDir, opts, sourceDir = skillsSourceDir()) {
     }
     return result;
 }
+function isSymlink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
 export function resolveSkillsDir(args, ctx, cfg) {
     return args.skillsDir ?? ctx.env.CATALYST_SKILLS_CLAUDE_DIR ?? cfg?.skillsDir ?? defaultSkillsDirFor(ctx.home);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.9.2",
+  "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.2 — 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.2 — 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.2 — 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

@@ -34,7 +34,11 @@ Say these two things plainly:
 
 ## Claude
 
-The same page takes a Claude account's new credential. Its field is "Replacement setup token". The person runs `claude setup-token` in their terminal, pastes the token it prints into that field, and presses Replace credential. Then re-run the script.
+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.
+
+## 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. 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