@catalyst-cloud/cli 0.14.10 → 0.15.0

package/dist/setup.js

@@ -0,0 +1,426 @@
+// setup.ts — CTC-4625: `catalyst setup`, what a person sees while Catalyst installs.
+//
+// install.sh is a small POSIX bootstrap: it checks for Node, npm, git and a coding agent, gets
+// this command, and runs `catalyst setup --engine <file> --engine-sha256 <digest> -- <its args>`.
+// The engine is the served install script's step bodies. It runs unchanged in behaviour, with
+// CATALYST_INSTALL_UI=events: it keeps the lock, the last-run.json receipt, resume, the flags and
+// the exit codes, and instead of drawing anything it reports on fd 4 (see setup-events.ts). This
+// command draws those reports, asks the questions, and runs the sign-in itself.
+//
+//   fd 3  the --json document, forwarded to stdout unchanged (one document)
+//   fd 4  the engine's events
+//   fd 5  this command's answers, one line per question or sign-in
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { constants, tmpdir } from "node:os";
+import { join } from "node:path";
+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";
+const MACHINE_TITLES = {
+    1: "Install the catalyst command",
+    2: "Add the Catalyst skills",
+    3: "Set up folders",
+    4: "Sign in to Catalyst",
+    5: "Local sync",
+    6: "Schedule the daily update",
+};
+const EXIT_STOPPED = 10;
+/** How long the engine's pipes may take to drain after it exits. */
+const PIPE_DRAIN_MS = 2000;
+/** Flags the engine reads a value after, so a value is never mistaken for --json or --yes. */
+const VALUED = new Set([
+    "--scope",
+    "--prefix",
+    "--repo-root",
+    "--worktrees-root",
+    "--thoughts-repo",
+    "--housekeeping",
+    "--login-timeout",
+    "--replica-db",
+    "--profile",
+]);
+export const SETUP_USAGE = VERB_USAGE.setup ?? "setup";
+function parseSetupArgv(argv) {
+    let engine = "";
+    let sha256 = "";
+    let i = 0;
+    for (; i < argv.length; i++) {
+        const a = argv[i] ?? "";
+        if (a === "--") {
+            i++;
+            break;
+        }
+        if (a === "--engine" || a === "--engine-sha256") {
+            const value = argv[++i];
+            if (value === undefined)
+                return `${a} needs a value`;
+            if (a === "--engine")
+                engine = value;
+            else
+                sha256 = value;
+            continue;
+        }
+        break;
+    }
+    if (!engine || !sha256)
+        return "--engine and --engine-sha256 are required";
+    if (!/^[0-9a-f]{64}$/.test(sha256))
+        return "--engine-sha256 must be 64 lowercase hex characters";
+    return { engine, sha256, args: argv.slice(i) };
+}
+/** Which of the engine's own flags were given, read the way its parser reads them. */
+export function engineFlags(args) {
+    const seen = { json: false, yes: false, verbose: false, localSync: false };
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i] ?? "";
+        if (VALUED.has(a)) {
+            i++;
+            continue;
+        }
+        if (a === "--json")
+            seen.json = true;
+        if (a === "--yes")
+            seen.yes = true;
+        if (a === "--verbose")
+            seen.verbose = true;
+        if (a === "--with-replica")
+            seen.localSync = true;
+    }
+    return seen;
+}
+/** The plan's steps: number and title on one line, what it does indented below, a blank line between. */
+function planRenderer(r) {
+    let open = false;
+    let hidden = false;
+    return {
+        plan(number, title, text) {
+            hidden = number === 5 || number === 7;
+            if (hidden)
+                return;
+            if (open)
+                r.blank();
+            open = true;
+            r.plan(number >= 8 ? number - 2 : number === 6 ? 5 : number, title, text);
+        },
+        more(text) {
+            if (!hidden)
+                r.line(`       ${text}`);
+        },
+        close() {
+            open = false;
+        },
+    };
+}
+/** A stop before the engine ran: the person's line, and under --json the one document anyway. */
+function stopBeforeEngine(deps, ctx, json, message) {
+    createSetupRenderer(deps.stderr, ctx.env).line(`catalyst setup: ${message}`);
+    if (json)
+        deps.writeJson(`${JSON.stringify({
+            schema: "catalyst-install-last-run/1",
+            state: "stopped",
+            exitCode: EXIT_STOPPED,
+            message,
+            fix: "run the install command again",
+            steps: [],
+        }, null, 2)}\n`);
+    return EXIT_STOPPED;
+}
+/** A shell reports a child killed by a signal as 128 plus its number; so does this command. */
+function exitCodeOf(status, signal) {
+    if (status !== null)
+        return status;
+    return signal ? 128 + (constants.signals[signal] ?? 0) : EXIT_STOPPED;
+}
+export async function cmdSetup(argv, ctx, deps) {
+    const parsed = parseSetupArgv(argv);
+    if (typeof parsed === "string")
+        return stopBeforeEngine(deps, ctx, argv.includes("--json"), `${parsed}. Usage: catalyst ${SETUP_USAGE}`);
+    const flags = engineFlags(parsed.args);
+    let body;
+    try {
+        body = readFileSync(parsed.engine);
+    }
+    catch (error) {
+        return stopBeforeEngine(deps, ctx, flags.json, `the setup engine ${parsed.engine} could not be read (${error instanceof Error ? error.message : String(error)}). Nothing was changed.`);
+    }
+    if (createHash("sha256").update(body).digest("hex") !== parsed.sha256)
+        return stopBeforeEngine(deps, ctx, flags.json, "the setup engine did not match the digest install.sh expected. Nothing was run, and nothing was changed.");
+    // The engine runs from a private copy of the bytes just checked, so the file it was given cannot
+    // change between the check and the run.
+    const own = mkdtempSync(join(tmpdir(), "catalyst-setup-engine-"));
+    try {
+        const engine = join(own, "engine.sh");
+        writeFileSync(engine, body, { mode: 0o600 });
+        return await runEngine(engine, parsed.args, flags, ctx, deps);
+    }
+    finally {
+        rmSync(own, { recursive: true, force: true });
+    }
+}
+async function runEngine(engine, args, flags, ctx, deps) {
+    const errors = createSetupRenderer(deps.stderr, ctx.env);
+    const human = flags.json ? deps.stderr : deps.stdout;
+    const r = createSetupRenderer(human, flags.json ? { ...ctx.env, NO_COLOR: "1" } : ctx.env);
+    const plan = planRenderer(r);
+    // Aborts once the engine has exited: a question or sign-in still open then has nobody to answer.
+    const gone = new AbortController();
+    // The sign-in in progress, if any; Ctrl-C stops only that one.
+    let signinStop = null;
+    const child = spawn("/bin/sh", [engine, ...args], {
+        stdio: ["ignore", "pipe", "pipe", "pipe", "pipe", "pipe"],
+        env: {
+            ...ctx.env,
+            CATALYST_INSTALL_UI: "events",
+            CATALYST_INSTALL_INTERACTIVE: deps.interactive && !flags.yes ? "1" : "0",
+        },
+    });
+    // Node types `stdio` as a five-slot tuple; fds 3 to 5 exist because the spawn above asked for them.
+    const pipes = child.stdio;
+    const jsonPipe = pipes[3];
+    const eventPipe = pipes[4];
+    const answers = pipes[5];
+    if (!(jsonPipe instanceof Readable) ||
+        !(eventPipe instanceof Readable) ||
+        !(answers instanceof Writable)) {
+        child.kill("SIGTERM");
+        return stopBeforeEngine(deps, ctx, flags.json, "the setup engine's pipes could not be opened. Nothing was changed.");
+    }
+    answers.on("error", () => {
+        // The engine stopped before reading its answer; its exit code says why.
+    });
+    const answer = (line) => {
+        if (!answers.destroyed)
+            answers.write(`${line}\n`);
+    };
+    let spin = null;
+    const spinner = () => deps.spinner?.(r, flags.json ? "stderr" : "stdout") ?? null;
+    const stopSpin = () => {
+        spin?.stop();
+        spin = null;
+    };
+    const changes = [];
+    const deferredEnding = [];
+    let current = null;
+    let queue = Promise.resolve();
+    const handle = async (event) => {
+        if (event.kind !== "begin")
+            stopSpin();
+        if (event.kind !== "plan" && event.kind !== "more")
+            plan.close();
+        switch (event.kind) {
+            case "line":
+                if (/^(Details:|Full log:)\s+/.test(event.text))
+                    flags.logPath = event.text.replace(/^(Details:|Full log:)\s+/, "");
+                if (deps.onboard && /^(Next:|Details:|Full log:)\s+/.test(event.text)) {
+                    deferredEnding.push(event);
+                    return;
+                }
+                if (event.text === "")
+                    r.blank();
+                else if (!deps.onboard ||
+                    !/^(Next:|Details:|Full log:|This computer is ready)/.test(event.text)) {
+                    if (event.text === "Catalyst setup")
+                        r.intro(event.text);
+                    else
+                        r.line(event.text);
+                }
+                return;
+            case "row":
+                r.line(`  ${event.label.padEnd(18)} ${event.value}`);
+                return;
+            case "heading":
+                if (deps.onboard && ["What’s left", "What's left"].includes(event.text)) {
+                    deferredEnding.push(event);
+                    return;
+                }
+                if (!deps.onboard ||
+                    !["What’s left", "What\'s left"].includes(event.text))
+                    r.heading(event.text === "Setting up" ? "This computer" : event.text);
+                return;
+            case "plan":
+                plan.plan(event.number, event.title, event.text);
+                return;
+            case "more":
+                plan.more(event.text);
+                return;
+            case "begin":
+                stopSpin();
+                current = event;
+                if (event.number !== 7)
+                    r.begin(event.number === 6 ? 5 : event.number === 5 ? 0 : event.number, MACHINE_TITLES[event.number] ?? event.title);
+                return;
+            case "step":
+                if (event.number !== 7)
+                    r.step(event.mark === "act" && event.number === 6 ? "skip" : event.mark, event.number === 6 ? 5 : event.number === 5 ? 0 : event.number, MACHINE_TITLES[event.number] ?? event.title, event.outcome);
+                else if (event.mark === "fail")
+                    r.step("fail", 0, "This computer", event.outcome);
+                current = null;
+                return;
+            case "detail":
+                if (current || flags.verbose)
+                    r.detail(event.text);
+                return;
+            case "change":
+                changes.push(event.text);
+                return;
+            case "changes-end":
+                if (flags.verbose)
+                    for (const text of changes.splice(0))
+                        r.line(text);
+                return;
+            case "verdict":
+                if (!event.ok || !deps.onboard) {
+                    r.heading(event.ok ? "Setup complete" : "Not ready for work yet");
+                    r.line(event.text);
+                }
+                return;
+            case "stop": {
+                const block = createSetupRenderer(deps.stderr, ctx.env);
+                block.line(block.bold(event.header));
+                block.line(`  What happened: ${event.what}`);
+                block.line(`  Already done:  ${event.done}`);
+                block.line(`  To fix:        ${event.fix}`);
+                block.line(`  Log:           ${event.log}`);
+                // An agent greps this line and runs it as is, so it is never wrapped.
+                deps.stderr.write(`resume: ${event.resume}\n`);
+                return;
+            }
+            case "ask": {
+                if (!(deps.interactive && !flags.yes && deps.ask)) {
+                    answer(event.fallback);
+                    return;
+                }
+                const reply = await deps.ask(event, r, gone.signal);
+                if (reply === null) {
+                    // Ctrl-C at a prompt arrives as a cancelled question (the prompt holds the terminal in
+                    // raw mode). The engine stops the way it stops on Ctrl-C: record, block, exit 10.
+                    child.kill("SIGINT");
+                    answer(event.id === "continue" ? "n" : "");
+                    return;
+                }
+                if (event.id === "replica")
+                    flags.localSync = /^y(es)?$/i.test(reply);
+                answer(reply);
+                return;
+            }
+            case "signin": {
+                // The sign-in is the one step a person does: it gets its own line before the code.
+                r.update("waiting for you");
+                if (!deps.signin) {
+                    answer("failed");
+                    return;
+                }
+                const stop = new AbortController();
+                signinStop = stop;
+                try {
+                    answer(await deps.signin(event.timeoutSeconds, r, AbortSignal.any([stop.signal, gone.signal]), spinner));
+                }
+                finally {
+                    signinStop = null;
+                }
+                return;
+            }
+            case "note":
+                if (flags.verbose)
+                    r.line(r.dim(event.text));
+                return;
+        }
+    };
+    // Events are handled one at a time, in order: a question holds the lines after it until answered.
+    // A handler that fails still answers, so the engine is never left waiting on fd 5.
+    const enqueue = (event) => {
+        queue = queue
+            .then(() => handle(event))
+            .catch((error) => {
+            stopSpin();
+            errors.line(`catalyst setup: ${error instanceof Error ? error.message : String(error)}`);
+            if (event.kind === "ask")
+                answer(event.fallback);
+            if (event.kind === "signin")
+                answer("failed");
+        });
+    };
+    const events = new SetupEventStream(enqueue);
+    const passThrough = new SetupEventStream(enqueue, plainSetupLine);
+    eventPipe
+        .setEncoding("utf8")
+        .on("data", (chunk) => events.push(chunk));
+    let machineJson = "";
+    jsonPipe.setEncoding("utf8").on("data", (chunk) => {
+        if (deps.onboard)
+            machineJson += chunk;
+        else
+            deps.writeJson(chunk);
+    });
+    // Anything the engine prints outside the protocol is still shown, never lost.
+    for (const stream of [child.stdout, child.stderr])
+        stream
+            ?.setEncoding("utf8")
+            .on("data", (chunk) => passThrough.push(chunk));
+    // Ctrl-C reaches the engine too (same process group), and it records and stops on its own. This
+    // command only stops a sign-in in progress, and on a second Ctrl-C stops an engine still going.
+    let interrupts = 0;
+    const onInterrupt = () => {
+        interrupts += 1;
+        signinStop?.abort();
+        if (interrupts > 1)
+            child.kill("SIGTERM");
+    };
+    process.on("SIGINT", onInterrupt);
+    child.on("exit", () => gone.abort());
+    const closed = new Promise((resolve) => child.on("close", () => resolve()));
+    try {
+        const code = await new Promise((resolve) => {
+            child.on("error", (error) => {
+                errors.line(`catalyst setup: the setup engine could not start (${error.message}).`);
+                resolve(EXIT_STOPPED);
+            });
+            child.on("exit", (status, signal) => resolve(exitCodeOf(status, signal)));
+        });
+        // The engine is done; its last lines may still be in the pipes. A background child it started
+        // can hold them open for good, so wait for them briefly, not until that child exits.
+        await Promise.race([
+            closed,
+            new Promise((resolve) => setTimeout(resolve, PIPE_DRAIN_MS).unref()),
+        ]);
+        for (const pipe of [eventPipe, jsonPipe, child.stdout, child.stderr])
+            pipe?.destroy();
+        events.end();
+        passThrough.end();
+        await queue;
+        stopSpin();
+        if (code === 0 &&
+            deps.onboard &&
+            !args.some((a) => ["--dry-run", "--help", "-h"].includes(a))) {
+            try {
+                return await deps.onboard(r, flags);
+            }
+            catch {
+                errors.line("catalyst setup: onboarding could not finish. Run catalyst onboard to try again.");
+                if (flags.json)
+                    deps.writeJson(`${JSON.stringify({ schema: "catalyst-install-last-run/1", state: "failed", exitCode: 10, steps: [] })}\n`);
+                return 10;
+            }
+        }
+        // A failed, declined or dry-run engine never enters onboarding. Preserve its actual
+        // repair guidance; successful continuation owns the sole final screen instead.
+        for (const event of deferredEnding) {
+            if (event.kind === "heading")
+                r.heading(event.text);
+            else if (event.text.startsWith("Next:"))
+                r.outro(event.text);
+            else
+                r.line(event.text);
+        }
+        if (machineJson)
+            deps.writeJson(machineJson);
+        return code;
+    }
+    finally {
+        r.dispose();
+        process.off("SIGINT", onInterrupt);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.14.10",
+  "version": "0.15.0",
   "description": "Customer skill bundle for Catalyst Cloud, named from the executive's seat \u2014 get set up, see what is happening, see what needs you, run a project, unstick what is stuck \u2014 plus the catalyst CLI that reads through the Catalyst Cloud SDK, writes through the agent proxy, and connects your machine to your cloud account with one command. The skills directory is the roster; this line never counts it.",
   "license": "MIT",
   "type": "module",
@@ -47,15 +47,19 @@
     "evals": "node scripts/run-evals.mjs",
     "paths:check": "node scripts/vendor-paths.mjs --check",
     "prose:check": "node scripts/check-public-prose.mjs",
-    "settings:check": "node scripts/vendor-settings.mjs --check"
+    "settings:check": "node scripts/vendor-settings.mjs --check",
+    "self-host:check": "node scripts/vendor-self-host.mjs --check"
   },
   "dependencies": {
-    "@catalyst-cloud/sdk": "^0.13.1",
+    "@catalyst-cloud/sdk": "0.14.1",
     "@clack/prompts": "1.8.1",
+    "fast-string-width": "3.0.2",
+    "fast-wrap-ansi": "0.2.2",
     "smol-toml": "^1.7.1",
     "yaml": "^2.9.0"
   },
   "devDependencies": {
+    "@catalyst-cloud/schema": "0.13.1",
     "@types/node": "^26.3.0",
     "@vitest/coverage-v8": "^4.1.11",
     "typescript": "^7.0.2",

package/skills/catalyst-github/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's GitHub: show a ticket's pull request with its checks, reviews and review threads, say whether it is mergeable under this repository's policy, and explain what a PR accumulates as the ticket moves (the branch, the draft, the rewrite, the force-pushes, the labels, the queue). Use when someone asks "show me the PR", "what are the checks saying", "why hasn't it merged", "what does the queue need", "what does that label mean", or wants the branch and merge conventions Catalyst follows.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.10 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.0 — 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.14.10 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.0 — 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.14.10 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.0 — written in this repository for customer accounts -->
 
 # Onboard me
 
@@ -20,7 +20,7 @@ Guide setup through the same `catalyst onboard` flow that the installer runs. Th
 
 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.
 
-Choose an existing Linear team explicitly in the command's team picker or with `catalyst onboard --team <team ID or unique key>`. Unattended setup does not pick the first team, even when only one is visible. Resume rechecks the saved selection; final readiness reads only that team. A team used to verify the workspace grant is not a project selection. Setup does not create a Linear team. Native sign-in waits for up to ten minutes across all device-code rounds; a timeout saves progress for the next run.
+Choose an existing Linear team explicitly in the command's team picker or with `catalyst onboard --team <team ID or unique key>`. Unattended setup does not pick the first team, even when only one is visible. Resume rechecks the saved selection; final readiness reads only that team. A team used to verify the workspace grant is not a project selection. Setup creates a Linear team only when the cloud advertises it, which is off until approved. The picker then ends with "Create a new Linear team…", which asks for a name and an editable key, creates the team as the person (owner or admin only) and sets up Catalyst's workflow on it. A definite taken key is asked again before a new team is created. An unconfirmed result keeps its key for recovery and asks you to check Linear before another creation. If Linear refuses the person, setup says why and returns to the picker. If the workflow step fails, setup names the created team and the `catalyst team adopt <KEY>` retry. For an owner or admin selecting an existing team, the workflow step shows that team's adopt plan (the stages and labels it creates or keeps) and asks before applying it. `--yes` applies that previewed plan without asking, so use it only when the person has accepted the plan. Native sign-in waits for up to ten minutes across all device-code rounds; a timeout saves progress for the next run.
 
 Default invited-member setup handles personal accounts and leaves workspace administration to an owner or admin. It does not ask the team or repository questions. A member can explicitly request an existing-team selection with `--team` or `--only linear.team`; that request only reads and verifies the selection.
 
@@ -70,5 +70,6 @@ Scripts are run, never read; each prints `--help`.
 - **Previews before project writes.** `team map`, `team adopt` and `team migrate` preview; pass `--yes --plan-hash` only after the person approves that exact plan.
 - **The plan explains changes before they happen.** The onboarding command owns that review. In the older manual path, say what you will write and where before asking for its approval.
 - **Local sync is opt-in.** Every skill works through the API without it; a started process is not proof of freshness.
+- **Running work on this machine is opt-in.** In a terminal the command asks once, default no. Unattended, pass `--runner` only when the person asked for this machine to run Catalyst's work, and `--no-runner` to skip without asking. It needs Docker and an owner or admin. Its waits name who acts: an organization key file from an owner or admin (`CATALYST_RUNNER_ORG_KEY_FILE`), or images and team admission from Catalyst support. Relay that ask; never sign in to a registry or edit the runner's files yourself.
 - **Stop at a wall.** A suspended workspace, an inactive seat, an owner or admin needed where the person is neither, a blocked command: say what you found and who can act, then stop. An older cloud is not a broken command. A person with no account joins one by invitation from its admin.
 - **Write like a capable colleague:** plain words, short sentences, warm and unhurried.

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.14.10 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.0 — 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.14.10 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.0 — 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.14.10 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.0 — 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.14.10 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.0 — 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.14.10 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.0 — written in this repository for customer accounts -->
 
 # What's happening
 

package/vendor/README.md

@@ -7,3 +7,7 @@ Run `CATALYST_PATHS_SOURCE=/path/to/catalyst-cloud node scripts/vendor-paths.mjs
 Replica selection is `--db` where accepted, `CATALYST_REPLICA_DB`, then the machine manifest's `replicaDb`. Before a machine manifest exists, the CLI retains its saved customer.json path or legacy default. A manifest without replicaDb leaves replication optional and unconfigured. A malformed or missing explicit manifest fails instead of selecting another database.
 
 The reader derives the lock from the selected database on each status check. No existing database is copied, moved, opened for writing, or reseeded by path resolution. Setup must import a discovered populated replica into the manifest before activating it. This PR does not install a manifest or start a writer.
+
+# Self-hosted runner Compose file
+
+`self-host/compose.yaml` is catalyst-cloud's `deploy/self-host/compose.yaml` at the commit in `self-host/provenance.json`, byte for byte. `catalyst onboard` copies it to this machine when a person chooses to run Catalyst's work here, because the source repository is private. Run `CATALYST_SELF_HOST_SOURCE=/path/to/catalyst-cloud node scripts/vendor-self-host.mjs` after moving the commit in that script. `npm run self-host:check` validates the file against the recorded hash.