@catalyst-cloud/cli 0.15.3 → 0.15.4

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.15.4
+
+- Setup shows a colour mark and clearer progress, with a plain display when your terminal needs it.
+- Setup separates your next steps from tasks waiting on an owner or admin, and reports when it stops waiting for an account connection.
+- Setup wraps long text by words and keeps numbered steps in order.
+
 ## 0.15.3
 
 - Setup can finish once the steps needed to run work are ready. It lists optional next steps and keeps your first-ticket choice when you resume.

package/README.md

@@ -133,6 +133,8 @@ catalyst onboard
 catalyst ready --onboarding --json
 ```
 
+`catalyst setup` opens with the Catalyst Cloud mark in your terminal's colours. It asks the terminal whether its background is light or dark; set `CATALYST_THEME=light` or `CATALYST_THEME=dark` when it guesses wrong. `--no-color` or `NO_COLOR` prints plain text without the mark.
+
 The dry run writes no files. `--only <step>` runs one step and reports its scope separately from full onboarding. Exit 10 means a failed step, 11 means waiting, and 12 means a guard refused the action. The private receipt is `install/last-run.json` under your machine's Catalyst state directory; credentials stay in the login config. A fake HOME reports old services and keeps them intact.
 
 ### Headless setup (CI, image builds, agent VMs)

package/dist/args.js

@@ -64,6 +64,10 @@ export const FLAG_TABLES = {
             value: false,
             help: "do not run Catalyst's work on this machine, and do not ask",
         },
+        "no-color": {
+            value: false,
+            help: "print setup in plain text, without colour or the Catalyst Cloud mark",
+        },
         "resume-from": {
             value: true,
             help: "resume at a verified onboarding step",
@@ -459,7 +463,7 @@ export const FLAG_TABLES = {
 export const VERB_USAGE = {
     setup: "setup [onboard options]   (sets up Catalyst step by step; same as catalyst onboard) | setup --engine <file> --engine-sha256 <hex> [-- <install options>]   (run by install.sh; install.sh --help lists the options)",
     login: "login [--base-url <url>] [--start-replica]   (keyless; or --key <personal-key> / CATALYST_CLOUD_TOKEN)",
-    onboard: "onboard [--team <ID|key>] [--repo <owner/name>]... [--coding-account <slot>] [--resume-from <step>] [--only <step>] [--local-sync] [--runner|--no-runner] [--yes] [--dry-run] [--json] | onboard --headless [--key-file <path>] [--team ...] [--repo ...]... [--coding-account ...] [--runner yes|no] [--json]",
+    onboard: "onboard [--team <ID|key>] [--repo <owner/name>]... [--coding-account <slot>] [--resume-from <step>] [--only <step>] [--local-sync] [--runner|--no-runner] [--no-color] [--yes] [--dry-run] [--json] | onboard --headless [--key-file <path>] [--team ...] [--repo ...]... [--coding-account ...] [--runner yes|no] [--json]",
     install: "install [--skills-dir <dir>] [--force]",
     status: "status",
     notice: "notice",

package/dist/cli.js

@@ -1,6 +1,6 @@
 // cli.ts — the `catalyst` dispatcher (npm: @catalyst-cloud/cli). Verbs live in
 // their own modules; this file keeps every export the 0.1 tests and the bin import.
-import { createSetupRenderer } from "./setup-render.js";
+import { createSetupRenderer, setupBanner, } from "./setup-render.js";
 import { existsSync, openSync, closeSync } from "node:fs";
 import { ReadStream as TerminalInput } from "node:tty";
 import { Writable } from "node:stream";
@@ -210,6 +210,7 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
     // CTC-4625: setup passes the install options through to its engine untouched, so they never meet
     // this CLI's own flag tables. CTC-4680: without --engine, `setup` is the name a person types for
     // the onboard flow, so it runs exactly that.
+    const viaSetup = drawsMark(argv);
     if (argv[0] === "setup") {
         const rest = argv.slice(1);
         const own = rest.indexOf("--") === -1 ? rest : rest.slice(0, rest.indexOf("--"));
@@ -278,6 +279,9 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                 // Headless runs drop the terminal UI, browser sign-in and every browser action (CTC-4633).
                 const runOnboard = async (args, ctx, headless) => {
                     let ui = headless ? undefined : deps.setupUi;
+                    // --no-color reaches the renderer as NO_COLOR, so the banner and every step row go plain.
+                    const noColor = args.flags["no-color"] === true;
+                    const rendererEnv = noColor ? { ...ctx.env, NO_COLOR: "1" } : ctx.env;
                     let terminal;
                     let input = process.stdin;
                     const originalRaw = Boolean(input.isRaw);
@@ -300,10 +304,18 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                         }
                         if (input.isTTY) {
                             try {
+                                const banner = await setupBanner({
+                                    setup: viaSetup,
+                                    env: rendererEnv,
+                                    input,
+                                    stdout: process.stdout,
+                                    stream: bannerStream(ctx),
+                                    noColor,
+                                });
                                 ui = createClackOnboardUi(await import("@clack/prompts"), { input, output: process.stdout }, {
                                     baseUrl: () => savedOnboardBaseUrl(ctx.home),
                                     verbose: args.flags.verbose === true,
-                                    renderer: createSetupRenderer(process.stdout, ctx.env),
+                                    renderer: createSetupRenderer(process.stdout, rendererEnv, banner),
                                     disposeRenderer: true,
                                     signinTimeoutMs: deps.onboardSigninTimeoutMs,
                                     version: manifest.version,
@@ -326,7 +338,14 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                             });
                         ui = createClackOnboardUi(await import("@clack/prompts"), { input: process.stdin, output }, {
                             baseUrl: () => savedOnboardBaseUrl(ctx.home),
-                            renderer: createSetupRenderer(output, ctx.env),
+                            renderer: createSetupRenderer(output, rendererEnv, await setupBanner({
+                                setup: viaSetup,
+                                env: rendererEnv,
+                                input: process.stdin,
+                                stdout: process.stdout,
+                                stream: bannerStream(ctx),
+                                noColor,
+                            })),
                             disposeRenderer: true,
                             signinTimeoutMs: deps.onboardSigninTimeoutMs,
                             version: manifest.version,
@@ -560,6 +579,23 @@ const VERB_HELP_KNOWN = Object.fromEntries([
     "legacy",
     "onboard",
 ].map((v) => [v, true]));
+/** CTC-4680: the Pixel Nucleus mark belongs to `catalyst setup` alone. `setup` runs the onboard
+ *  flow, so this is read from the verb typed, before setup becomes onboard. */
+export function drawsMark(argv) {
+    return argv[0] === "setup";
+}
+/** CTC-4680: the banner goes to stderr, through ctx when stderr is not a terminal. */
+function bannerStream(ctx) {
+    if (process.stderr.isTTY === true)
+        return process.stderr;
+    return {
+        write(chunk) {
+            for (const line of chunk.replace(/\n$/, "").split("\n"))
+                ctx.stderr(line);
+            return true;
+        },
+    };
+}
 /** CTC-4625: `catalyst setup`, wired to this terminal, @clack/prompts and the keyless login. */
 async function runSetup(argv, ctx, deps) {
     if (argv[0] === "--help" || argv[0] === "-h") {

package/dist/onboard-checklist.js

@@ -235,8 +235,9 @@ export function connectChecklistAdapter(options) {
             // The contract advertised the route for this read; the wait's polls read the checklist alone.
             const origin = new URL(url).origin;
             let instruction;
-            if (options.page.openedBy === null ||
-                options.page.openedBy === options.step) {
+            // One tab per run: a second wait (Keep waiting, or another step) points at the page already
+            // open, and the wait still shows its address.
+            if (options.page.openedBy === null) {
                 try {
                     await options.openBrowser(url, signal);
                     options.page.openedBy = options.step;

package/dist/onboard-ui.js

@@ -1,12 +1,13 @@
 import { COMPUTER_CHECKS, standalonePlan, standalonePlanNotes, pendingContinuation, } from "./onboard-standalone-copy.js";
 import { trackedPrompt } from "./setup-prompt-frame.js";
 import { createOnboardInterrupts } from "./onboard-interrupts.js";
-import { setupStepView, CONNECTION_REPAIR_REASONS, setupFinalScreen, setupBrowserInstruction, setupCommandWords as say, setupPartHeading, setupPartProgress, setupTrackerRows, SETUP_PART_NUMBERS, SETUP_PART_OF, SETUP_PARTS, } from "./setup-onboard-copy.js";
+import { setupStepView, CONNECTION_REPAIR_REASONS, setupFinalScreen, setupBrowserInstruction, setupCommandWords as say, setupWaitsOnAdmin, TIMED_OUT_REASONS, setupPartHeading, setupPartProgress, setupTrackerRows, SETUP_PART_NUMBERS, SETUP_PART_OF, SETUP_PARTS, } from "./setup-onboard-copy.js";
 import { createOnboardProgress, } from "./onboard-progress.js";
 import { CREATE_TEAM_CHOICE, suggestTeamKey, teamKeyProblem, teamNameProblem, } from "./onboard-team-create.js";
 import { FIRST_TICKET_SAMPLE, FIRST_TICKET_SKIP, } from "./onboard-first-ticket.js";
-import { ONBOARD_STEPS, ONBOARD_TITLES, stepSatisfied, onboardIdentityLines, onboardNextActions, onboardReadyForWork, onboardStepAction, } from "./onboard.js";
+import { ONBOARD_STEPS, ONBOARD_TITLES, stepSatisfied, onboardHeaderIdentity, onboardIdentityLines, onboardNextActions, onboardReadyForWork, onboardStepAction, } from "./onboard.js";
 import { onboardStepDetail, onboardReasonText } from "./onboard-next.js";
+import { CONNECT_PAGE_PATH } from "./onboard-checklist.js";
 export function shouldUseOnboardUi(args, stdoutTty) {
     return (stdoutTty &&
         !args.json &&
@@ -43,6 +44,11 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
     let planned = {};
     let rechecking = false;
     let shownPlan;
+    // CTC-4680: steps whose wait was on the Connect accounts page. That page does not expire, so a
+    // wait that ran out is setup giving up, and the way back is the same page.
+    const connectWaits = new Map();
+    const onConnectPage = (step) => connectWaits.has(step.id) && TIMED_OUT_REASONS.has(step.reason ?? "");
+    const outcome = (step, view) => onConnectPage(step) ? "setup stopped waiting" : view.outcome;
     let browserOpened = true;
     let questionOpen = false;
     let signinShown = false;
@@ -98,11 +104,15 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             renderer.heading(setupPartHeading(next, renderer.traits.unicode));
             return;
         }
-        const progress = setupPartProgress(journalSeen, planned.scope);
-        const left = progress[previous].total - progress[previous].done;
-        renderer.heading(left
-            ? `Part ${previous} has ${left === 1 ? "1 step" : `${left} steps`} left. Setup carries on with part ${next}.`
-            : `Part ${previous} done. ${SETUP_PARTS[previous].done}`);
+        const progress = setupPartProgress(journalSeen, planned.scope, "run");
+        const got = progress[previous];
+        const left = got.total - got.done;
+        // Mid-run nothing yet says whether an owner or admin has done their part, so this is neutral.
+        renderer.heading(!left
+            ? `Part ${previous} done. ${SETUP_PARTS[previous].done}`
+            : left === got.admin + got.aside
+                ? `The rest of part ${previous} is for an owner or admin of your Catalyst workspace.`
+                : `Part ${previous} has ${left === 1 ? "1 step" : `${left} steps`} left. Setup carries on with part ${next}.`);
         renderer.tracker(setupTrackerRows(progress, { next }));
         planPart(renderer, next, journalSeen);
         renderer.blank();
@@ -221,10 +231,54 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
         return result.answer;
     };
     let summaryShown = false;
-    const summary = (journal) => {
+    /**
+     * The end screen's actions, split by who acts: the person's own, and an owner's or admin's
+     * (CTC-4680). A step paused with Ctrl-C is not an action: the last line says how to carry on.
+     */
+    const sortActions = (journal) => {
         const screen = setupFinalScreen(journal, deps.baseUrl?.(), abort.signal.aborted);
+        const step = (id) => journal.steps.find((s) => s.id === id) ?? { id, state: "pending" };
+        const text = (action) => {
+            const row = step(action.id);
+            if (!onConnectPage(row))
+                return say(action.text);
+            const kinds = row.evidence?.aiAccountKinds;
+            // #277's rule: subscription wording only for a workspace the cloud enables for it.
+            const what = action.id === "accounts"
+                ? typeof kinds === "string" && kinds.split(",").includes("subscription")
+                    ? "add an API key or connect a subscription"
+                    : "add an API key"
+                : action.id === "github.install"
+                    ? "install Catalyst on GitHub"
+                    : `finish "${title(action.id)}" there`;
+            return `Open ${connectWaits.get(action.id)} and ${what}.`;
+        };
+        const live = screen.actions.filter((action) => step(action.id).reason !== "interrupted");
+        const theirs = live.filter((action) => setupWaitsOnAdmin(step(action.id), journal));
+        const mine = live.filter((action) => !theirs.includes(action));
+        // Steps only an owner or admin can do, less any already listed as their task above.
+        const skipped = journal.steps.filter((s) => s.reason === "member_scope" &&
+            setupWaitsOnAdmin(s, journal) &&
+            SETUP_PART_NUMBERS[s.id] !== undefined &&
+            s.id !== "projects" &&
+            !theirs.some((action) => action.id === s.id));
+        const waiting = theirs.length > 0 || skipped.length > 0;
+        const own = mine.length;
+        const next = screen.paused ||
+            !/^Next: run catalyst onboard after you finish/.test(screen.next)
+            ? say(screen.next)
+            : own
+                ? `Next: run catalyst setup after you finish ${own === 1 ? "1" : own === 2 ? "1 and 2" : `1 to ${own}`}.`
+                : waiting
+                    ? "Next: run catalyst setup once they have."
+                    : "Next: run catalyst setup to check again.";
+        return { screen, mine, theirs, skipped, waiting, next, text, live };
+    };
+    const summary = (journal) => {
+        const sorted = sortActions(journal);
+        const { screen, mine, theirs, skipped } = sorted;
         if (!renderer)
-            return screen;
+            return sorted;
         renderer.suspendLive();
         active = false;
         renderer.heading(screen.heading);
@@ -233,12 +287,34 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
         renderer.tracker(setupTrackerRows(setupPartProgress(journal, planned.scope), "end"));
         if (screen.readinessCause)
             renderer.line(say(screen.readinessCause));
-        if (screen.actions.length) {
-            renderer.line(`${screen.actions.length} ${screen.actions.length === 1 ? "thing needs" : "things need"} you:`);
-            screen.actions.forEach((action, i) => renderer.item(`${i + 1}. `, say(action.text)));
+        if (mine.length) {
+            renderer.line(`${mine.length} ${mine.length === 1 ? "thing needs" : "things need"} you:`);
+            mine.forEach((action, i) => renderer.item(`${i + 1}. `, sorted.text(action)));
             if (screen.more)
                 renderer.line(`and ${screen.more} more after these`);
-            const continuation = pendingContinuation(journal, new Set(screen.actions.map((action) => action.id)));
+        }
+        if (sorted.waiting) {
+            renderer.line("Waiting on an owner or admin of your Catalyst workspace:");
+            for (const action of theirs)
+                renderer.item("· ", sorted.text(action));
+            if (skipped.length) {
+                renderer.item("· ", `Steps only they can do: ${skipped.map((s) => title(s.id)).join(", ")}.`);
+                const base = deps.baseUrl?.();
+                const integrations = base
+                    ? new URL("/settings/connections", base).href
+                    : undefined;
+                if (integrations && !theirs.some((a) => a.text.includes(integrations)))
+                    renderer.item("· ", `They start at ${integrations}, the Integrations page.`);
+            }
+        }
+        // A step skipped with Ctrl-C is no action, but it is still to come: the line below names it.
+        if (screen.actions.length || skipped.length) {
+            const continuation = pendingContinuation(journal, 
+            // A step paused with Ctrl-C is still to come, so it stays in this line.
+            new Set([
+                ...sorted.live.map((action) => action.id),
+                ...skipped.map((s) => s.id),
+            ]));
             if (continuation)
                 renderer.line(continuation);
         }
@@ -246,7 +322,7 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             renderer.line("Catalyst is ready to work on your team's tickets.");
         if (deps.logPath?.())
             renderer.line(`Full log: ${deps.logPath()}`);
-        return screen;
+        return sorted;
     };
     const ui = {
         signal: abort.signal,
@@ -264,14 +340,16 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             machineChecks.clear();
             machineBlocked = false;
             stop();
+            // Signed in already, the header carries who and where, so the lines below would repeat it.
+            let identityShown = false;
             if (!introduced) {
                 if (renderer)
-                    renderer.brand("setup", deps.version);
+                    identityShown = renderer.brand("setup", deps.version, identity ? onboardHeaderIdentity(identity) : undefined);
                 else
                     prompts.intro("Catalyst setup", { output: streams.output });
                 introduced = true;
             }
-            if (identity !== undefined)
+            if (identity !== undefined && !identityShown)
                 for (const line of onboardIdentityLines(identity))
                     if (renderer)
                         renderer.line(line);
@@ -586,25 +664,35 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
         async retryTimedOut(id) {
             if (abort.signal.aborted)
                 return false;
+            // The Connect accounts page does not expire: setup stopped waiting, and can wait again.
+            const page = connectWaits.has(id);
+            const why = page
+                ? "Setup stopped waiting for the Connect accounts page."
+                : "The link timed out.";
             if (renderer) {
                 // The question draws under this row, so the reason stays on screen while it is asked.
                 stop();
-                renderer.begin(number(id), title(id), "the link timed out", "ask");
+                renderer.begin(number(id), title(id), page ? "setup stopped waiting" : "the link timed out", "ask");
+                if (page)
+                    renderer.detail(why);
                 active = true;
                 questionOpen = true;
             }
             else {
                 stop();
-                prompts.log.message(`${title(id)}: the link timed out.`, {
+                prompts.log.message(`${title(id)}: ${why}`, {
                     output: streams.output,
                 });
             }
             const answer = await select({
                 ...options,
-                message: "Ready to try again?",
+                message: page ? "Keep waiting?" : "Ready to try again?",
                 initialValue: "again",
                 options: [
-                    { value: "again", label: "Yes, give me a new link" },
+                    {
+                        value: "again",
+                        label: page ? "Yes, keep waiting" : "Yes, give me a new link",
+                    },
                     { value: "stop", label: "Stop here. Run catalyst setup later to carry on." },
                 ],
             });
@@ -716,7 +804,7 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
                 }
                 if (step.id === "ready" || (hidden(step.id) && step.state !== "failed"))
                     return;
-                if ((step.id === "github.repos" || step.id === "settings") &&
+                if (step.id === "github.repos" &&
                     step.state === "done")
                     return;
                 if (step.id === "projects" &&
@@ -725,7 +813,7 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
                 const view = setupStepView(step, journal);
                 if (hidden(step.id))
                     enterPart(step.id);
-                renderer.step(view.mark, view.number, view.title, view.outcome);
+                renderer.step(view.mark, view.number, view.title, outcome(step, view));
                 const granted = deps.verbose ? onboardStepDetail(step) : undefined;
                 if (granted)
                     renderer.detail(granted);
@@ -772,7 +860,7 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             if (!renderer ||
                 !interactive ||
                 abort.signal.aborted ||
-                !setupFinalScreen(journal, deps.baseUrl?.()).actions.length)
+                !sortActions(journal).mine.length)
                 return false;
             active = false;
             summary(journal);
@@ -819,15 +907,14 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             }
             if (renderer) {
                 active = false;
-                const screen = summaryShown
-                    ? setupFinalScreen(journal, deps.baseUrl?.(), abort.signal.aborted)
-                    : summary(journal);
+                const sorted = summaryShown ? sortActions(journal) : summary(journal);
+                const { screen } = sorted;
                 if (summaryShown && screen.paused) {
                     renderer.heading(screen.heading);
                     renderer.line("Your progress is saved.");
                 }
                 summaryShown = false;
-                renderer.outro(say(screen.next));
+                renderer.outro(sorted.next);
                 return;
             }
             stop();
@@ -852,6 +939,19 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             prompts.outro(text, { output: streams.output });
         },
         async wait(text, run, page) {
+            if (currentStep && page) {
+                let path = "";
+                try {
+                    path = new URL(page.url).pathname;
+                }
+                catch {
+                    // Not a URL, so not the Connect accounts page.
+                }
+                if (path === CONNECT_PAGE_PATH)
+                    connectWaits.set(currentStep, page.url);
+                else
+                    connectWaits.delete(currentStep);
+            }
             const browser = currentStep && renderer && page
                 ? page
                 : currentStep &&

package/dist/onboard.js

@@ -45,16 +45,25 @@ function dailyUpdateChoice(value) {
         return { state: "skipped", reason: "no_scheduler" };
     return undefined;
 }
+const identityLabel = (text) => text
+    .replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, 180);
+/** CTC-4680: who and where for the lines beside setup's mark, "user: …" and "workspace: …". */
+export function onboardHeaderIdentity(identity) {
+    const display = identity.display;
+    return {
+        user: identityLabel(display?.email || display?.personLabel || identity.membershipId),
+        workspace: identityLabel(display?.workspaceName || identity.account),
+    };
+}
 export function onboardIdentityLines(identity) {
     if (!identity)
         return [
             "Use an existing Catalyst account or accept your invitation before approving sign-in.",
         ];
-    const label = (text) => text
-        .replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, " ")
-        .replace(/\s+/g, " ")
-        .trim()
-        .slice(0, 180);
+    const label = identityLabel;
     const display = identity.display;
     const person = label(display?.personLabel || identity.membershipId);
     const email = display?.email ? label(display.email) : "";

package/dist/setup-brand.js

@@ -0,0 +1,202 @@
+/** Ring order runs from the top tip, round the back, to the bottom tip, as in the brand script. */
+export const RING = [
+    [3, 0],
+    [2, 0],
+    [1, 0],
+    [0, 1],
+    [0, 2],
+    [1, 3],
+    [2, 3],
+    [3, 3],
+];
+export const CORE = [
+    [1, 1],
+    [2, 1],
+    [1, 2],
+    [2, 2],
+];
+export const MARK_SIZE = { dot: 3, gap: 1 };
+export const markSpan = (size = MARK_SIZE) => 4 * size.dot + 3 * size.gap;
+export const markLines = (size = MARK_SIZE) => Math.ceil(markSpan(size) / 2);
+const paintOf = (col, row) => RING.some(([c, r]) => c === col && r === row)
+    ? "ring"
+    : CORE.some(([c, r]) => c === col && r === row)
+        ? "core"
+        : null;
+/** The mark as a grid of square units, `markSpan` rows of half lines by `markSpan` columns. */
+export function markUnits(size = MARK_SIZE) {
+    const span = markSpan(size);
+    const pitch = size.dot + size.gap;
+    return Array.from({ length: span }, (_, y) => Array.from({ length: span }, (_, x) => x % pitch >= size.dot || y % pitch >= size.dot
+        ? null
+        : paintOf(Math.floor(x / pitch), Math.floor(y / pitch))));
+}
+const BRAND = {
+    ink: "#11100e",
+    cream: "#f1ebe2",
+    copper: "#d28e63",
+    rust: "#a9512f",
+};
+/** The brand rules: a cream C and copper core on dark, an ink C and rust core on light. */
+const PALETTES = {
+    dark: { ring: BRAND.cream, core: BRAND.copper },
+    light: { ring: BRAND.ink, core: BRAND.rust },
+};
+export function colourLevel(env, terminal) {
+    if (terminal.noColor)
+        return "none";
+    const force = env.FORCE_COLOR;
+    if (force !== undefined) {
+        if (force === "0" || force === "false")
+            return "none";
+        if (force === "" || force === "1" || force === "true")
+            return "16";
+        if (force === "2")
+            return "256";
+        if (force === "3")
+            return "truecolor";
+    }
+    if (env.NO_COLOR !== undefined || !terminal.tty)
+        return "none";
+    if (!env.TERM || env.TERM === "dumb")
+        return "none";
+    if (/^(truecolor|24bit)$/i.test(env.COLORTERM ?? ""))
+        return "truecolor";
+    return /256/.test(env.TERM) ? "256" : "16";
+}
+/** CI as most tools read it: set, and not "", "0" or "false". */
+export function inCi(env) {
+    return ![undefined, "", "0", "false"].includes(env.CI);
+}
+export const MARK_MIN_COLUMNS = 60;
+/**
+ * Why the mark is left off, or null to draw it. Off for every verb but setup, without a terminal,
+ * in CI, with --no-color or NO_COLOR or no colour at all, without UTF-8 (the blocks are UTF-8), and
+ * below 60 columns. The text lines are printed either way.
+ */
+export function markSkipped(options) {
+    const { env } = options;
+    if (!options.setup)
+        return "not catalyst setup";
+    if (!options.tty)
+        return "not a terminal";
+    if (inCi(env))
+        return "CI";
+    if (options.noColor)
+        return "--no-color";
+    if (env.NO_COLOR !== undefined)
+        return "NO_COLOR";
+    if (colourLevel(env, options) === "none")
+        return "no colour";
+    if (!/utf-?8/i.test(env.LC_ALL || env.LC_CTYPE || env.LANG || ""))
+        return "not UTF-8";
+    if (options.columns < MARK_MIN_COLUMNS)
+        return "narrow";
+    return null;
+}
+const rgb = (hex) => [
+    Number.parseInt(hex.slice(1, 3), 16),
+    Number.parseInt(hex.slice(3, 5), 16),
+    Number.parseInt(hex.slice(5, 7), 16),
+];
+const distance = (a, b) => (a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2 + (a[2] - b[2]) ** 2;
+/** The nearest xterm-256 colour: the 6×6×6 cube or the 24-step grey ramp, whichever is closer. */
+export function nearest256(hex) {
+    const colour = rgb(hex);
+    const levels = [0, 95, 135, 175, 215, 255];
+    const step = (v) => levels.reduce((best, l, i) => (Math.abs(l - v) < Math.abs(levels[best] - v) ? i : best), 0);
+    const [ri, gi, bi] = colour.map(step);
+    const avg = (colour[0] + colour[1] + colour[2]) / 3;
+    const greyIndex = Math.min(23, Math.max(0, Math.round((avg - 8) / 10)));
+    const grey = 8 + 10 * greyIndex;
+    return distance([levels[ri], levels[gi], levels[bi]], colour) <=
+        distance([grey, grey, grey], colour)
+        ? 16 + 36 * ri + 6 * gi + bi
+        : 232 + greyIndex;
+}
+/** xterm's default 16 colours, as SGR foreground codes. */
+const XTERM16 = [
+    [30, [0, 0, 0]],
+    [31, [205, 0, 0]],
+    [32, [0, 205, 0]],
+    [33, [205, 205, 0]],
+    [34, [0, 0, 238]],
+    [35, [205, 0, 205]],
+    [36, [0, 205, 205]],
+    [37, [229, 229, 229]],
+    [90, [127, 127, 127]],
+    [91, [255, 0, 0]],
+    [92, [0, 255, 0]],
+    [93, [255, 255, 0]],
+    [94, [92, 92, 255]],
+    [95, [255, 0, 255]],
+    [96, [0, 255, 255]],
+    [97, [255, 255, 255]],
+];
+/**
+ * The nearest of xterm's 16 default colours. Plain distance puts copper nearest grey (90), and the
+ * core is the mark's one accent, so the core picks from the coloured entries only: copper is then
+ * yellow (33) and rust red (31). The ring takes plain distance: cream is white (37), ink black (30).
+ */
+export function nearest16(hex, accent = false) {
+    const colour = rgb(hex);
+    const greys = [30, 37, 90, 97];
+    return XTERM16.filter(([code]) => !accent || !greys.includes(code)).reduce((best, entry) => distance(entry[1], colour) < distance(best[1], colour) ? entry : best)[0];
+}
+/**
+ * The SGR parameters for one of the mark's colours on a `theme` background, as a foreground or a
+ * background. With 16 colours the core is also bold, which most terminals draw brighter.
+ */
+export function markColour(paint, theme, level, layer = "fg") {
+    const hex = PALETTES[theme][paint];
+    const lead = layer === "fg" ? 38 : 48;
+    if (level === "truecolor")
+        return `${lead};2;${rgb(hex).join(";")}`;
+    if (level === "256")
+        return `${lead};5;${nearest256(hex)}`;
+    const code = nearest16(hex, paint === "core") + (layer === "fg" ? 0 : 10);
+    return paint === "core" && layer === "fg" ? `1;${code}` : String(code);
+}
+/**
+ * Units to terminal lines, two unit rows per line: both halves set is a full block (or an upper
+ * half block on the lower colour's background when they differ), one half is a half block, neither
+ * is a space. Each run of one glyph colour is closed with a reset.
+ */
+export function unitLines(units, theme, level) {
+    const lines = [];
+    for (let y = 0; y < units.length; y += 2) {
+        const upper = units[y];
+        const lower = units[y + 1] ?? [];
+        let out = "";
+        let open = "";
+        for (let x = 0; x < upper.length; x++) {
+            const [top, bottom] = [upper[x] ?? null, lower[x] ?? null];
+            const sgr = top && bottom && top !== bottom
+                ? `${markColour(top, theme, level)};${markColour(bottom, theme, level, "bg")}`
+                : top || bottom
+                    ? markColour((top ?? bottom), theme, level)
+                    : "";
+            if (sgr !== open) {
+                if (open)
+                    out += "\u001b[0m";
+                if (sgr)
+                    out += `\u001b[${sgr}m`;
+                open = sgr;
+            }
+            out +=
+                !top && !bottom
+                    ? " "
+                    : top && bottom && top === bottom
+                        ? "█"
+                        : top
+                            ? "▀"
+                            : "▄";
+        }
+        lines.push(open ? `${out}\u001b[0m` : out);
+    }
+    return lines;
+}
+/** The mark, one string per terminal line: `markLines` lines of `markSpan` columns. */
+export function pixelNucleusLines(theme, level, size = MARK_SIZE) {
+    return unitLines(markUnits(size), theme, level);
+}

package/dist/setup-onboard-copy.js

@@ -212,7 +212,9 @@ function unfinished(step) {
     if (step.reason === "runner_docker_missing")
         return "Docker is not running";
     if (step.reason === "member_scope")
-        return "an admin handles this step";
+        return step.id === "linear.team" || step.id === "values"
+            ? "run catalyst setup --team <KEY> to choose your team"
+            : "an admin handles this step";
     if (step.reason === "automation_management_unavailable")
         return "could not read them; checked again before work starts";
     if (step.reason === "interrupted" || step.reason === "first_ticket_skipped")
@@ -306,14 +308,62 @@ export function setupStepView(step, journal, required = false) {
         outcome,
     };
 }
+/** The signed-in person's Catalyst role, when the sign-in step recorded one. */
+function signedInRole(journal) {
+    const role = journal?.steps.find((s) => s.id === "signin" && s.state === "done")?.evidence?.role;
+    return typeof role === "string" ? role : undefined;
+}
+const notOwnerOrAdmin = (journal) => {
+    const role = signedInRole(journal);
+    return role !== undefined && role !== "owner" && role !== "admin";
+};
+/** The steps readiness says an owner or admin has left (`admin_setup_pending`), if it said so. */
+function readinessAdminSteps(journal) {
+    const ready = journal?.steps.find((s) => s.id === "ready");
+    const ids = ready?.evidence?.admin;
+    return ready?.reason === "admin_setup_pending" && typeof ids === "string"
+        ? new Set(ids.split(","))
+        : new Set();
+}
+/** A member's skip of their own team (or the values it gates): rerun with --team, nobody else. */
+const memberOwnSkip = (step) => step.reason === "member_scope" &&
+    (step.id === "linear.team" || step.id === "values");
+/**
+ * CTC-4680: a step only an owner or admin of the Catalyst workspace can finish, for the person
+ * running setup. A member's run skips every admin step whether or not the admin has done it, so a
+ * skip waits on an admin only when readiness names that step. Refusals for the person's role, a
+ * member's unverified runner or workflow, and a member's AI account or values do too.
+ */
+export function setupWaitsOnAdmin(step, journal) {
+    if (step.state === "done")
+        return false;
+    const reason = step.reason ?? "";
+    if (reason === "member_scope")
+        return !memberOwnSkip(step) && readinessAdminSteps(journal).has(step.id);
+    if (reason === "github_installation_admin_required")
+        return true;
+    if (reason === "runner_identity_unverified" ||
+        reason === "workflow_identity_unverified")
+        return notOwnerOrAdmin(journal);
+    // Only reasons an owner or admin clears. A probe that could not finish (a stale read, a login
+    // to refresh) is the person's own to check again.
+    if ((step.id === "accounts" &&
+        (reason === "account_enrollment_required" ||
+            reason === "ai_account_not_usable")) ||
+        (step.id === "values" && reason === "required_values_missing"))
+        return notOwnerOrAdmin(journal);
+    return false;
+}
 /** How far each part has got, by its numbered rows. A row is done when every step in it is done
- *  or skipped, and needs someone when any of its steps does. */
-export function setupPartProgress(journal, scope) {
-    const progress = {
-        1: { total: 0, done: 0, needs: 0, failed: 0 },
-        2: { total: 0, done: 0, needs: 0, failed: 0 },
-        3: { total: 0, done: 0, needs: 0, failed: 0 },
-    };
+ *  or skipped by choice, needs someone when any of its steps does, and waits on an owner or admin
+ *  when only they can finish it. */
+export function setupPartProgress(journal, scope, 
+/** "run" before readiness is known: a member's admin skips count aside, neither done nor owed.
+ *  At the end they count done only when readiness passed. */
+moment = "end") {
+    const empty = () => ({ total: 0, done: 0, needs: 0, failed: 0, admin: 0, aside: 0 });
+    const progress = { 1: empty(), 2: empty(), 3: empty() };
+    const readinessPassed = journal.steps.find((s) => s.id === "ready")?.state === "done";
     const rows = new Map();
     for (const id of ONBOARD_STEPS) {
         const number = SETUP_PART_NUMBERS[id];
@@ -324,18 +374,36 @@ export function setupPartProgress(journal, scope) {
             state: "pending",
         };
         const key = `${SETUP_PART_OF[id]}:${number}`;
-        rows.set(key, [...(rows.get(key) ?? []), setupStepView(step, journal).mark]);
+        rows.set(key, [
+            ...(rows.get(key) ?? []),
+            {
+                // A member's own skip (no --team) is theirs to finish, so it is never counted done.
+                mark: memberOwnSkip(step) ? "act" : setupStepView(step, journal).mark,
+                kind: setupWaitsOnAdmin(step, journal)
+                    ? "admin"
+                    : step.reason === "member_scope" &&
+                        !memberOwnSkip(step) &&
+                        (moment === "run" || !readinessPassed)
+                        ? "aside"
+                        : "own",
+            },
+        ]);
     }
-    for (const [key, marks] of rows) {
+    for (const [key, steps] of rows) {
         const part = progress[Number(key.split(":")[0])];
         part.total++;
-        if (marks.every((m) => m === "done" || m === "skip"))
+        const own = steps.filter((s) => s.kind === "own");
+        if (own.length === steps.length && own.every((s) => s.mark === "done" || s.mark === "skip"))
             part.done++;
-        else if (marks.some((m) => m === "act" || m === "fail")) {
+        else if (own.some((s) => s.mark === "act" || s.mark === "fail")) {
             part.needs++;
-            if (marks.includes("fail"))
+            if (own.some((s) => s.mark === "fail"))
                 part.failed++;
         }
+        else if (steps.some((s) => s.kind === "admin"))
+            part.admin++;
+        else if (steps.some((s) => s.kind === "aside"))
+            part.aside++;
     }
     return progress;
 }
@@ -345,6 +413,7 @@ export function setupPartProgress(journal, scope) {
  */
 export function setupTrackerRows(progress, moment) {
     const steps = (n) => `${n} ${n === 1 ? "step" : "steps"}`;
+    const waiting = (n) => `${steps(n)} ${n === 1 ? "waits" : "wait"} on an owner or admin`;
     return [1, 2, 3]
         .filter((p) => progress[p].total > 0)
         .map((p) => {
@@ -365,14 +434,21 @@ export function setupTrackerRows(progress, moment) {
                 return row("now", `next · ${estimate}`);
             if (p > moment.next)
                 return row("later", estimate);
-            return finished
-                ? row("done", "done")
-                : row(needsMark, `${steps(got.total - got.done)} not finished`);
+            if (finished)
+                return row("done", "done");
+            const theirs = got.admin + got.aside;
+            if (theirs && got.done + theirs === got.total)
+                return row("act", `${steps(theirs)} ${theirs === 1 ? "is" : "are"} for an owner or admin`);
+            return row(needsMark, `${steps(got.total - got.done)} not finished`);
         }
         if (finished)
             return row("done", "");
         if (got.needs)
             return row(needsMark, `${steps(got.needs)} ${got.needs === 1 ? "needs" : "need"} someone`);
+        if (got.admin)
+            return row("act", waiting(got.admin));
+        if (got.aside)
+            return row("act", `${steps(got.aside)} ${got.aside === 1 ? "is" : "are"} for an owner or admin`);
         return row("later", `${got.done} of ${steps(got.total)} done`);
     });
 }

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 || "");
@@ -72,33 +75,20 @@ const UNICODE_MARKS = {
     ask: ["◆", "cyan"],
     now: ["◆", "cyan"],
 };
-/** CTC-4680: the Pixel Nucleus core, copper on a dark terminal and rust on a light one
- *  (catalyst-cloud docs/brand-mark.md), with the nearest 256- and 16-colour background. */
-const CORE = {
-    dark: { rgb: "210;142;99", x256: 173, x16: 43 },
-    light: { rgb: "169;81;47", x256: 130, x16: 41 },
-};
 /**
- * The mark's 4×4 grid in two terminal lines, each cell 2 columns by half a line. The ring is a
- * glyph in the terminal's own foreground colour; the core is a background colour, so no
- * foreground is ever set and the C reads on light and dark terminals alike. The second line
- * reverses video so the core's half block takes the copper and its other half the ring.
+ * 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 function pixelNucleusLines(env) {
-    // COLORFGBG is "fg;bg" (rxvt, Konsole, iTerm2); 7 and 15 are the light backgrounds.
-    const light = ["7", "15"].includes((env.COLORFGBG ?? "").split(";").at(-1) ?? "");
-    const core = light ? CORE.light : CORE.dark;
-    const bg = /^(truecolor|24bit)$/i.test(env.COLORTERM ?? "")
-        ? `48;2;${core.rgb}`
-        : /256/.test(env.TERM ?? "")
-            ? `48;5;${core.x256}`
-            : String(core.x16);
-    return [
-        `▄▄\u001b[${bg}m▀▀▀▀\u001b[49m▀▀`,
-        `▀▀\u001b[7;${bg}m▀▀▀▀\u001b[27;49m▄▄`,
-    ];
+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) {
+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);
@@ -252,29 +242,64 @@ export function createSetupRenderer(stream, env) {
             refresh();
             ordinary([prefix(textCol) + style("bold", title)]);
         },
-        brand(program, version) {
+        brand(program, version, identity) {
             if (branded)
-                return;
+                return false;
             branded = true;
             refresh();
-            if (!traits.color || traits.columns < 50) {
-                ordinary([
-                    `${prefix(textCol)}Catalyst Cloud ${program}${version ? ` ${version}` : ""}`,
-                ]);
-                return;
+            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;
             }
-            const [one, two] = pixelNucleusLines(env);
-            ordinary([
-                `${prefix(textCol)}${one}  ${style("bold", "Catalyst Cloud")}`,
-                `${prefix(textCol)}${two}  ${style("dim", `${program}${version ? ` · ${version}` : ""}`)}`,
-            ]);
+            // 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(["", prefix(textCol) + 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));

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.3",
+  "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.3 — 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.3 — 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.3 — 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
 

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.3 — 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
 

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.3 — 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.3 — 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.3 — 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
 

package/skills/whats-happening/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Use for "what's happening?", "where are we?", "why is that stuck?", "what closed?", "what's next?", "how does this work?", "why did it do that?", "how does it prioritise?" and "what does this setting do, where is it set?" in Catalyst Cloud, or asks for something to be done rather than known. Reads the contract via catalyst CLI. Read-only: route work/decisions, never answer as the human.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.3 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.4 — written in this repository for customer accounts -->
 
 # What's happening