@catalyst-cloud/cli 0.15.6 → 0.16.1

package/dist/ready-copy.js

@@ -90,11 +90,11 @@ export function valuesFacts(value) {
             : [],
     };
 }
-/** Where the named variables get their values. Names only: nothing here reads or prints a value. */
-function setValuesFix(baseUrl, names) {
-    return baseUrl
-        ? `set ${names.join(", ")} on the repository's Environment page: open ${origin(baseUrl)}/settings/projects, then the project, then the repository`
-        : `set ${names.join(", ")} on the repository's Environment page in Catalyst's project settings`;
+/** How the named variables get their values: the CLI's own verbs, which read each value from a
+ *  hidden prompt. Names only: nothing here reads or prints a value. */
+function setValuesFix(names) {
+    const name = names.length === 1 && /^[A-Za-z_][A-Za-z0-9_]*$/.test(names[0]) ? names[0] : "NAME";
+    return `set ${names.join(", ")} with catalyst var set ${name} --repo <owner/name> (catalyst secret set ${name} --repo <owner/name> for a secret)`;
 }
 function nameList(v) {
     return Array.isArray(v)
@@ -127,13 +127,13 @@ function unresolvedLine(u) {
  *  identifier or a repository name, never a value, and nothing here reads a value. Any other check
  *  keeps the generic line. Shared with setup's values step, which has no web address when the
  *  saved login has none. */
-export function valuesFix(base, c) {
+export function valuesFix(_base, c) {
     const unresolved = unresolvedList(c.unresolved);
     const unresolvedNames = new Set(unresolved.map((u) => u.name));
     const names = nameList(c.names).filter((n) => !unresolvedNames.has(n));
     const parts = [];
     if (names.length > 0)
-        parts.push(setValuesFix(base, names));
+        parts.push(setValuesFix(names));
     for (const u of unresolved)
         parts.push(unresolvedLine(u));
     for (const note of Array.isArray(c.repos) ? c.repos : []) {
@@ -152,10 +152,6 @@ export function valuesFix(base, c) {
     }
     return parts.length === 0 ? null : parts.join(". ");
 }
-/** The team's own page in Catalyst settings, optionally one of its sub-pages (`map`, `adopt`). */
-export function teamPage(baseUrl, key, sub) {
-    return `${origin(baseUrl)}/settings/linear-teams/${encodeURIComponent(key)}${sub ? `/${sub}` : ""}`;
-}
 /** The dispatch gate: whether Catalyst may start any ticket in the team. */
 export function dispatchGateCopy(baseUrl, key, status, missingSlots) {
     if (status === "open")
@@ -170,18 +166,18 @@ export function dispatchGateCopy(baseUrl, key, status, missingSlots) {
     if (status === "mapping_missing")
         return {
             line: `team ${key}: Catalyst doesn't know which ${key} stages to use for ${slots}. Until it does, it starts no ${key} tickets.`,
-            fix: `pick them at ${teamPage(baseUrl, key, "map")}`,
+            fix: `run catalyst team map ${key}`,
         };
     if (status === "mapping_state_unresolved")
         // The gate reads Catalyst's own copy of the team, which can lag Linear by a minute after a team
         // is created or its workflow is set up (CTC-4680 Rerun A). Say that, not "map your stages".
         return {
             line: `team ${key}: Catalyst can't find the stages it uses for ${slots} in its copy of ${key} yet. Until it can, it starts no ${key} tickets.`,
-            fix: `if you just set up ${key}, run catalyst ready again in a minute. If this stays, press Re-check at ${teamPage(baseUrl, key)}`,
+            fix: `if you just set up ${key}, run catalyst ready again in a minute. If this stays, run catalyst team check ${key}`,
         };
     return {
         line: `team ${key}: Catalyst can't start ${key} tickets yet.`,
-        fix: `open ${teamPage(baseUrl, key)} to see why`,
+        fix: `run catalyst team check ${key} to see why`,
     };
 }
 const AUTOMATION_RULES = {
@@ -237,6 +233,13 @@ const CHECK_PAGES = {
     github_app_installed: "/settings/projects",
     thoughts_reachable: "/settings/projects",
 };
+/** The command that fixes a check, offered before its page. A check with no command keeps the page. */
+const CHECK_COMMANDS = {
+    webhook_covers_team: (key) => `an owner or admin registers the repository with catalyst onboard --team ${key} --repo <owner/name>`,
+    hosts_current: () => "run catalyst onboard --runner on the machine that runs the work",
+    tools_resolvable: () => "set the missing secret with catalyst secret set NAME --repo <owner/name>, or fix the repository's .catalyst/catalyst.toml",
+    reviewer_required: () => "relax the merge policy with catalyst var set CATALYST_MERGE_EVIDENCE_POLICY --repo <owner/name> (if .catalyst/catalyst.toml declares the policy, change it there instead, because the declaration wins), or configure a reviewer",
+};
 const AGAIN = "run catalyst ready again in a few minutes";
 /** One failing or unknown team check, in plain words. `valuesFix` is the variable-naming fix the
  *  caller already built for `required_values`, or null when the cloud named no variable. */
@@ -258,17 +261,17 @@ export function teamCheckCopy(baseUrl, key, id, state, valuesFix) {
     switch (id) {
         case "oauth_scope":
             return unknown
-                ? { line: team("Catalyst couldn't check its Linear connection."), fix: `check that Linear is connected at ${base}/settings/connections` }
+                ? { line: team("Catalyst couldn't check its Linear connection."), fix: "run catalyst onboard to check the Linear connection" }
                 : {
                     line: team("Catalyst's Linear connection is missing a permission it needs."),
-                    fix: `reconnect Linear at ${base}/settings/connections?reauthorize=linear`,
+                    fix: "run catalyst onboard and have an owner or admin approve the Linear link it prints",
                 };
         case "token_live":
             return unknown
                 ? { line: team("Catalyst couldn't reach Linear to check its connection."), fix: AGAIN }
                 : {
                     line: team("Linear stopped accepting Catalyst's connection. It was revoked or expired."),
-                    fix: `reconnect Linear at ${base}/settings/connections`,
+                    fix: "run catalyst onboard and have an owner or admin approve the Linear link it prints",
                 };
         case "team_visible":
             return unknown
@@ -285,16 +288,16 @@ export function teamCheckCopy(baseUrl, key, id, state, valuesFix) {
             if (id === "mapped_states_exist")
                 return {
                     line: team(`A stage Catalyst uses in ${key} was deleted or renamed in Linear.`),
-                    fix: `pick its replacement at ${teamPage(baseUrl, key, "map")}`,
+                    fix: `pick its replacement with catalyst team map ${key}`,
                 };
             if (id === "mapping_total")
                 return {
                     line: team(`${key}'s stages aren't all mapped yet, so Catalyst doesn't know where to move its tickets.`),
-                    fix: `map them at ${teamPage(baseUrl, key, "map")}, or set up Catalyst's workflow at ${teamPage(baseUrl, key, "adopt")}`,
+                    fix: `map them with catalyst team map ${key}, or set up Catalyst's workflow with catalyst team adopt ${key}`,
                 };
             return {
                 line: team(`A stage mapped in ${key} is the wrong kind, for example a Done stage that Linear treats as in progress.`),
-                fix: `choose the right stages at ${teamPage(baseUrl, key, "map")}`,
+                fix: `choose the right stages with catalyst team map ${key}`,
             };
         case "required_values":
             return unknown
@@ -304,22 +307,25 @@ export function teamCheckCopy(baseUrl, key, id, state, valuesFix) {
                 }
                 : {
                     line: team(`A variable ${key}'s repository needs has no value, so Catalyst can't run its work.`),
-                    fix: valuesFix ?? `add the missing values on the repository's Environment page: open ${base}/settings/projects, then the project, then the repository`,
+                    fix: valuesFix ?? setValuesFix(["the missing values"]),
                 };
         case "coding_account_enrolled":
             return unknown
                 ? { line: team("Catalyst couldn't check your AI accounts."), fix: AGAIN }
                 : {
                     line: team("Catalyst has no AI account to do the work with."),
-                    fix: `run catalyst setup to add one, or add it at ${base}/settings/coding-accounts`,
+                    fix: `an owner or admin adds one at ${base}/settings/coding-accounts; there is no command for that yet`,
                 };
     }
     const name = CHECK_NAMES[id] ?? id.replaceAll("_", " ");
-    const page = CHECK_PAGES[id] ?? `/settings/linear-teams/${encodeURIComponent(key)}`;
+    const page = CHECK_PAGES[id];
+    const command = CHECK_COMMANDS[id]?.(key);
     return unknown
         ? { line: team(`Catalyst hasn't checked ${name} yet.`), fix: AGAIN }
         : {
             line: team(`${name.charAt(0).toUpperCase()}${name.slice(1)} ${PLURAL.has(id) ? "need" : "needs"} attention.`),
-            fix: `open ${base}${page}`,
+            fix: command
+                ? page ? `${command}, or open ${base}${page}` : command
+                : page ? `open ${base}${page}` : `run catalyst team check ${key} to see why`,
         };
 }

package/dist/ready.js

@@ -15,7 +15,7 @@ import { FIRST_STAMPED_VERSION } from "./skill-shape.js";
 import { installedBundleVersion } from "./skills.js";
 import { onboardingReadyReport, observeCloudOnboarding, } from "./onboard-ready.js";
 import { selectedOnboardTeam } from "./onboard-existing.js";
-import { dispatchGateCopy, teamCheckCopy, teamPage, valuesFix, whoFixes } from "./ready-copy.js";
+import { dispatchGateCopy, teamCheckCopy, valuesFix, whoFixes } from "./ready-copy.js";
 import { onboardStatePath, readOnboardJournal } from "./onboard.js";
 export { semverOlder };
 /** `ready`'s own wording for the replica. It never recommends adopting the replica — until the
@@ -393,7 +393,7 @@ export async function readyReport(ctx, deps) {
                     line: team.readiness.status === "degraded"
                         ? `team ${label}: works, with some optional settings still missing`
                         : `team ${label}: not ready for work yet`,
-                    fix: `open ${teamPage(base, label)}`,
+                    fix: `run catalyst team check ${label} to see what is missing`,
                     who: whoFixes("mapping_total"),
                 });
             }

package/dist/secret.js

@@ -36,7 +36,7 @@ const IMPORT_REASONS = {
     name_taken_by_env_var: "already a plain environment variable; a name is a secret or a variable, never both",
     invalid_name: "not an env-style name (A-Z, 0-9 and _, starting with a letter)",
     invalid_value: "the value is empty",
-    config_rotation_unconfirmed: "the existing entry is a readable config value; change it in the app",
+    config_rotation_unconfirmed: "the existing entry is a plain variable; change it with catalyst var set",
     probe_refused: "the value failed this kind's check",
 };
 /** A command's stdout, minus the one trailing newline almost every command prints after a value. */
@@ -74,7 +74,7 @@ function refusalLine(status, body, repo) {
         return "refused (401): the cloud did not accept your credential here. If `catalyst me` works, this cloud predates secret writes from the CLI and needs a newer release; otherwise log in again.";
     }
     if (status === 404)
-        return `refused (404): ${repo} is not a repository of this tenant (register it in the app first)`;
+        return `refused (404): ${repo} is not a repository of this workspace. Register it first with catalyst onboard --team <KEY> --repo ${repo}`;
     if (status === 409 && body.error === "registry_not_migrated") {
         return "refused (409): the cloud's secret audit is not set up yet, so nothing was stored. Tell your Catalyst operator.";
     }

package/dist/setup-onboard-copy.js

@@ -508,9 +508,7 @@ function action(step, base, journal) {
         case "linear.adopt": {
             const team = journal?.steps.find((row) => row.id === "linear.team" && row.state === "done");
             const key = team && value(team, "teamKey");
-            return link(key
-                ? `/settings/linear-teams/${encodeURIComponent(key)}/adopt`
-                : "/settings/linear-teams", "set up the team's Catalyst workflow");
+            return `Run catalyst team adopt ${key || "<TEAM KEY>"} to preview the team's Catalyst workflow, then run it again with the --yes --plan-hash value it prints.`;
         }
         case "linear.automations":
             return "Open your Linear team settings and set each pull request automation to No action.";
@@ -572,17 +570,20 @@ export function setupFinalScreen(journal, base, paused = false, required = new S
                 : undefined
             : clean(onboardReasonText(readiness, { baseUrl: base, journal }))
         : undefined;
+    const machineOnly = journal.steps.some(step => step.reason === "returning_workspace_move_on");
     const heading = paused
         ? "Setup paused"
         : journal.steps.some((step) => step.id === "runner" &&
             (step.evidence?.selected === true || required.has(step.id)) &&
             step.state !== "done")
             ? "Not ready for work yet"
-            : journal.exit === 0 && journal.complete
-                ? "Setup complete"
-                : journal.exit === 0
-                    ? "Ready for work"
-                    : "Not ready for work yet";
+            : journal.exit === 0 && machineOnly
+                ? "This computer is set up"
+                : journal.exit === 0 && journal.complete
+                    ? "Setup complete"
+                    : journal.exit === 0
+                        ? "Ready for work"
+                        : "Not ready for work yet";
     const firstTicket = journal.steps.find((s) => s.id === "first-ticket");
     const ticket = firstTicket?.state === "done" ? firstTicket : undefined;
     const key = ticket && (value(ticket, "ticket") ?? value(ticket, "ticketKey"));
@@ -590,25 +591,27 @@ export function setupFinalScreen(journal, base, paused = false, required = new S
     const ticketUrl = savedTicketUrl && page(base, savedTicketUrl);
     const next = paused
         ? "Next: run catalyst onboard to continue."
-        : key
-            ? `Follow ${ticketUrl ?? key} in Linear; Catalyst comments there as each phase finishes.`
-            : heading === "Setup complete"
-                ? `Next: move a ticket to ${dispatchStageName(firstTicket?.evidence?.stage)} in Linear.`
-                : journal.exit === 0 && personal[0]
-                    ? `Next: ${personal[0].text[0].toLowerCase() + personal[0].text.slice(1)}`
-                    : personal.length === 1
-                        ? "Next: run catalyst onboard after you finish 1."
-                        : personal.length === 2
-                            ? "Next: run catalyst onboard after you finish 1 and 2."
-                            : personal.length
-                                ? "Next: run catalyst onboard after you finish 1 to " +
-                                    personal.length +
-                                    "."
-                                : actions.length
-                                    ? "Next: nothing for you to do. catalyst ready shows when Catalyst has read the settings."
-                                    : readyStep?.reason === "member_team_required"
-                                        ? "Next: run catalyst onboard --team <KEY> to check again."
-                                        : "Next: run catalyst onboard to check again.";
+        : machineOnly && journal.exit === 0
+            ? "Next: run catalyst ready to review your existing projects."
+            : key
+                ? `Follow ${ticketUrl ?? key} in Linear; Catalyst comments there as each phase finishes.`
+                : heading === "Setup complete"
+                    ? `Next: move a ticket to ${dispatchStageName(firstTicket?.evidence?.stage)} in Linear.`
+                    : journal.exit === 0 && personal[0]
+                        ? `Next: ${personal[0].text[0].toLowerCase() + personal[0].text.slice(1)}`
+                        : personal.length === 1
+                            ? "Next: run catalyst onboard after you finish 1."
+                            : personal.length === 2
+                                ? "Next: run catalyst onboard after you finish 1 and 2."
+                                : personal.length
+                                    ? "Next: run catalyst onboard after you finish 1 to " +
+                                        personal.length +
+                                        "."
+                                    : actions.length
+                                        ? "Next: nothing for you to do. catalyst ready shows when Catalyst has read the settings."
+                                        : readyStep?.reason === "member_team_required"
+                                            ? "Next: run catalyst onboard --team <KEY> to check again."
+                                            : "Next: run catalyst onboard to check again.";
     return {
         heading,
         readinessCause,
@@ -688,11 +691,13 @@ export function onboardJsonView(journal, base, paused = false, options = {}) {
         ? "paused"
         : journal.exit === 10
             ? "failed"
-            : screen.heading === "Setup complete"
-                ? "complete"
-                : screen.heading === "Ready for work"
-                    ? "ready"
-                    : "not-ready";
+            : screen.heading === "This computer is set up"
+                ? "machine-complete"
+                : screen.heading === "Setup complete"
+                    ? "complete"
+                    : screen.heading === "Ready for work"
+                        ? "ready"
+                        : "not-ready";
     const actions = screen.actions.map((action) => {
         const step = view.steps.find((step) => step.id === action.id);
         const role = view.steps.find((step) => step.id === "signin" && step.state === "done")?.evidence?.role;

package/dist/setup.js

@@ -89,6 +89,10 @@ export function engineFlags(args) {
             seen.verbose = true;
         if (a === "--with-replica")
             seen.localSync = true;
+        if (a === "--runner")
+            seen.runner = true;
+        if (a === "--no-runner")
+            seen.runner = false;
     }
     return seen;
 }

package/dist/transport.js

@@ -112,6 +112,22 @@ export class ApiClient {
             await this.refuseIfNotOk(res, `PUT ${path}`);
         return { status: res.status, body: await this.parseBody(res, `PUT ${path}`), headers: res.headers };
     }
+    async deleteJson(path, opts = {}) {
+        const res = await this.send(this.url(path), {
+            method: "DELETE",
+            headers: {
+                authorization: `Bearer ${await this.credential()}`,
+                accept: "application/json",
+            },
+        });
+        if (!opts.accept?.includes(res.status))
+            await this.refuseIfNotOk(res, `DELETE ${path}`);
+        return {
+            status: res.status,
+            body: await this.parseBody(res, `DELETE ${path}`),
+            headers: res.headers,
+        };
+    }
     async send(url, init) {
         try {
             return await this.fetchImpl(url, { ...init, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
@@ -142,7 +158,7 @@ export class ApiClient {
             reason = raw.slice(0, 200);
         }
         if (res.status === 401) {
-            throw new CliError(`${what} failed (401): credential not accepted — mint a personal key at Settings → API keys and log in again`, "unauthorized", 2, 401);
+            throw new CliError(`${what} failed (401): credential not accepted. Run catalyst login to sign in again; an unattended machine needs a new personal key from Settings → API keys`, "unauthorized", 2, 401);
         }
         if (res.status === 403) {
             throw new CliError(`${what} failed (403): this key may not reach that route${reason ? ` (${reason})` : ""} — a route that acts as a host (claiming work, publishing artifacts) needs the tenant's account key; every read and write a person makes takes your personal key`, "forbidden", 2, 403);
@@ -183,7 +199,7 @@ export async function fetchMe(baseUrl, key, fetchImpl, timeoutMs = REQUEST_TIMEO
             reason = "";
         }
         const detail = res.status === 401
-            ? "credential not accepted — mint a personal key at Settings → API keys and log in again"
+            ? "credential not accepted. Run catalyst login to sign in again; an unattended machine needs a new personal key from Settings → API keys"
             : reason || `HTTP ${res.status}`;
         throw new MeError(`GET /me failed (${res.status}): ${detail}`, "http", res.status);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.15.6",
+  "version": "0.16.1",
   "description": "Set up Catalyst Cloud, check your tickets and manage your account from the command line.",
   "license": "MIT",
   "type": "module",
@@ -48,18 +48,21 @@
     "paths:check": "node scripts/vendor-paths.mjs --check",
     "prose:check": "node scripts/check-public-prose.mjs",
     "settings:check": "node scripts/vendor-settings.mjs --check",
-    "self-host:check": "node scripts/vendor-self-host.mjs --check"
+    "self-host:check": "node scripts/vendor-self-host.mjs --check",
+    "release:check": "node scripts/release-train-check.mjs && node --test scripts/release-train-check.test.mjs",
+    "prepublishOnly": "node scripts/release-train-check.mjs --publish cli"
   },
   "dependencies": {
-    "@catalyst-cloud/sdk": "0.14.1",
+    "@catalyst-cloud/sdk": "0.16.1",
     "@clack/prompts": "1.8.1",
     "fast-string-width": "3.0.2",
     "fast-wrap-ansi": "0.2.2",
     "smol-toml": "^1.7.1",
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.0",
+    "@catalyst-cloud/sdk-replica-node": "0.16.1"
   },
   "devDependencies": {
-    "@catalyst-cloud/schema": "0.13.1",
+    "@catalyst-cloud/schema": "0.16.0",
     "@types/node": "^26.3.0",
     "@vitest/coverage-v8": "^4.1.11",
     "typescript": "^7.0.2",

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:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.1 — written in this repository for customer accounts -->
 
 # Catalyst's GitHub
 

package/skills/catalyst-linear/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's view of Linear on the customer's own cloud account. Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the cloud API by default, with local replica reads available as an explicit opt-in, always naming the source; searches tickets, PRs, projects and initiatives; writes comments, card moves, labels and new tickets through the account's agent proxy as the app actor, with every route, stage id, label id and marker read from the account's contract. Knows what a ticket accumulates as Catalyst works it (phase-outcome comments, the document per phase, the agent session, the labels, the single blocks relation, the bookkeeping marker, the eyes acknowledgement). Use when a person says "show me the ticket", "what did Catalyst write on it", "comment on it", "move it", "label it" or "file a ticket". Not for raising a decision for a human (what-needs-me) and not for pull requests (catalyst-github).
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.1 — written in this repository for customer accounts -->
 
 # Catalyst Linear
 

package/skills/catalyst-onboard/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Set up Catalyst Cloud and say whether setup is working. Walks a person from nothing to their first ticket running, one step at a time: the coding account, the project, the integrations and connected accounts, each repository's settings file, then one real ticket moving. Also logs this machine in, reads the readiness verdict with who can fix each failure, and checks the optional local replica. Use when someone says "set me up", "onboard me", "I just signed up", "get me started", "what do I do first", "log me in", "which account is this machine on", "am I set up", "what is missing", "why does nothing happen" or "is the replica running", when a login expired, or when a skill script exits 2 saying this machine is not connected. Does every step a key can do through the catalyst CLI, hands over the exact page for the steps only a browser can do, and never claims a step it did not watch succeed.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.1 — written in this repository for customer accounts -->
 
 # Onboard me
 
@@ -36,7 +36,7 @@ Default invited-member setup handles personal accounts and leaves workspace admi
 
 1. Run `node scripts/where-am-i.mjs --next` and read its one line; trust it over your memory of the last turn. A `note:` after it is worth one clause.
 2. Say what the step is for.
-3. Ask one question or do one thing. Run a `do:` command a key can run and show its output; hand over a browser step as `references/what-the-browser-owns.md` says.
+3. Ask one question or do one thing. Offer to run every step a command can do, run it on a yes and show its output; hand over a browser step only as `references/what-the-browser-owns.md` says.
 4. Wait for the answer. Two or three short sentences a turn; the full report is for you, not to paste.
 5. Re-run the script and read back the part that should have changed. Still unchanged after one `catalyst contract --refresh`: report both what the page said and what the instrument says.
 
@@ -55,7 +55,7 @@ Scripts are run, never read; each prints `--help`.
 | logging in, a refused or expired login, which account this is, the Linear identity | `references/connecting-this-machine.md` |
 | anything reports not ready, a check id, or who fixes something | `references/reading-ready.md` |
 | the coding account or the `host` part, or before saying work can run | `references/what-a-phase-needs.md`; a credential to replace, `references/replacing-a-credential.md` |
-| a browser step, or confirming a page that said it worked | `references/what-the-browser-owns.md` |
+| which steps a command does and which need a browser, or confirming a page that said it worked | `references/what-the-browser-owns.md` |
 | the repository's `.catalyst/catalyst.toml` and its approval; its AGENTS.md block and agent layout | `references/declaring-a-repository.md`; `references/repository-agent-setup.md` |
 | the replica or event cache | `references/local-sync.md` |
 | local SQL, only when `catalyst replica status --json` reports `configured: true` | `references/local-replica.md` |

package/skills/catalyst-onboard/references/connecting-this-machine.md

@@ -8,7 +8,7 @@
 
 Keyless is the preferred rail: `catalyst login` with no key prints a short code and a URL the person approves in a browser, or from a phone. Ask first, and run it once per code. The session refreshes silently, so they stay connected for months.
 
-A **personal key** is the fallback for a script or an unattended shell. Any active member mints one at Settings → API keys. The environment form keeps it out of shell history:
+A **personal key** is the fallback for a script or an unattended shell, where nobody can approve a code. Offer `catalyst login` first; a key is minted only in the browser, so for an unattended machine any active member mints one at Settings → API keys. The environment form keeps it out of shell history:
 
 ```sh
 CATALYST_CLOUD_TOKEN=<your-personal-key> catalyst login
@@ -18,7 +18,7 @@ CATALYST_CLOUD_TOKEN=<your-personal-key> catalyst login
 
 ## An unmatched Linear identity
 
-An unmatched Linear identity is the person's to match: `catalyst identity linear status`, then `catalyst identity linear options`; they pick their own listed identity and you run `catalyst identity linear set <linearUserId>`. An identity someone else claimed, and an inactive seat, need an owner or admin at Settings → Members. Connecting Linear personally does not set the identity: the identity and the personal grant are two different stored facts. Until the identity is matched, "what needs me" shows everyone's asks.
+An unmatched Linear identity is the person's to match: `catalyst identity linear status`, then `catalyst identity linear options`; they pick their own listed identity and you run `catalyst identity linear set <linearUserId>`. An identity someone else claimed, and an inactive seat, need an owner or admin at Settings → Members; no command does this yet, so raise one ask to them. Connecting Linear personally does not set the identity: the identity and the personal grant are two different stored facts. Until the identity is matched, "what needs me" shows everyone's asks.
 
 ## What login writes
 
@@ -27,9 +27,9 @@ An unmatched Linear identity is the person's to match: `catalyst identity linear
 ## When login fails
 
 - **"Your login expired or was revoked."** One fresh `catalyst login`.
-- **A 401 on the key rail.** A stale, mistyped or revoked key: mint a new one at Settings → API keys.
+- **A 401 on the key rail.** A stale, mistyped or revoked key: offer a keyless `catalyst login` instead; an unattended machine needs a new key from Settings → API keys.
 - **A 403 on the contract naming an older cloud.** The cloud lacks personal-key access: update the cloud, or use the account key until then.
 - **A line naming two contract versions.** `npm install -g @catalyst-cloud/cli@latest && catalyst login` before using the other skills.
-- **A refusal naming `jwt-no-membership`.** The cloud learns of a person at their first sign-in to the app. Have them sign in once, then log in again. If it repeats, their seat is inactive and an owner or admin activates it.
+- **A refusal naming `jwt-no-membership`.** The cloud learns of a person at their first sign-in to the app. Hand over the app's sign-in link once, then offer to run `catalyst login` again. If it repeats, their seat is inactive and an owner or admin activates it.
 
 Retry a failed login once, by hand, after the fix. A key goes into the login command or `CATALYST_CLOUD_TOKEN` and nowhere else: never a ticket, a transcript, or a file you write. After a bundle update, the next command prints a one-line notice; read it to the person if they are watching.

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

@@ -14,7 +14,7 @@ The assistant prepares `.catalyst/catalyst.toml` from the repository. Never ask
 
 Show a short preview with the project/team, setup and verify commands, variable names, which are marked secret, and confirmation that every variable is optional. Do not include values. Ask the person to approve this exact draft. Before approval, do not write or replace `.catalyst/catalyst.toml`, remove `catalyst.env.json`, or open a settings PR.
 
-After approval, write the validated file. When converting a legacy-only repository, remove `catalyst.env.json` in the same change. Open the settings PR, then offer to watch it merge. Once merged, give the owner or admin a direct link to approve the new declaration revision at Settings → Your projects → the project → Repositories → the repository → Environment → Setup declaration → Approve this revision. The direct route is `/settings/projects/$projectId/repositories/$repoId/environment/declaration`; use the project and repository ids from Catalyst instead of guessing them.
+After approval, write the validated file. When converting a legacy-only repository, remove `catalyst.env.json` in the same change. Open the settings PR, then offer to watch it merge. A reviewed merge is the approval. Catalyst approves the exact merged revision, with no second step, when someone other than the PR's author approved the merged head commit, or when a workspace owner or admin merged the PR. Tell the person this before they merge: the approving review is their consent to the setup commands and secret names in the file, so a reviewer should read it like code. A direct push, an unreviewed merge, or an approval left before the last commit leaves the revision proposed. No command approves one repository's revision yet, so only then give an owner or admin a direct link to approve it at Settings → Your projects → the project → Repositories → the repository → Environment → Setup declaration → Approve this revision. The direct route is `/settings/projects/$projectId/repositories/$repoId/environment/declaration`; use the project and repository ids from Catalyst instead of guessing them.
 
 ## File shape
 

package/skills/catalyst-onboard/references/reading-ready.md

@@ -7,7 +7,7 @@ Read this before telling a person something is not ready or what to do about it.
 | part | instrument | a pass does not prove |
 | -- | -- | -- |
 | **machine** | `catalyst status`, and the machine checks of `ready` | anything about the cloud account |
-| **person** | `catalyst me`, `catalyst connections personal <linear|github> status` | an active seat (an owner or admin fixes it in Settings → Members) |
+| **person** | `catalyst me`, `catalyst connections personal <linear|github> status` | an active seat (an owner or admin fixes it in Settings → Members; no command does this yet, so raise one ask to them) |
 | **account** | `catalyst contract --path account` (a resolved Linear workspace) | that the GitHub App is installed |
 | **project** | `catalyst team list`, then `team check <KEY>` and the `team:` checks of `ready` | that an unchecked team is ready |
 | **repository** | `catalyst contract --path merge.repositories` | that it is active, attached to a project, or declared |
@@ -21,7 +21,7 @@ Read this before telling a person something is not ready or what to do about it.
 Split the verdict first. In `catalyst ready --json`, an id that begins with `team:` is a **project** finding; the rest are **machine** findings. Report the two groups separately, machine first, each with its owner, its `pass`, `fail` and `unknown` counts, and when each team verdict was computed (`teams[].readiness.checkedAt`, null before any pass).
 
 - **A machine check failed:** the person's, here, now. Do its `fix` line.
-- **A project check failed:** name the check, the project and the `who`. A mapping is repaired with `catalyst team check`, `team map` or `team adopt`; a Linear connection, permission or team setting in a browser. Re-running `ready` fixes nothing.
+- **A project check failed:** name the check, the project and the `who`. Offer to run the repair: `catalyst team check`, `team map` or `team adopt` for a mapping, and `catalyst onboard` to start a Linear reconnection, whose consent link the owner or admin approves. Only Linear's own team access is a page in Linear. Re-running `ready` fixes nothing.
 - **A note** never moves the verdict; waiting is not failing, and unknown is not a pass.
 
 End every readiness answer with the verdict and the who-can-click-what list, in that order. Run each check once; waiting for one to clear is the project owner's watch (`run-this-project`).
@@ -34,20 +34,20 @@ A team is `ready`, `degraded`, `blocked` or `unchecked` (no pass yet, a note). S
 
 | check id | proves | when it fails | who clicks |
 | -- | -- | -- | -- |
-| `oauth_scope` | the Linear connection has the permissions it needs | re-authorise it | owner or admin, in settings |
-| `token_live` | the Linear connection is accepted now | reconnect if expired, revoked or never connected; re-check if Linear was unreachable | owner or admin |
-| `team_visible` | Catalyst can see the team | usually it went private: grant access in Linear | owner or admin, in Linear |
+| `oauth_scope` | the Linear connection has the permissions it needs | re-authorise it: `catalyst onboard` starts it and prints the consent link | owner or admin, in their browser |
+| `token_live` | the Linear connection is accepted now | reconnect with `catalyst onboard` if expired, revoked or never connected; `catalyst team check <KEY>` if Linear was unreachable | owner or admin |
+| `team_visible` | Catalyst can see the team | usually it went private: grant access in Linear, then `catalyst team check <KEY>` | owner or admin, in Linear |
 | `mapped_states_exist` | every mapped stage still exists | `catalyst team map <KEY>`; `stages_pending_write` means a mapping was just saved, so wait | owner or admin |
 | `mapping_total` | every stage Catalyst moves tickets into is mapped | map them ("absent": never mapped) | owner or admin |
 | `types_compatible` | each load-bearing stage is the right kind (dispatch and intake unstarted or backlog, PR started, done completed, canceled canceled) | map a stage of the right kind | owner or admin |
 | `labels_present` | Catalyst's labels exist | none: they are created on first use | nobody |
 | `writes_land` | Catalyst has written to the team | `no_write_observed` clears on the first move; a refused write: check the connection and permissions | owner or admin when refused; otherwise nobody |
-| `webhook_covers_team` | the team's events arrive | `no_delivery_observed` clears once a registered repository's events flow | owner or admin, by registering the repository |
+| `webhook_covers_team` | the team's events arrive | `no_delivery_observed` clears once a registered repository's events flow | owner or admin, by registering the repository: `catalyst onboard --team <KEY> --repo <owner/name>` |
 | `hosts_current` | no connected host runs an older mapping | `references/what-a-phase-needs.md`; `no_host_connected` is waiting | whoever runs that host |
-| `environment_declared` | the default repository's `.catalyst/catalyst.toml` is ingested, valid and approved | the reason names the step: register a default repository, commit or fix the file, or approve it (`references/declaring-a-repository.md`) | owner or admin, except committing the file, which is whoever can push |
-| `tools_resolvable` | every MCP server and CLI the declaration names resolves | `tool_reference_unresolved`: add the secret or fix the declaration; `toolchain_cli_missing` is not self-service | owner or admin, in the declaration or Settings → Environment |
-| `reviewer_required` | the repository can merge under its policy | a strict policy with no reviewer: configure one at Settings → Your projects → the project → Repositories → the repository → Code reviews, or relax the policy; only the merge waits | owner or admin, in settings |
-| `reviewer_configured` | a code reviewer is configured at all | configure one there; a fail never blocks or degrades | owner or admin, in settings; nobody is required when it fails |
+| `environment_declared` | the default repository's `.catalyst/catalyst.toml` is ingested, valid and approved | the reason names the step: register a default repository, commit or fix the file through a reviewed pull request, or approve a revision that merged without one (`references/declaring-a-repository.md`) | owner or admin, except committing the file, which is whoever can push |
+| `tools_resolvable` | every MCP server and CLI the declaration names resolves | `tool_reference_unresolved`: set the secret with `catalyst secret set NAME --repo <owner/name>`, or fix `.catalyst/catalyst.toml` in a pull request; `toolchain_cli_missing` is not self-service | owner or admin |
+| `reviewer_required` | the repository can merge under its policy | a strict policy with no reviewer: relax the policy with `catalyst var set CATALYST_MERGE_EVIDENCE_POLICY --repo <owner/name>` (a policy declared in `.catalyst/catalyst.toml` wins over the variable, so change it there in a pull request), or configure a reviewer at Settings → Your projects → the project → Repositories → the repository → Code reviews (no command for that yet); only the merge waits | owner or admin |
+| `reviewer_configured` | a code reviewer is configured at all | configure one there; a fail never blocks or degrades | owner or admin; nobody is required when it fails |
 
 ## The machine checks the CLI adds
 
@@ -70,10 +70,10 @@ Each failing line prints its own fix.
 
 A team receives work once its stages are saved. Saving one team changes no other team's stages or tickets; only the labels Adopt creates are shared. Once saved, tickets in its dispatch stage start, so pilot on a low-stakes team and first move anything there that should wait back to Backlog. Nothing reads `gitAutomation` in the contract.
 
-Each action exists in the terminal and on `<their cloud>/settings/linear-teams`:
+Each action is a command; offer to run it for an owner or admin:
 
-- **Check** (`catalyst team check <KEY>`, Re-check) saves the team's verdict, changing no ticket or mapping, and files one setup ticket for an admin if something is missing.
-- **Map** (`catalyst team map <KEY>`, Map my stages) saves a mapping from the team's existing stages and creates nothing in Linear.
-- **Adopt** (`catalyst team adopt <KEY>`, Adopt the Catalyst workflow) creates the missing stages and Catalyst's labels with the admin's own Linear authorisation, including the hold label a failed phase uses when the team has no remediate stage (`teams[].labels.hold`). The label alone means nothing failed.
+- **Check** (`catalyst team check <KEY>`) saves the team's verdict, changing no ticket or mapping, and files one setup ticket for an admin if something is missing.
+- **Map** (`catalyst team map <KEY>`) saves a mapping from the team's existing stages and creates nothing in Linear.
+- **Adopt** (`catalyst team adopt <KEY>`) creates the missing stages and Catalyst's labels with the admin's own Linear authorisation, including the hold label a failed phase uses when the team has no remediate stage (`teams[].labels.hold`). The label alone means nothing failed.
 
 Map when the team's stages already cover the work, Adopt when they do not.

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

@@ -1,6 +1,6 @@
 # Replacing an AI account's credential
 
-When the script prints "<provider> account <slot> needs a new credential" (quarantined, expired, revoked, or three or more polls failed on the credential), replace that account's credential on its own page. Do not enroll a second account. It would be a duplicate beside the dead one. A workspace owner or admin does it in the browser, from the link the script prints; the person copies and pastes the credential, and you never read, print or paste it.
+When the script prints "<provider> account <slot> needs a new credential" (quarantined, expired, revoked, or three or more polls failed on the credential), replace that account's credential on its own page. Do not enroll a second account. It would be a duplicate beside the dead one. No command replaces a credential yet, so a workspace owner or admin does it in the browser, from the link the script prints; the person copies and pastes the credential, and you never read, print or paste it.
 
 ## The steps
 

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

@@ -1,6 +1,6 @@
 # The one path
 
-The steps run in the order a person can act on them, each the cheapest place to catch what the next would hide. The script prints each step's owner and link; this page adds why it matters, what to ask, and its trap. Browser handovers follow `references/what-the-browser-owns.md`.
+The steps run in the order a person can act on them, each the cheapest place to catch what the next would hide. The script prints each step's owner and link; this page adds why it matters, what to ask, and its trap. Offer to run each step a command can do; browser handovers follow `references/what-the-browser-owns.md`.
 
 ## 0. Where are we
 
@@ -20,7 +20,7 @@ Each stage of a ticket runs on an account the person owns, at their own rate, un
 
 ## 3. Connect the Linear integration
 
-The one Linear connection the whole workspace shares, made once by an owner or admin on `<their cloud>/settings/connections`; no project can be read without it.
+The one Linear connection the whole workspace shares, made once by an owner or admin; no project can be read without it. Offer to start it: `catalyst onboard` asks Linear for the consent link and prints it, and the owner or admin approves it in their browser. Without that link, the page is `<their cloud>/settings/connections`.
 
 ## 4. Pick one project, and map its stages
 
@@ -28,15 +28,15 @@ A card moved into an unmapped project does nothing, the most common reason a new
 
 `catalyst team list` shows the teams without checking readiness; the person picks one key. `catalyst team map <KEY>` or `catalyst team adopt <KEY>` prints a preview to approve before `--yes --plan-hash <hash>` (exit 3 applied nothing). Run `catalyst team check <KEY>` only for the selected team. `team migrate <KEY>`, its `--retire`, and `team adopt <KEY> --undo` each preview and need their own approval. `catalyst capabilities` says which verbs this cloud serves.
 
-A `blocked` project is not set up. Change Linear's own Git automation rules in Linear for now (Settings → Teams → the team → Workflow → Workflows & automations → Pull request and commit automations → No action); hand that over, then re-check.
+A `blocked` project is not set up. There is no command for Linear's own Git automation rules yet, so hand over the page in Linear (Settings → Teams → the team → Workflow → Workflows & automations → Pull request and commit automations → No action), then offer to run `catalyst team check <KEY>`.
 
 ## 5. Install the GitHub App
 
-Without it Catalyst cannot touch code. On the same page, the owner or admin installs the App and grants it the repository plus `<org>/thoughts`, where cloud phases write their notes (`<org>` owns the code repository). If it does not exist, they create a private repository named `thoughts`, initialized with a README, then on the App's installation page for that org choose All repositories or add `thoughts`. The script notes whether `gh` can see that repository, never that the App can reach it. Step 6 succeeding is the proof the App is installed.
+Without it Catalyst cannot touch code. Offer to start the install: `catalyst onboard` prints the App's install link, and the owner or admin grants it the repository plus `<org>/thoughts` on GitHub, where cloud phases write their notes (`<org>` owns the code repository). If `thoughts` does not exist, offer to create it as a private repository named `thoughts`, initialized with a README (`gh repo create <org>/thoughts --private --add-readme`); then on the App's installation page for that org they choose All repositories or add `thoughts`. The script notes whether `gh` can see that repository, never that the App can reach it. Step 6 succeeding is the proof the App is installed.
 
 ## 6. Register the repository
 
-On `<their cloud>/settings/projects`, add the repository **and attach it to the project from step 4** in the same form. A repository registered without a project is listed and never receives work.
+Offer to register the repository **and attach it to the project from step 4** in one command: `catalyst onboard --team <KEY> --repo <owner/name>` (an owner or admin). A repository registered without a project is listed and never receives work.
 
 ## 7. Connect your own accounts