@catalyst-cloud/cli 0.15.2 → 0.15.4

package/dist/setup-render.js

@@ -8,7 +8,10 @@
 import { styleText } from "node:util";
 import { wrapAnsi } from "fast-wrap-ansi";
 import stringWidth from "fast-string-width";
+import { colourLevel, markSkipped, markSpan, pixelNucleusLines, } from "./setup-brand.js";
+import { detectTheme, envTheme, } from "./terminal-background.js";
 const DEFAULT_COLUMNS = 80;
+const graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 const MIN_COLUMNS = 40;
 function utf8Locale(env) {
     return /utf-?8/i.test(env.LC_ALL || env.LC_CTYPE || env.LANG || "");
@@ -60,6 +63,7 @@ const ASCII_MARKS = {
     later: "[later]",
     run: "[..]",
     ask: "[?]",
+    now: "[next]",
 };
 const UNICODE_MARKS = {
     done: ["✓", "green"],
@@ -69,8 +73,22 @@ const UNICODE_MARKS = {
     later: ["·", "gray"],
     run: ["◐", "cyan"],
     ask: ["◆", "cyan"],
+    now: ["◆", "cyan"],
 };
-export function createSetupRenderer(stream, env) {
+/**
+ * The banner options for the onboard flow: the mark only for `catalyst setup`, and the background
+ * asked of the terminal only when the mark will be drawn and both stdin and stdout are terminals.
+ */
+export async function setupBanner(options) {
+    const { setup, env, input, stream, noColor } = options;
+    const tty = stream.isTTY === true && options.stdout.isTTY === true;
+    const columns = stream.columns && stream.columns > 0 ? stream.columns : DEFAULT_COLUMNS;
+    const ask = !markSkipped({ setup, tty, columns, env, noColor }) && input.isTTY === true
+        ? { input, output: stream }
+        : undefined;
+    return { mark: setup, stream, noColor, theme: await detectTheme(env, ask) };
+}
+export function createSetupRenderer(stream, env, banner = {}) {
     let traits = terminalTraits(stream, env);
     const style = (format, text) => traits.color ? styleText(format, text, { validateStream: false }) : text;
     let width = Math.min(traits.columns, 100);
@@ -85,12 +103,14 @@ export function createSetupRenderer(stream, env) {
     const visible = (text) => text
         .replace(/\u001b\]8;;[^\u001b]*\u001b\\/g, "")
         .replace(/\u001b\[[0-9;]*m/g, "");
-    const rail = traits.unicode ? "│" : "";
-    // CTC-4680: details sit 4 columns in (under the rail in Unicode), not under the step title at 6 or
-    // 11, so the eye doesn't travel across a small screen to read them.
-    const titleCol = 4;
-    const outcomeCol = traits.unicode ? 38 : 43;
-    const prefix = (col) => rail + " ".repeat(col - rail.length);
+    // CTC-4680 (round 2): headings and prose at column 2, step rows at 4, and their details 4 more,
+    // at 8, so the eye doesn't travel across a small screen to read them. No rail: the same columns
+    // on a terminal and in a pipe.
+    const textCol = 2;
+    const rowCol = 4;
+    const titleCol = rowCol + 4;
+    const outcomeCol = rowCol + (traits.unicode ? 38 : 43);
+    const prefix = (col) => " ".repeat(col);
     const mark = (kind) => {
         if (!traits.unicode)
             return ASCII_MARKS[kind];
@@ -111,9 +131,7 @@ export function createSetupRenderer(stream, env) {
             .map((line) => {
             const plain = visible(line);
             const indent = /^https?:\/\/\S+$/.test(plain) && stringWidth(plain) > width - col
-                ? traits.unicode
-                    ? 3
-                    : 0
+                ? textCol
                 : col;
             return prefix(indent) + line;
         });
@@ -122,13 +140,13 @@ export function createSetupRenderer(stream, env) {
         refresh();
         const lead = plan
             ? traits.unicode
-                ? "│"
+                ? " "
                 : "       "
             : traits.unicode
                 ? mark(kind)
                 : mark(kind).padEnd(7);
         const titleWidth = stringWidth(visible(title));
-        const label = `${lead}${traits.unicode ? "  " : " "}${String(number || "").padStart(2)} ${title}`;
+        const label = `${prefix(rowCol)}${lead}${traits.unicode ? "  " : " "}${String(number || "").padStart(2)} ${title}`;
         if (!outcome)
             return [label];
         if (width < 80 || titleWidth > 30)
@@ -214,6 +232,7 @@ export function createSetupRenderer(stream, env) {
         clear();
         abandon();
     };
+    let branded = false;
     const r = {
         get traits() {
             refresh();
@@ -221,11 +240,66 @@ export function createSetupRenderer(stream, env) {
         },
         intro(title) {
             refresh();
-            ordinary([traits.unicode ? `┌  ${style("bold", title)}` : title]);
+            ordinary([prefix(textCol) + style("bold", title)]);
+        },
+        brand(program, version, identity) {
+            if (branded)
+                return false;
+            branded = true;
+            refresh();
+            const out = banner.stream ?? stream;
+            const tty = out.isTTY === true && stream.isTTY === true;
+            const columns = tty && out.columns && out.columns > 0 ? out.columns : traits.columns;
+            const separator = utf8Locale(env) ? " · " : " ";
+            const words = [
+                "Catalyst Cloud",
+                `${program}${version ? `${separator}${version}` : ""}`,
+                ...(identity
+                    ? [`user:      ${identity.user}`, `workspace: ${identity.workspace}`]
+                    : []),
+            ];
+            const print = (lines) => out.write(lines.join("\n") + "\n");
+            const level = colourLevel(env, { tty, noColor: banner.noColor });
+            if (level === "none" ||
+                markSkipped({ setup: banner.mark === true, tty, columns, env, noColor: banner.noColor })) {
+                // Without the mark the words carry everything, plainly: a screen reader reads blocks aloud.
+                print(words.map((w) => prefix(textCol) + w));
+                return identity !== undefined;
+            }
+            // Beside the middle of the mark, 4 columns from it, each cut short with … rather than
+            // wrapped under it when the terminal is narrow.
+            const textAt = textCol + markSpan() + 4;
+            const room = columns - textAt - 1;
+            const fit = (text) => {
+                if (stringWidth(text) <= room)
+                    return text;
+                // Cut by what the terminal draws: whole graphemes, counted in columns.
+                let cut = "";
+                for (const { segment } of graphemes.segment(text)) {
+                    if (stringWidth(cut + segment) > room - 1)
+                        break;
+                    cut += segment;
+                }
+                return `${cut}…`;
+            };
+            const styled = words.map((w, i) => i === 0 && fit(w) === w ? `\u001b[1m${w}\u001b[22m` : fit(w));
+            const mark = pixelNucleusLines(banner.theme ?? envTheme(env) ?? "dark", level);
+            const first = Math.floor((mark.length - styled.length) / 2);
+            print(mark.map((line, i) => {
+                const text = styled[i - first];
+                return text
+                    ? `${prefix(textCol)}${line}    ${text}`
+                    : `${prefix(textCol)}${line}`.trimEnd();
+            }));
+            return identity !== undefined;
+        },
+        tracker(parts) {
+            ordinary(parts.flatMap((p) => stepRows(p.mark, p.number, p.title, p.note)));
         },
         outro(text) {
             abandon();
-            write(traits.unicode ? [`│`, `└  ${text}`] : ["", text]);
+            // Wrapped by words like any prose, a link kept whole on its own line when it is too long.
+            write(["", ...rows(text, textCol)]);
         },
         plan(number, title, text) {
             ordinary(stepRows("run", number, title, text, true));
@@ -318,14 +392,22 @@ export function createSetupRenderer(stream, env) {
         },
         heading(text) {
             abandon();
-            write(traits.unicode ? ["│", `├─ ${style("bold", text)}`] : ["", text]);
+            write(["", prefix(textCol) + style("bold", text)]);
         },
         line(text) {
-            ordinary(rows(text, traits.unicode ? 3 : 0));
+            ordinary(rows(text, textCol));
+        },
+        item(label, text) {
+            const col = textCol + stringWidth(label);
+            const lines = rows(text, col);
+            const hang = prefix(col);
+            ordinary(lines[0].startsWith(hang)
+                ? [prefix(textCol) + label + lines[0].slice(col), ...lines.slice(1)]
+                : [prefix(textCol) + label.trimEnd(), ...lines]);
         },
         blank() {
             refresh();
-            ordinary([rail]);
+            ordinary([""]);
         },
         link(url) {
             return traits.links

package/dist/setup.js

@@ -19,6 +19,7 @@ import { Readable, Writable } from "node:stream";
 import { VERB_USAGE } from "./args.js";
 import { plainSetupLine, SetupEventStream, } from "./setup-events.js";
 import { createSetupRenderer, } from "./setup-render.js";
+import { setupPartHeading } from "./setup-onboard-copy.js";
 const MACHINE_TITLES = {
     1: "Install the catalyst command",
     2: "Add the Catalyst skills",
@@ -107,7 +108,7 @@ function planRenderer(r) {
         },
         more(text) {
             if (!hidden)
-                r.line(`       ${text}`);
+                r.line(`      ${text}`);
         },
         close() {
             open = false;
@@ -238,7 +239,9 @@ async function runEngine(engine, args, flags, ctx, deps) {
                 }
                 if (!deps.onboard ||
                     !["What’s left", "What\'s left"].includes(event.text))
-                    r.heading(event.text === "Setting up" ? "This computer" : event.text);
+                    r.heading(event.text === "Setting up"
+                        ? setupPartHeading(1, r.traits.unicode)
+                        : event.text);
                 return;
             case "plan":
                 plan.plan(event.number, event.title, event.text);
@@ -399,7 +402,7 @@ async function runEngine(engine, args, flags, ctx, deps) {
                 return await deps.onboard(r, flags);
             }
             catch {
-                errors.line("catalyst setup: onboarding could not finish. Run catalyst onboard to try again.");
+                errors.line("catalyst setup: onboarding could not finish. Run catalyst setup to try again.");
                 if (flags.json)
                     deps.writeJson(`${JSON.stringify({ schema: "catalyst-install-last-run/1", state: "failed", exitCode: 10, steps: [] })}\n`);
                 return 10;

package/dist/terminal-background.js

@@ -0,0 +1,220 @@
+// terminal-background.ts — CTC-4680: is the terminal's background light or dark, so setup's mark
+// takes the brand's light or dark colours. The order: CATALYST_THEME, then COLORFGBG, then asking
+// the terminal (OSC 11), then dark. Asking is the only part that touches the terminal, and it must
+// leave nothing behind: the input's mode is restored, the reply never reaches the first prompt, and
+// a key the person pressed meanwhile is handed back to the input rather than eaten.
+/** CATALYST_THEME=light|dark, then COLORFGBG ("fg;bg", where 7 and 15 are light). Null when
+ *  neither says. */
+export function envTheme(env) {
+    const chosen = (env.CATALYST_THEME ?? "").trim().toLowerCase();
+    if (chosen === "light" || chosen === "dark")
+        return chosen;
+    const bg = (env.COLORFGBG ?? "").split(";").at(-1) ?? "";
+    if (!/^[0-9]+$/.test(bg))
+        return null;
+    return bg === "7" || bg === "15" ? "light" : "dark";
+}
+/**
+ * The colour in an OSC 11 reply, `ESC ] 11 ; rgb:RRRR/GGGG/BBBB` ended by BEL or ST. Each part is
+ * 1 to 4 hex digits, scaled to 0..1.
+ */
+export function parseOsc11(reply) {
+    const m = /\u001b\]11;rgba?:([0-9a-f]{1,4})\/([0-9a-f]{1,4})\/([0-9a-f]{1,4})/i.exec(reply);
+    if (!m)
+        return null;
+    const scale = (hex) => Number.parseInt(hex, 16) / (16 ** hex.length - 1);
+    return [scale(m[1]), scale(m[2]), scale(m[3])];
+}
+/** Light above 0.5 luma (Rec. 709 weights on the colour as sent). */
+export function themeOf(rgb) {
+    return 0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2] > 0.5
+        ? "light"
+        : "dark";
+}
+const OSC11_REPLY = /\u001b\]11;[^\u0007\u001b]*(?:\u0007|\u001b\\)/;
+/** Primary device attributes (DA1). Terminals answer in order and nearly all answer DA1, so once
+ *  its reply is in, no OSC 11 reply can follow: the query ends there, not at the timeout. */
+const DA1_REPLY = /\u001b\[\?[0-9;]*c/;
+/** Bytes that may be the start of a reply still arriving. */
+const REPLY_START = /^\u001b(?:$|\](?:1(?:1(?:;[^\u0007\u001b]*(?:\u001b)?)?)?)?$|\[(?:\?[0-9;]*)?$)/;
+export const QUERY_TIMEOUT_MS = 150;
+/**
+ * After the timeout the answer is dark, but a slow terminal may still reply. For this long the
+ * replies are still taken out of the input, so a late one never reaches the shell or the first
+ * prompt. It ends sooner when the DA1 reply arrives.
+ */
+export const LATE_MS = 350;
+/** Splits terminal replies out of the input as it arrives; what is left is what the person typed. */
+function replyFilter() {
+    let pending = "";
+    return {
+        /** What is held back as a possible reply start, emptied. */
+        release() {
+            const held = pending;
+            pending = "";
+            return held;
+        },
+        /** Adds `text`; returns the keys in it and whether DA1 (the last reply) is in. */
+        take(text) {
+            pending += text;
+            let osc = null;
+            let answered = false;
+            for (;;) {
+                const reply = OSC11_REPLY.exec(pending);
+                if (reply) {
+                    const rgb = parseOsc11(reply[0]);
+                    if (rgb)
+                        osc = themeOf(rgb);
+                    pending = pending.slice(0, reply.index) + pending.slice(reply.index + reply[0].length);
+                    continue;
+                }
+                const da1 = DA1_REPLY.exec(pending);
+                if (!da1)
+                    break;
+                pending = pending.slice(0, da1.index) + pending.slice(da1.index + da1[0].length);
+                answered = true;
+            }
+            // Whatever cannot be the start of a reply is a key; after DA1 nothing is a reply.
+            let keep = pending.length;
+            if (!answered)
+                for (let i = pending.indexOf("\u001b"); i !== -1; i = pending.indexOf("\u001b", i + 1))
+                    if (REPLY_START.test(pending.slice(i))) {
+                        keep = i;
+                        break;
+                    }
+            const keys = pending.slice(0, keep);
+            pending = pending.slice(keep);
+            return { keys, osc, answered };
+        },
+    };
+}
+const text = (chunk) => typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("latin1");
+/**
+ * Ask the terminal for its background (OSC 11, then DA1 as the end marker). Resolves to the theme,
+ * or null when the terminal said nothing usable within the timeout.
+ *
+ * Raw mode is on only while this function is the input's reader; the input's own mode and flow are
+ * restored after. Keys typed meanwhile go back to the input for its next reader, except Ctrl-C,
+ * which raw mode would otherwise swallow: it ends the query and is raised as an interrupt. After
+ * the timeout, a late reply is still taken out for LATE_MS. When something else starts reading in
+ * that time (the first prompt), the replies are taken out of the data it receives instead.
+ */
+export function queryBackground(input, output, timeoutMs = QUERY_TIMEOUT_MS, interrupt = () => process.kill(process.pid, "SIGINT")) {
+    if (input.isTTY !== true || typeof input.setRawMode !== "function")
+        return Promise.resolve(null);
+    const wasRaw = input.isRaw === true;
+    // A stream nobody reads yet (readableFlowing null) must not be left flowing: with no listener,
+    // a late byte or a handed-back key would be emitted to nobody. Readers resume it themselves.
+    const wasFlowing = input.readableFlowing === true;
+    const filter = replyFilter();
+    const ownEmit = input.emit;
+    return new Promise((resolve) => {
+        let typed = "";
+        let theme = null;
+        let settled = false;
+        let reading = true; // this function is the input's only reader
+        let done = false;
+        let timer;
+        const settle = () => {
+            if (!settled) {
+                settled = true;
+                resolve(theme);
+            }
+        };
+        /** Stop being the reader: listener off, mode and flow back, typed keys back, followed by any
+         *  held bytes in the order they came (the filter on the prompt's data holds them again). */
+        const stopReading = () => {
+            if (!reading)
+                return;
+            reading = false;
+            input.off("data", onData);
+            input.off("newListener", onReader);
+            try {
+                input.setRawMode(wasRaw);
+            }
+            finally {
+                if (!wasFlowing)
+                    input.pause?.();
+                const back = typed + filter.release();
+                if (back && input.unshift)
+                    input.unshift(Buffer.from(back, "latin1"));
+                typed = "";
+            }
+        };
+        const end = () => {
+            if (done)
+                return;
+            done = true;
+            if (timer)
+                clearTimeout(timer);
+            // A lone Esc still held at the end was a key, not the start of a reply that never came.
+            const esc = filter.release() === "\u001b";
+            const wasReading = reading;
+            if (esc && wasReading)
+                typed += "\u001b";
+            stopReading();
+            input.emit = ownEmit;
+            if (esc && !wasReading)
+                input.unshift?.(Buffer.from("\u001b"));
+            settle();
+        };
+        const onData = (chunk) => {
+            const { keys, osc, answered } = filter.take(text(chunk));
+            if (osc && !settled)
+                theme = osc;
+            typed += keys;
+            if (typed.includes("\u0003")) {
+                typed = typed.replaceAll("\u0003", "");
+                end();
+                interrupt();
+            }
+            else if (answered)
+                end();
+        };
+        // A prompt starting to read during the late wait: hand it the input, and take the replies out
+        // of the data it is given until the wait ends.
+        const onReader = (event) => {
+            if (event !== "data" && event !== "keypress" && event !== "readable")
+                return;
+            input.emit = function (event, ...args) {
+                if (event !== "data")
+                    return ownEmit.call(input, event, ...args);
+                const { keys, answered } = filter.take(text(args[0]));
+                if (answered)
+                    end();
+                if (!keys)
+                    return true;
+                return ownEmit.call(input, "data", typeof args[0] === "string" ? keys : Buffer.from(keys, "latin1"));
+            };
+            stopReading();
+        };
+        input.on("data", onData);
+        try {
+            input.setRawMode(true);
+            output.write("\u001b]11;?\u0007\u001b[c");
+        }
+        catch {
+            end();
+            return;
+        }
+        if (done)
+            return;
+        input.on("newListener", onReader);
+        timer = setTimeout(() => {
+            settle();
+            timer = setTimeout(end, LATE_MS);
+        }, timeoutMs);
+    });
+}
+/**
+ * The background, in order: CATALYST_THEME, COLORFGBG, the terminal's own answer (only when
+ * `ask` holds), then dark.
+ */
+export async function detectTheme(env, ask, timeoutMs = QUERY_TIMEOUT_MS) {
+    const known = envTheme(env);
+    if (known)
+        return known;
+    if (!ask)
+        return "dark";
+    return (await queryBackground(ask.input, ask.output, timeoutMs)) ?? "dark";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.15.2",
+  "version": "0.15.4",
   "description": "Set up Catalyst Cloud, check your tickets and manage your account from the command line.",
   "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:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.2 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.4 — 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.2 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.4 — 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.2 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.4 — written in this repository for customer accounts -->
 
 # Onboard me
 
@@ -14,9 +14,9 @@ Guide setup through the same `catalyst onboard` flow that the installer runs. Th
 
 1. Run `catalyst capabilities --json`. If its `onboard` entry is available and advertises `bootstrapHandoff: true`, use this path. If absent, use the older step-by-step references below and name the CLI update needed for the continuous flow.
 2. For a requested setup, run `catalyst onboard`. To inspect first, run `catalyst onboard --dry-run --json`. Resume with `catalyst onboard`; the command rechecks saved results. Do not ask the person to confirm completed browser steps or add a separate approval before the command's plan question.
-3. In a terminal, the command shows the verified person, workspace and plan before approval. Without terminal input, or with `--json`, use `--yes` only when the person has accepted the displayed defaults; otherwise setup waits with exit 11 and keeps the saved connection and receipt. JSON keeps progress, identity, the plan and quota disclosure on stderr and returns one result on stdout. A supplied key needs `catalyst login` before onboarding; browser sign-in does not replace it.
+3. In a terminal, the command shows the verified person, workspace and plan before approval. Without terminal input, or with `--json`, use `--yes` only when the person has accepted the displayed defaults; otherwise setup waits with exit 11 and keeps the saved connection and receipt. JSON keeps progress, identity and the plan on stderr and returns one result on stdout. A supplied key needs `catalyst login` before onboarding; browser sign-in does not replace it.
 4. For the current onboarding checks, run `catalyst ready --onboarding --json`. A failed check needs attention. An unknown check needs evidence. Report observed project work separately from incomplete setup; an unknown setup check does not prove work stopped.
-5. Exit 0 completes the requested scope. For a full run, exit 0 means work can start. If the receipt's `complete` is false, repository settings, local values, the daily update or the first ticket are still open, and the command lists them under "Next, when you want". Exit 10 means a failed step, 11 means waiting, and 12 means a guard refused the action. A successful `--only` step does not mean onboarding is complete. Keep the command's safe fix and supported resume command in your reply.
+5. Exit 0 completes the requested scope. For a full run, exit 0 means work can start. If the receipt's `complete` is false, a repository value or the first ticket is still open, and the command lists it under "Next, when you want". The daily update never keeps `complete` false, and neither do repository settings this computer cannot review (no checkout here, or not yet approved); a settings review that timed out or could not keep its draft does. Only a person at a terminal picks the first ticket; `--yes`, `--json` and headless runs leave it waiting with an action. Exit 10 means a failed step, 11 means waiting, and 12 means a guard refused the action. A successful `--only` step does not mean onboarding is complete. Keep the command's safe fix and supported resume command in your reply.
 
 Use cloud reads for ordinary workstation setup checks. Offer local sync for local SQL or sustained local reads inside the plan review. Local sync does not promise offline browsing. It is optional; do not make an absent replica a setup failure. Browser approval belongs to the person. Missing bearer capabilities stay unfinished; never call a session-only route from the CLI or invent a command.
 

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

@@ -1,25 +1,19 @@
-# Replacing a coding account's credential
+# 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.
 
-## Codex
+## The steps
 
-The person runs these steps on their own machine:
+For an API key, billed per token by its provider:
 
-1. Run `codex login` and choose "Sign in with ChatGPT".
-2. The login writes `~/.codex/auth.json`, or `$CODEX_HOME/auth.json` when `CODEX_HOME` is set. On macOS, `pbcopy < ~/.codex/auth.json` copies it.
-3. In the browser, open Settings → AI accounts, then that Codex account.
-4. Paste the file into "Replacement auth.json contents", then press Replace credential.
+1. The person creates a new key in the provider's console, under the same provider account the AI account was made from.
+2. In the browser, they open Settings → AI accounts, then that account.
+3. They paste the new key into the replacement field and press Replace credential.
+4. Once the account reads healthy, they can revoke the old key in the provider's console if nothing else uses it.
 
-Say plainly that Catalyst takes over this login: its refresh token is single-use, so the local copy stops working once Catalyst uses it, and to use Codex locally they sign in to Codex again, separately, after the replacement.
+If the account's page asks for something other than a key, follow the steps the page shows. When the page names the login the account belongs to, the new credential must come from that same login: one from another login would put a live account onto the wrong record. If a tool on the person's machine mints the credential, have them confirm it is signed in to the login the page names before minting; such tools mint for whoever is signed in, not for the account. When the page says Catalyst takes over the login, say so before the paste, and that the person signs in again locally afterwards.
 
-## Claude
-
-The field is "Replacement setup token". `claude setup-token` mints a token for whichever account the terminal is logged into, not for the slot, so match them first: compare the slot's email on the AI accounts page with what `/status` in `claude` shows, and log in to the slot's account if they differ. Then run `claude setup-token`, paste the token, and press Replace credential.
-
-## Any other provider
-
-The same page, with the credential it asks for. A cancelled or ended account is not a credential problem, and no token revives it.
+A cancelled or ended account is not a credential problem, and no new credential revives it.
 
 ## Afterwards
 

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

@@ -4,20 +4,13 @@ A phase needs the `coding accounts` and `host` parts of `node scripts/where-am-i
 
 ## Coding accounts
 
-One coding account is enough to start. A second, on another provider or plan, gives the router somewhere to go at a limit; offer it later.
+One coding account is enough to start. A second gives the router somewhere to go at a limit; offer it later.
 
 ### The kinds, and enrolling
 
-| they say | kind | the page asks for |
-| -- | -- | -- |
-| "Claude Pro or Max", "I use Claude Code" | Claude setup token | what `claude setup-token` prints, after `/status` in `claude` shows the account they mean |
-| "ChatGPT", "Codex" | Codex auth file | `~/.codex/auth.json` after `codex login` (steps in `references/replacing-a-credential.md`) |
-| "a GLM key", "Z.ai" | GLM API key | the key from the provider's console |
-| "a Qwen key", "Alibaba Model Studio" | Qwen API key | the key from the provider's console |
-
-A plain Anthropic or OpenAI API key cannot be enrolled; say so and ask whether they have one of these. Before a Codex paste, say Catalyst takes over that login: its refresh token is single-use, so they sign in to Codex again locally afterwards.
+Settings → AI accounts lists the providers this workspace can connect and what each one asks for; an API key is billed per token by its provider. Do not promise a provider. Ask the person to open Settings → AI accounts and choose from the providers it lists; if the one they name is not there, say so and ask whether they have a key from one that is.
 
-Enrolling is a browser step by construction: on Settings → AI accounts, an owner or admin picks the provider, labels the account, and pastes the credential into a write-only field. Call an account by its label, else its email, else its slot (`displayName` in `catalyst accounts --json`).
+Enrolling is a browser step by construction: on Settings → AI accounts, an owner or admin picks the provider, labels the account, and pastes the key into a write-only field. If the page says Catalyst takes over a login, say so before the paste. Call an account by its label, else its email, else its slot (`displayName` in `catalyst accounts --json`).
 
 ### The states
 
@@ -30,7 +23,7 @@ Enrolling is a browser step by construction: on Settings → AI accounts, an own
 | `inactive` | every account is out of rotation | reactivate one on its page, never enrol another |
 | `unread` | the cloud could not read them | it is not "no accounts"; read again later |
 
-**A cancelled or ended account** stays for reporting, unused, and does not hold setup up; say so in one clause. It keeps its own login: a token from another login would put a live account onto a dead slot. It stays enrolled rather than retired or deleted, and a returning subscription reactivates it on its page.
+**A cancelled or ended account** stays for reporting, unused, and does not hold setup up; say so in one clause. It keeps its own login: a token from another login would put a live account onto a dead slot. It stays enrolled rather than retired or deleted, and is reactivated on its page only if it can run again.
 
 ## Host
 

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

@@ -753,7 +753,7 @@ if (!connected) {
         retirable.length === 0
           ? []
           : [
-              `${retirable.length} account(s) cancelled or ended (${retirable.map((a) => `${who(a) ?? a.displayName ?? a.accountSlot ?? "?"} (${a.provider ?? "unknown provider"})`).join(", ")}): kept for reporting, not used, and not counted here. Never replace their credential; reactivate one on the AI accounts page only if its subscription is live again.`,
+              `${retirable.length} account(s) cancelled or ended (${retirable.map((a) => `${who(a) ?? a.displayName ?? a.accountSlot ?? "?"} (${a.provider ?? "unknown provider"})`).join(", ")}): kept for reporting, not used, and not counted here. Never replace their credential; reactivate one on the AI accounts page only if it can run again.`,
             ];
       retireNote = retireLine[0] ?? null;
       if (rows === null) {

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

@@ -4,7 +4,7 @@ description: >-
   Own one Catalyst Cloud project end to end until it closes. Use when the person says "run this project for me", "own this until it ships", "keep this moving", or hands you a project id or a set of tickets to drive. Subscribes to the account's event stream for the scope through the catalyst CLI, reacts to each change in the same turn, makes tickets ready and moves them to dispatch, parks what should stop, chases stalls, escalates inward, and keeps one status summary current. Writes to Linear as the app actor; never polls.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.2 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.4 — written in this repository for customer accounts -->
 
 # Run this project
 
@@ -15,7 +15,7 @@ You are the steward: the single-threaded owner of ONE project or ticket set unti
 Scripts are run, never read. Each prints `--help`, and exits 2 when this machine is not connected (`catalyst login`), 1 when its own check fails.
 
 1. `node scripts/scope-status.mjs --project <id>` (or `--team <key>`): tickets by stage, what is running and queued in scope, and stalls against the local policy. Run it to take the scope, and again after a resync.
-2. `node scripts/watch-scope.mjs --project <id>`: the subscription. In Claude Code, arm a monitor on it and react to each printed line in the same turn; elsewhere add `--exec <command>` so a reaction runs per frame.
+2. `node scripts/watch-scope.mjs --project <id>`: the live watch. In Claude Code, arm a monitor on it and react to each printed line in the same turn; elsewhere add `--exec <command>` so a reaction runs per frame.
 3. `node scripts/make-ready.mjs <ticket>` dispatches; `--park` stops; `--note <why>` records it.
 4. `catalyst explain <ticket>` whenever a ticket is not moving.
 

package/skills/unstick/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Get a stuck Catalyst Cloud ticket moving again. Use when the person asks "why is this parked and can you release it?", "unpark this", "get things flowing again", "the outage is over, retry what failed", or hands you a ticket that is not moving. Reads why nothing runs and what holds the ticket through the catalyst CLI, decides whether the recorded cause is fixed, previews the release, releases every governor holding the ticket the right way (or one failure class across a team), and raises an ask only for what a person has to do. Never releases a cause it cannot show changed without saying so.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.2 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.4 — written in this repository for customer accounts -->
 
 # Unstick
 

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

@@ -4,7 +4,7 @@ description: >-
   The human's decision inbox on Catalyst Cloud, and the one way an agent raises a decision on their behalf. Use when the person asks "what needs me?", "what am I blocking?", or when active work is gated on a choice only they can make. Lists open asks ranked by how much open work each one holds, files an ask through the cloud's ask route with the account's own template, and records the answer so the held work releases. Never answers as the human, never duplicates an open ask.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.2 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.4 — written in this repository for customer accounts -->
 
 # What needs me
 

package/skills/what-this-repo-needs/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   What environment variable names does this repository need, and where does each one come from? Scans the repository offline (no login, no network) and lists the names in three groups (build/test, deploy-only, bindings), each with where it was found, what uses it, and where a local value would come from. Never reads a value or prints one. Also checks the environment variable table in `.catalyst/catalyst.toml` offline. Use when someone asks "what does catalyst.env.json mean", "what env vars does this repo need", "why does the container need this", or before reviewing or writing the declaration.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.2 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.4 — written in this repository for customer accounts -->
 
 # What this repository needs