@catalyst-cloud/cli 0.16.0 → 0.16.2

package/dist/onboard-ui.js

@@ -444,6 +444,49 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
                 ...(answer === "signin" ? { signin: true } : {}),
             };
         },
+        async reviewProjects(projects) {
+            stop();
+            if (abort.signal.aborted)
+                return null;
+            const answer = await select({
+                ...options,
+                message: "What should setup do with this workspace's projects?",
+                initialValue: "move-on",
+                options: [
+                    { value: "move-on", label: "Move on and finish this computer's setup", hint: "default" },
+                    ...projects.map(p => ({ value: `repair:${p.id}`, label: `Review or repair ${p.name} (${p.key})` })),
+                    ...projects.map(p => ({ value: `cleanup:${p.id}`, label: `Preview archiving ${p.name} (${p.key})` })),
+                    { value: "new", label: "Create a new Catalyst project" },
+                ],
+            });
+            if (prompts.isCancel(answer)) {
+                abort.abort();
+                return null;
+            }
+            if (answer === "move-on" || answer === "new")
+                return answer;
+            if (typeof answer === "string" && answer.startsWith("cleanup:"))
+                return { cleanup: answer.slice(8) };
+            return typeof answer === "string" && answer.startsWith("repair:") ? { repair: answer.slice(7) } : null;
+        },
+        async confirmProjectCleanup(project, lines) {
+            stop();
+            for (const line of lines)
+                message(line);
+            if (abort.signal.aborted)
+                return false;
+            const answer = await select({ ...options,
+                message: `Archive ${project.name} after reviewing these changes?`,
+                initialValue: "keep",
+                options: [{ value: "keep", label: "Keep the project and finish this computer's setup" },
+                    { value: "archive", label: "Archive this project" }],
+            });
+            if (prompts.isCancel(answer)) {
+                abort.abort();
+                return false;
+            }
+            return answer === "archive";
+        },
         async chooseTeam(teams, create) {
             stop();
             // Creating needs a name prompt; a port without one offers only the existing teams.
@@ -671,6 +714,23 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             }
             return typeof answer === "string" ? answer : null;
         },
+        async nameMachine(defaultName) {
+            if (abort.signal.aborted)
+                return null;
+            const answer = await text({
+                ...options,
+                message: "Name for this machine",
+                initialValue: defaultName,
+                validate: (value) => /^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$/.test(value ?? "")
+                    ? undefined
+                    : "Use 1 to 63 letters, digits, dots, underscores or hyphens, starting with a letter or digit.",
+            });
+            if (typeof answer !== "string") {
+                abort.abort();
+                return null;
+            }
+            return answer;
+        },
         async chooseRunner() {
             if (abort.signal.aborted)
                 return null;
@@ -1114,6 +1174,7 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
         delete ui.chooseFirstRepository;
         delete ui.reviewSettings;
         delete ui.chooseRunner;
+        delete ui.nameMachine;
         delete ui.chooseFirstTicket;
         delete ui.retryTimedOut;
         delete ui.confirmWorkflowAdoption;

package/dist/onboard.js

@@ -268,6 +268,7 @@ function normalizeStep(value, fallbackAt) {
         "membershipId",
         "checkedAt",
         "project",
+        "projectCount",
         "repository",
         "installation",
         "ticket",
@@ -673,6 +674,7 @@ export function stepSatisfied(step) {
                 // Optional: a computer without the daily update still runs work.
                 step.id === "housekeeping" ||
                 step.reason === "member_scope" ||
+                step.reason === "returning_workspace_move_on" ||
                 (step.id === "daemon" && step.reason === "local_sync_not_selected") ||
                 (step.id === "runner" && step.reason === "runner_not_selected") ||
                 (step.id === "first-ticket" && step.reason === "first_ticket_skipped") ||
@@ -711,7 +713,8 @@ export function onboardRequiredStepsWaiting(journal) {
 }
 /** A full run that exited 0 with deferred steps still open: ready for work, not complete. */
 export function onboardReadyForWork(journal, only) {
-    return !only && journal.exit === 0 && !journal.complete;
+    return !only && journal.exit === 0 && !journal.complete &&
+        !journal.steps.some(step => step.reason === "returning_workspace_move_on");
 }
 /** A recorded step's next action; a prerequisite wait names the first unfinished step it needs. */
 export function onboardStepAction(journal, step, baseUrl) {
@@ -1143,7 +1146,11 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
         else if (deps.ui)
             deps.ui.finish(journal, only);
         else {
-            if (journal.complete)
+            if (journal.complete && journal.steps.some(step => step.reason === "returning_workspace_move_on")) {
+                ctx.stdout("This computer is set up. Existing projects were kept in place.");
+                ctx.stdout("Next: run catalyst ready to review their checks.");
+            }
+            else if (journal.complete)
                 ctx.stdout("Onboarding complete.");
             else if (onboardReadyForWork(journal, only) &&
                 (deps.requiredSteps ?? []).every((id) => journalStep(journal, id)?.state === "done")) {

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.16.0",
+  "version": "0.16.2",
   "description": "Set up Catalyst Cloud, check your tickets and manage your account from the command line.",
   "license": "MIT",
   "type": "module",
@@ -53,13 +53,13 @@
     "prepublishOnly": "node scripts/release-train-check.mjs --publish cli"
   },
   "dependencies": {
-    "@catalyst-cloud/sdk": "0.16.0",
+    "@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",
-    "@catalyst-cloud/sdk-replica-node": "0.16.0"
+    "@catalyst-cloud/sdk-replica-node": "0.16.1"
   },
   "devDependencies": {
     "@catalyst-cloud/schema": "0.16.0",

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.16.0 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.2 — 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.16.0 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.2 — 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.16.0 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.2 — 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. 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. 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.
+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