@catalyst-cloud/cli 0.15.4 → 0.15.6

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.15.6
+
+Setup checks current readiness and waits up to one minute while Catalyst reads repository settings.
+
+## 0.15.5
+
+Setup explains what running work on this computer means and lists every repository registered to your Linear team.
+
 ## 0.15.4
 
 - Setup shows a colour mark and clearer progress, with a plain display when your terminal needs it.

package/dist/onboard-headless.js

@@ -242,6 +242,9 @@ export function planOnboardHeadless(args, ctx) {
     delete flags["key-file"];
     delete flags.runner;
     delete flags["no-runner"];
+    // CATALYST_ONBOARD_HEADLESS=1 alone leaves the flag unset; the plan names the headless input
+    // rather than a --no-runner nobody typed (CTC-4739).
+    flags.headless = true;
     if (runner === "yes")
         flags.runner = true;
     if (runner === "no")

package/dist/onboard-next.js

@@ -147,7 +147,7 @@ const REASONS = {
     linear_workspace_permissions_unverified: "The workspace's Linear connection works, but its granted scopes could not be checked. Run catalyst onboard to try again.",
     linear_personal_scope_outdated: "Your personal Linear connection is missing scopes this version needs. Re-authorize it from Connected accounts, then run catalyst onboard.",
     personal_permissions_unverified: "Your personal connection's granted scopes could not be checked. Run catalyst onboard to try again.",
-    required_values_unverified: "Catalyst has not read the repository's settings yet. Run catalyst setup again in a few minutes.",
+    required_values_unverified: "Setup couldn't get a current readiness check for this team from Catalyst, so it can't tell whether the repositories' values are set. Run catalyst ready to check.",
     first_ticket_team_unverified: "Setup could not confirm the selected Linear team. Run catalyst setup again.",
     first_ticket_dispatch_unmapped: "Catalyst does not know which of the team's stages starts its work yet. Set up the team's Catalyst workflow, then run catalyst setup again.",
     housekeeping_service_unverified: "The daily update needs a user service manager, launchd on macOS or systemd --user on Linux. Setup cannot schedule it on this computer. It is optional, and work does not depend on it.",
@@ -435,6 +435,12 @@ export function onboardReasonText(step, context = {}) {
     }
     if (reason === "runner_admission_operator")
         return `The admission policy for team ${onboardTeamKey(context.journal) ?? "<TEAM KEY>"} needs a Catalyst operator to check it. Setup changes only restricted admission and preserves existing policy fields. Ask Catalyst support to confirm a compatible policy, then run the same setup command.`;
+    // CTC-4744: the cloud has not read the settings yet. Setup already waited a minute; this is
+    // the cloud's work, not the person's.
+    if (reason === "required_values_unread") {
+        const which = typeof step.evidence?.repositories === "string" ? step.evidence.repositories : "this team's repositories";
+        return `Catalyst hasn't finished reading the settings of ${which}, so it can't check the values yet. You don't need to do anything: Catalyst does this on its own, and catalyst ready shows when it's done.`;
+    }
     if (reason === "required_values_missing") {
         let facts;
         try {

package/dist/onboard-readiness-fresh.js

@@ -0,0 +1,32 @@
+// CTC-4744: the team's readiness verdict in the contract lasts five minutes, and the contract never
+// recomputes it. Only a readiness read does. Setup asks for that read before it judges a team, so
+// the end of setup and `catalyst ready` read the same current verdict.
+import { normalizeBaseUrl } from "./config.js";
+import { loadContract } from "./contract.js";
+const READ_THROUGH_TIMEOUT_MS = 30_000;
+/** Ask the cloud to bring each team's verdict up to date, then read the contract past its cache.
+ *  The read-through's own answer is not trusted: the contract it refreshes is the evidence. A cloud
+ *  without the route, or any failure here, leaves the verdict as it was. */
+export async function loadFreshTeamContract(ctx, cfg, teamIds, signal, timeoutMs = READ_THROUGH_TIMEOUT_MS) {
+    const expiry = cfg.auth ? Date.parse(cfg.auth.expiresAt) - ctx.now().getTime() : 0;
+    const bearer = cfg.key ||
+        (cfg.auth && Number.isFinite(expiry) && expiry > 30_000 ? cfg.auth.accessToken : undefined);
+    if (bearer)
+        for (const id of new Set(teamIds)) {
+            if (signal?.aborted)
+                break;
+            const deadline = AbortSignal.timeout(timeoutMs);
+            try {
+                const response = await ctx.fetch(`${normalizeBaseUrl(cfg.baseUrl)}/api/v1/agent/tenant/readiness?team=${encodeURIComponent(id)}`, {
+                    redirect: "error",
+                    signal: signal ? AbortSignal.any([signal, deadline]) : deadline,
+                    headers: { authorization: `Bearer ${bearer}`, accept: "application/json" },
+                });
+                await response.body?.cancel().catch(() => { });
+            }
+            catch {
+                // Unreachable or refused: the contract read below decides.
+            }
+        }
+    return loadContract(ctx, cfg, { refresh: true, signal });
+}

package/dist/onboard-ready.js

@@ -1,5 +1,5 @@
 import { loadConfig } from "./config.js";
-import { loadContract } from "./contract.js";
+import { loadFreshTeamContract } from "./onboard-readiness-fresh.js";
 import { ONBOARD_DEFERRED_STEPS, onboardRequiredStepsWaiting, } from "./onboard.js";
 const evidenceNames = new Set(["account", "membershipId", "project", "team", "repository", "count", "checkedAt", "expiresAt", "revision", "lag", "cursor", "heartbeatAgeMs", "supervised", "available", "validated", "phaseStarted", "linearComment", "fleetActivity"]);
 const slug = (value) => value && /^[a-z][a-z0-9_]{1,63}$/.test(value) ? value : undefined;
@@ -98,7 +98,8 @@ export async function observeCloudOnboarding(ctx, scope = {}) {
     const cfg = loadConfig(ctx.home);
     if (!cfg?.user)
         return { checks: [{ id: "signin", state: "fail", required: true, reason: "personal_login_required" }], work: { state: "unknown" } };
-    const { doc, source } = await loadContract(ctx, cfg, { refresh: true });
+    // CTC-4744: ask for each team's verdict fresh, the same read `catalyst setup`'s values step makes.
+    const { doc, source } = await loadFreshTeamContract(ctx, cfg, scope.teamIds ?? []);
     if (source === "cache")
         return { checks: [{ id: "cloud.setup", state: "unknown", required: true, reason: "cloud_observation_unavailable" }], work: { state: "unknown" } };
     const checks = [];

package/dist/onboard-repositories.js

@@ -97,6 +97,17 @@ export async function readOnboardRepositoryInventory(ctx, journal, signal) {
     const teamId = selectedOnboardTeam(journal);
     if (!teamId)
         return { reason: "team_selection_unverified" };
+    // CTC-4742: the per-person repository list names every project a repository belongs to, so a
+    // team that uses several repositories shows all of them. A member's list is narrowed to their
+    // own access by the server. An older server without the route falls back to the one-per-team
+    // registry below.
+    const agent = await readExistingOnboardJson(ctx, "/api/v1/agent/repos", signal);
+    if (!sameIdentity())
+        return { reason: "repository_identity_unverified" };
+    if (!("reason" in agent))
+        return teamRepositories(ctx, journal, teamId, agent.body, sameIdentity, signal);
+    if (agent.status !== 404)
+        return { reason: "repository_read_unavailable" };
     const read = await readExistingOnboardJson(ctx, "/api/v1/repos", signal);
     if (!sameIdentity())
         return { reason: "repository_identity_unverified" };
@@ -171,6 +182,162 @@ export async function readOnboardRepositoryInventory(ctx, journal, signal) {
     }
     return { repositories };
 }
+/** The saved login is still the person, account and origin this run started with (and, when
+ *  `manager`, an owner or admin). Returns that config, or null. */
+function journalIdentity(ctx, journal, manager = false) {
+    const cfg = loadConfig(ctx.home);
+    return cfg?.user &&
+        cfg.account === journal.account &&
+        cfg.user.id === journal.membershipId &&
+        !!journal.baseUrl &&
+        normalizeBaseUrl(cfg.baseUrl) === normalizeBaseUrl(journal.baseUrl) &&
+        (!manager || ["owner", "admin"].includes(cfg.user.role))
+        ? cfg
+        : null;
+}
+const REGISTER_PATH = "/api/v1/agent/project-repositories";
+/** The fresh contract's repository IDs and the repositories registered to the chosen team (by its
+ *  id), or why they can't be trusted. */
+async function contractIds(ctx, journal, teamId, sameIdentity, signal) {
+    const read = await readExistingOnboardJson(ctx, "/api/v1/agent/contract", signal);
+    if (!sameIdentity())
+        return { reason: "repository_identity_unverified" };
+    if ("reason" in read)
+        return { reason: "repository_contract_unavailable" };
+    const doc = object(read.body);
+    const account = object(doc?.account);
+    const merge = object(doc?.merge);
+    if (!doc ||
+        account?.id !== journal.account ||
+        typeof doc.contractVersion !== "string" ||
+        contractVersionInRange(doc.contractVersion, readManifest().tenantContractRange) !== true ||
+        !merge ||
+        !Array.isArray(merge.repositories) ||
+        merge.repositories.length > 10_000 ||
+        !Array.isArray(doc.teams) ||
+        doc.teams.length > 1_000)
+        return { reason: "repository_contract_unverified" };
+    // The team's repositories, keyed by the team's id (a team key can be renamed or missing).
+    const teams = doc.teams.filter((value) => object(value)?.id === teamId);
+    const names = object(object(teams[0])?.repositories)?.registered;
+    if (teams.length !== 1 ||
+        !Array.isArray(names) ||
+        names.length > 1_000 ||
+        !names.every((name) => typeof name === "string" && /^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}\/[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/.test(name)))
+        return { reason: "team_selection_unverified" };
+    const registered = new Set(names.map((name) => name.toLowerCase()));
+    const ids = new Map();
+    const idNames = new Map();
+    for (const value of merge.repositories) {
+        const row = object(value);
+        if (!row ||
+            typeof row.owner !== "string" ||
+            !part.test(row.owner) ||
+            typeof row.name !== "string" ||
+            !part.test(row.name) ||
+            !isRepositoryId(row.repoId))
+            return { reason: "repository_contract_unverified" };
+        const name = key({ owner: row.owner, name: row.name });
+        if (idNames.has(row.repoId) && idNames.get(row.repoId) !== name)
+            return { reason: "repository_contract_unverified" };
+        idNames.set(row.repoId, name);
+        ids.set(name, [...(ids.get(name) ?? []), row.repoId]);
+    }
+    // Registering is offered only when this account's contract lists the route (CTC-4742).
+    const canRegister = Array.isArray(doc.routes) &&
+        doc.routes.some((value) => {
+            const route = object(value);
+            return route?.method === "POST" && route.path === REGISTER_PATH;
+        });
+    return { registered, ids, canRegister };
+}
+/** CTC-4742: every repository an active project of the chosen team uses, with its contract ID. */
+async function teamRepositories(ctx, journal, teamId, body, sameIdentity, signal) {
+    const list = object(body);
+    if (!list || !Array.isArray(list.repositories) || list.repositories.length > 10_000)
+        return { reason: "repository_inventory_shape" };
+    const contract = await contractIds(ctx, journal, teamId, sameIdentity, signal);
+    if ("reason" in contract)
+        return contract;
+    const repositories = [];
+    const seen = new Set();
+    for (const value of list.repositories) {
+        const row = object(value);
+        if (!row ||
+            typeof row.id !== "string" ||
+            typeof row.owner !== "string" ||
+            !part.test(row.owner) ||
+            typeof row.name !== "string" ||
+            !part.test(row.name))
+            return { reason: "repository_inventory_shape" };
+        // The contract says which repositories the team uses; this person's list says which of them
+        // they can see (the server narrows it for a member).
+        const name = key({ owner: row.owner, name: row.name });
+        if (!contract.registered.has(name))
+            continue;
+        if (seen.has(name))
+            return { reason: "repository_binding_ambiguous" };
+        seen.add(name);
+        const ids = contract.ids.get(name);
+        if (!ids || ids.length !== 1 || ids[0] !== row.id)
+            return { reason: "repository_id_unverified" };
+        repositories.push({ teamId, owner: row.owner, name: row.name, repoId: ids[0], registered: true });
+    }
+    return { repositories, canRegister: contract.canRegister };
+}
+/** CTC-4742: repositories the GitHub App can reach that the team does not use yet, for an owner or
+ *  admin only (only they can register one). Any read problem means no offers, never a stopped step. */
+async function offeredRepositories(ctx, journal, teamId, registered, signal) {
+    if (!journalIdentity(ctx, journal, true))
+        return [];
+    const read = await readExistingOnboardJson(ctx, "/api/v1/me/repositories/options", signal);
+    if (!journalIdentity(ctx, journal, true) || "reason" in read)
+        return [];
+    const github = object(object(read.body)?.github);
+    if (!github || github.connected !== true || !Array.isArray(github.repositories) || github.repositories.length > 10_000)
+        return [];
+    const used = new Set(registered.map(key));
+    const offers = [];
+    for (const value of github.repositories) {
+        const row = object(value);
+        if (!row || typeof row.owner !== "string" || !part.test(row.owner) || typeof row.name !== "string" || !part.test(row.name))
+            return [];
+        const name = key({ owner: row.owner, name: row.name });
+        if (used.has(name))
+            continue;
+        used.add(name);
+        offers.push({ teamId, owner: row.owner, name: row.name, repoId: null, registered: false });
+    }
+    return offers;
+}
+/** CTC-4742: register one repository to the team's project. Only adds; nothing here removes one. */
+async function registerToTeam(ctx, journal, teamId, repository, signal) {
+    // The person who answered the question is the one who registers: checked right before the write.
+    const cfg = journalIdentity(ctx, journal, true);
+    if (!cfg)
+        return "repository_identity_unverified";
+    const expiry = cfg.auth ? Date.parse(cfg.auth.expiresAt) - ctx.now().getTime() : 0;
+    const bearer = cfg.key || (cfg.auth && Number.isFinite(expiry) && expiry > 30_000 ? cfg.auth.accessToken : undefined);
+    if (!bearer)
+        return "project_login_refresh_required";
+    // Bounded like every read here, so a server that never answers can't hold setup.
+    const deadline = AbortSignal.timeout(30_000);
+    const bounded = signal ? AbortSignal.any([signal, deadline]) : deadline;
+    try {
+        const response = await ctx.fetch(`${normalizeBaseUrl(cfg.baseUrl)}${REGISTER_PATH}`, {
+            method: "POST",
+            redirect: "error",
+            signal: bounded,
+            headers: { authorization: `Bearer ${bearer}`, "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify({ teamId, repository }),
+        });
+        // A response is not evidence: the next read must show the repository on the team.
+        return response.status === 200 ? null : "repository_register_unverified";
+    }
+    catch {
+        return signal?.aborted ? "interrupted" : "repository_register_unverified";
+    }
+}
 export function existingRepositoryAdapter(args, choose) {
     let chosen;
     const requested = (repositories, journal) => {
@@ -218,7 +385,7 @@ export function existingRepositoryAdapter(args, choose) {
         return {
             state: "done",
             evidence: {
-                repository: JSON.stringify(rows),
+                repository: JSON.stringify(rows.map(({ teamId, owner, name, repoId }) => ({ teamId, owner, name, repoId }))),
                 count: rows.length,
                 checkedAt: ctx.now().getTime(),
             },
@@ -234,6 +401,14 @@ export function existingRepositoryAdapter(args, choose) {
                 return waiting("repository_inventory_empty");
             if (!choose)
                 return waiting("repository_choice_required");
+            const teamId = list.repositories[0].teamId;
+            const offers = list.canRegister
+                ? await offeredRepositories(ctx, journal, teamId, list.repositories, signal)
+                : [];
+            const choices = [
+                ...list.repositories.map((row) => ({ ...row })),
+                ...offers.map((row) => ({ ...row })),
+            ];
             let remove = () => { };
             const answer = await new Promise((resolve, reject) => {
                 const stopped = () => resolve(null);
@@ -244,9 +419,8 @@ export function existingRepositoryAdapter(args, choose) {
                 signal?.addEventListener("abort", stopped, { once: true });
                 remove = () => signal?.removeEventListener("abort", stopped);
                 Promise.resolve()
-                    .then(() => signal?.aborted
-                    ? null
-                    : choose(list.repositories.map((row) => ({ ...row }))))
+                    // The hook gets copies: changing one can never change what is matched below.
+                    .then(() => signal?.aborted ? null : choose(choices.map((row) => ({ ...row }))))
                     .then(resolve, reject);
             }).finally(() => remove());
             if (!answer || signal?.aborted)
@@ -259,9 +433,26 @@ export function existingRepositoryAdapter(args, choose) {
             const names = answer.map((name) => name.toLowerCase());
             if (new Set(names).size !== names.length)
                 return waiting("repository_selection_unverified");
-            const rows = names.map((name) => list.repositories.find((row) => key(row) === name));
-            if (!rows.every((row) => !!row))
+            const picked = names.map((name) => choices.find((row) => key(row) === name));
+            if (!picked.every((row) => !!row))
                 return waiting("repository_selection_unverified");
+            // CTC-4742: a selected offer is registered to the team. Leaving a registered repository
+            // unselected never unregisters it; nothing here removes a repository.
+            for (const row of picked) {
+                if (row.registered !== false)
+                    continue;
+                const failed = await registerToTeam(ctx, journal, teamId, `${row.owner}/${row.name}`, signal);
+                if (failed)
+                    return waiting(failed);
+            }
+            const fresh = picked.some((row) => row.registered === false)
+                ? await readOnboardRepositoryInventory(ctx, journal, signal)
+                : list;
+            if ("reason" in fresh)
+                return waiting(fresh.reason);
+            const rows = names.map((name) => fresh.repositories.find((row) => key(row) === name));
+            if (!rows.every((row) => !!row))
+                return waiting("repository_registration_visibility_pending");
             chosen = rows;
             return check(ctx, journal, signal);
         },

package/dist/onboard-runtime.js

@@ -339,7 +339,11 @@ export function createOnboardRuntime(args, ctx, hooks) {
                 },
         },
         housekeeping: onboardHousekeepingAdapter(hooks.scheduler),
-        values: onboardValuesAdapter(),
+        // CTC-4744: a settings read the cloud has not finished is waited on here, on one line.
+        values: onboardValuesAdapter({
+            message: (text) => hooks.ui?.note ? hooks.ui.note(text) : hooks.ui ? hooks.ui.message(text) : ctx.stderr(text),
+            sleep: hooks.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+        }),
         // Only a person at a terminal picks a ticket; --yes, JSON and headless runs leave it waiting.
         "first-ticket": onboardFirstTicketAdapter(interactiveWait && hooks.ui?.chooseFirstTicket
             ? {

package/dist/onboard-standalone-copy.js

@@ -1,5 +1,8 @@
 import { setupPartHeading, setupStepView, SETUP_NUMBERS, SETUP_PART_NUMBERS, SETUP_PART_OF, } from "./setup-onboard-copy.js";
 export const COMPUTER_CHECKS = ["machine", "cli", "skills", "legacy"];
+/** The runner row when no runner was chosen up front, naming where that choice came from, so the
+ *  plan says why no question comes (CTC-4739). */
+const runnerDeclined = (by) => `this computer will not take work, because ${by}`;
 const PLAN = [
     ["On this computer", "signin", "you approve once in your browser"],
     ["On this computer", "housekeeping", "schedule the daily update"],
@@ -22,7 +25,14 @@ const PLAN = [
  * part. `json` is the plain-text plan an agent reads beside `--json` (dry run, --json on stderr,
  * headless): the older groups and the numbers JSON `actions[].number` reports (CTC-4680).
  */
-export function standalonePlan(journal, scope, runnerSelected = false, numbering = "parts") {
+export function standalonePlan(journal, scope, 
+/** `true` for --runner, `false` for --no-runner, absent when setup will ask (CTC-4739). */
+runner, numbering = "parts", 
+/** Why `runner` is false: the flag on an interactive run, the headless input otherwise. */
+declinedBy = "--no-runner was passed") {
+    const runnerSelected = runner === true;
+    const RUNNER_DECLINED = runnerDeclined(declinedBy);
+    const declined = runner === false;
     const json = numbering === "json";
     const includes = (id) => !scope || scope.includes(id);
     const steps = new Map(journal.steps.map((step) => [step.id, step]));
@@ -53,7 +63,9 @@ export function standalonePlan(journal, scope, runnerSelected = false, numbering
             if (includes("runner"))
                 row("runner", runnerSelected
                     ? "start a Catalyst runner here with Docker"
-                    : "optional; this computer takes work only if you choose it");
+                    : declined
+                        ? RUNNER_DECLINED
+                        : "optional; this computer takes work only if you choose it");
             continue;
         }
         // The terminal gives repository values their own row; the plain-text plan keeps them folded
@@ -66,9 +78,13 @@ export function standalonePlan(journal, scope, runnerSelected = false, numbering
             continue;
         const reviewedDetail = id === "capacity" && includes("runner") && runnerSelected
             ? "start a Catalyst runner here with Docker"
-            : id === "capacity" && !includes("capacity")
-                ? "review the optional runner on this machine; start only if selected"
-                : detail;
+            : id === "capacity" && includes("runner") && declined
+                ? includes("capacity")
+                    ? `${detail}; ${RUNNER_DECLINED}`
+                    : RUNNER_DECLINED
+                : id === "capacity" && !includes("capacity")
+                    ? "review the optional runner on this machine; start only if selected"
+                    : detail;
         rows.push({
             group: json ? group : setupPartHeading(SETUP_PART_OF[id], false),
             part: SETUP_PART_OF[id],

package/dist/onboard-ui.js

@@ -1,13 +1,19 @@
 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, setupWaitsOnAdmin, TIMED_OUT_REASONS, setupPartHeading, setupPartProgress, setupTrackerRows, SETUP_PART_NUMBERS, SETUP_PART_OF, SETUP_PARTS, } from "./setup-onboard-copy.js";
+import { CLOUD_WORK, 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, onboardHeaderIdentity, onboardIdentityLines, onboardNextActions, onboardReadyForWork, onboardStepAction, } from "./onboard.js";
 import { onboardStepDetail, onboardReasonText } from "./onboard-next.js";
 import { CONNECT_PAGE_PATH } from "./onboard-checklist.js";
+/** What the runner question's answers mean, said before it is asked (CTC-4739). */
+const RUNNER_EXPLAINED = [
+    "Yes makes this computer pick up tickets and run agents in Docker with your workspace's AI accounts. It uses this computer's CPU and memory while it is on, and turning it off or letting it sleep pauses that work.",
+    "No is right for a personal workstation: your workspace's runner hosts do the work.",
+    "Pass --no-runner or --runner to skip this question next time.",
+];
 export function shouldUseOnboardUi(args, stdoutTty) {
     return (stdoutTty &&
         !args.json &&
@@ -254,8 +260,11 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             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));
+        // CTC-4744: what only the cloud's own work holds up is neither the person's nor an admin's.
+        const working = live.filter((action) => CLOUD_WORK.has(step(action.id).reason ?? ""));
+        const theirs = live.filter((action) => !working.includes(action) &&
+            setupWaitsOnAdmin(step(action.id), journal));
+        const mine = live.filter((action) => !theirs.includes(action) && !working.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) &&
@@ -272,7 +281,7 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
                 : waiting
                     ? "Next: run catalyst setup once they have."
                     : "Next: run catalyst setup to check again.";
-        return { screen, mine, theirs, skipped, waiting, next, text, live };
+        return { screen, mine, theirs, working, skipped, waiting, next, text, live };
     };
     const summary = (journal) => {
         const sorted = sortActions(journal);
@@ -293,6 +302,11 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             if (screen.more)
                 renderer.line(`and ${screen.more} more after these`);
         }
+        if (sorted.working.length) {
+            renderer.line("Still in progress, nothing for you to do:");
+            for (const action of sorted.working)
+                renderer.item("· ", sorted.text(action));
+        }
         if (sorted.waiting) {
             renderer.line("Waiting on an owner or admin of your Catalyst workspace:");
             for (const action of theirs)
@@ -543,16 +557,35 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
         ...(prompts.multiselect
             ? {
                 async chooseRepositories(repositories) {
+                    const projectsPage = () => {
+                        try {
+                            const base = deps.baseUrl?.();
+                            return base ? ` (${new URL("/settings/projects", base).href})` : "";
+                        }
+                        catch {
+                            return "";
+                        }
+                    };
                     stop();
                     if (!repositories.length || abort.signal.aborted)
                         return null;
+                    // CTC-4742: what the team already uses starts selected. Unselecting never removes one.
+                    const selected = repositories
+                        .filter((row) => row.registered === true)
+                        .map((row) => `${row.owner}/${row.name}`);
                     const answer = await multiselect({
                         ...options,
-                        message: "Which repositories should use this Linear team?",
+                        message: selected.length
+                            ? `Which repositories should use this Linear team? Leaving a repository unselected does not remove it from this team; an admin removes one in Settings → Projects${projectsPage()}.`
+                            : "Which repositories should use this Linear team?",
                         required: true,
+                        ...(selected.length ? { initialValues: selected } : {}),
                         options: repositories.map((row) => ({
                             value: `${row.owner}/${row.name}`,
                             label: `${row.owner}/${row.name}`,
+                            ...(row.registered === false
+                                ? { hint: "not used by this team yet; selecting it adds it" }
+                                : {}),
                         })),
                     });
                     if (prompts.isCancel(answer)) {
@@ -636,9 +669,21 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             return typeof answer === "string" ? answer : null;
         },
         async chooseRunner() {
-            stop();
             if (abort.signal.aborted)
                 return null;
+            // CTC-4739: say what each answer does to this computer before asking, and how to skip it.
+            stop();
+            if (renderer) {
+                renderer.begin(number("runner"), title("runner"), "", "ask");
+                for (const line of RUNNER_EXPLAINED)
+                    renderer.detail(line);
+                active = true;
+                questionOpen = true;
+            }
+            else
+                prompts.log.message(RUNNER_EXPLAINED.join("\n"), {
+                    output: streams.output,
+                });
             const answer = await select({
                 ...options,
                 message: "Run Catalyst's work on this machine?",
@@ -857,22 +902,33 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             }
         },
         async checkAgain(journal) {
+            const sorted = sortActions(journal);
             if (!renderer ||
                 !interactive ||
                 abort.signal.aborted ||
-                !sortActions(journal).mine.length)
+                (!sorted.mine.length && !sorted.working.length))
                 return false;
             active = false;
             summary(journal);
             summaryShown = true;
+            // CTC-4744: one question, about one thing. When the person has something to do, checking
+            // again is for after they do it; when only the cloud is working, it is a wait.
+            const yours = sorted.mine.length > 0;
             const answer = await select({
                 ...options,
-                message: "Done with these?",
+                message: yours
+                    ? `Check again once ${sorted.mine.length === 1 ? "that's" : "those are"} done?`
+                    : "Catalyst is still reading the repositories' settings. Wait for it?",
                 initialValue: "again",
-                options: [
-                    { value: "again", label: "Check again now" },
-                    { value: "stop", label: "Stop here" },
-                ],
+                options: yours
+                    ? [
+                        { value: "again", label: "Check again now" },
+                        { value: "stop", label: "Finish now; run catalyst setup later to check again" },
+                    ]
+                    : [
+                        { value: "again", label: "Wait and check again (about 1 minute)" },
+                        { value: "stop", label: "Finish now; check later with catalyst ready" },
+                    ],
             }, true);
             if (prompts.isCancel(answer)) {
                 abort.abort();

package/dist/onboard-values.js

@@ -1,47 +1,152 @@
 import { loadConfig } from "./config.js";
-import { loadContract } from "./contract.js";
 import { selectedOnboardTeam } from "./onboard-existing.js";
+import { loadFreshTeamContract } from "./onboard-readiness-fresh.js";
 import { valuesFacts } from "./ready-copy.js";
 const waiting = (reason, evidence) => ({
     state: "waiting",
     reason,
     ...(evidence ? { evidence } : {}),
 });
+/** How long setup waits for the cloud to read a repository's settings, and how often it looks. */
+export const VALUES_WAIT_MS = 60_000;
+const VALUES_POLL_MS = 10_000;
+/** While waiting, one slow read-through can't stretch "up to 1 minute". */
+const WAIT_READ_TIMEOUT_MS = 10_000;
+/** The repositories a team's verdict covers, by name, for the one waiting line. */
+function teamRepositories(team, check) {
+    const fromCheck = check ? (valuesFacts(check).repos ?? []).map((row) => row.repo) : [];
+    if (fromCheck.length)
+        return fromCheck;
+    const registered = team?.repositories
+        ?.registered;
+    return Array.isArray(registered)
+        ? registered.filter((name) => typeof name === "string")
+        : [];
+}
+function named(repositories) {
+    if (!repositories.length)
+        return "this team's repositories";
+    if (repositories.length === 1)
+        return repositories[0];
+    return `${repositories[0]} and ${repositories.length - 1} more`;
+}
 /** The selected team's `required_values` readiness check decides this step. It passes when the
  * selected repositories declare no required value, or every one has a value. Nothing here reads,
- * imports or prints a value: a missing one is named, with the page where it is set. A stale, absent
- * or unknown check waits, so the step never claims values it could not see. */
-export function onboardValuesAdapter() {
+ * imports or prints a value: a missing one is named, with the page where it is set.
+ *
+ * CTC-4744: the verdict is asked for fresh first (it lasts five minutes and only a readiness read
+ * recomputes it). When the cloud has not read the settings yet, setup waits up to a minute on one
+ * line, instead of telling the person to run setup again. */
+export function onboardValuesAdapter(deps = {}) {
     return {
         check: async (ctx, journal, signal) => {
             const cfg = loadConfig(ctx.home);
             const teamId = selectedOnboardTeam(journal);
             if (!cfg || !teamId)
                 return waiting("required_values_unverified");
-            let loaded;
-            try {
-                loaded = await loadContract(ctx, cfg, { refresh: true, signal });
-            }
-            catch {
-                return waiting(signal?.aborted ? "interrupted" : "required_values_unverified");
+            const read = async (timeoutMs, readSignal = signal) => {
+                let loaded;
+                try {
+                    // The contract transport owns another timeout. Carry our caller's cancellation through
+                    // its fetch too, including response-body reads and any credential refresh.
+                    const readCtx = readSignal
+                        ? {
+                            ...ctx,
+                            fetch: (input, init) => ctx.fetch(input, {
+                                ...init,
+                                signal: init?.signal
+                                    ? AbortSignal.any([readSignal, init.signal])
+                                    : readSignal,
+                            }),
+                        }
+                        : ctx;
+                    loaded = await loadFreshTeamContract(readCtx, cfg, [teamId], readSignal, timeoutMs);
+                }
+                catch {
+                    return { kind: "unverified" };
+                }
+                if (loaded.source === "cache")
+                    return { kind: "unverified" };
+                const team = loaded.doc.teams.find((row) => row.id === teamId);
+                const readiness = team?.readiness;
+                const fresh = readiness?.checkedAt != null &&
+                    readiness.expiresAt != null &&
+                    readiness.expiresAt > ctx.now().getTime();
+                // A verdict the cloud could not bring up to date says nothing either way.
+                if (!readiness || !fresh)
+                    return { kind: "unverified" };
+                const check = readiness.checks.find((row) => row.id === "required_values");
+                // An older cloud may not send this check at all: that says nothing, it is not an unread.
+                if (!check)
+                    return { kind: "unverified" };
+                if (check.state === "pass")
+                    return { kind: "pass" };
+                if (check.state === "fail")
+                    return { kind: "fail", check };
+                return { kind: "unread", repositories: teamRepositories(team, check) };
+            };
+            let reading = await read();
+            if (reading.kind === "unread" && deps.sleep) {
+                deps.message?.(`Waiting for Catalyst to read the settings of ${named(reading.repositories)} (up to 1 minute)…`);
+                // One deadline covers sleep, readiness refresh and contract/body reads. Attempts also
+                // bound an injected sleep whose clock stands still.
+                const deadline = Date.now() + VALUES_WAIT_MS;
+                const owned = new AbortController();
+                const waitSignal = signal ? AbortSignal.any([signal, owned.signal]) : owned.signal;
+                let stop = () => { };
+                const stopped = new Promise((resolve) => {
+                    stop = () => {
+                        owned.abort();
+                        resolve(null);
+                    };
+                });
+                const timer = setTimeout(stop, VALUES_WAIT_MS);
+                signal?.addEventListener("abort", stop, { once: true });
+                try {
+                    if (signal?.aborted)
+                        stop();
+                    for (let attempt = 0; reading.kind === "unread" &&
+                        attempt < VALUES_WAIT_MS / VALUES_POLL_MS &&
+                        Date.now() < deadline &&
+                        !waitSignal.aborted; attempt++) {
+                        // Ctrl-C or expiry ends either stage at once, even if an injected promise stalls.
+                        await Promise.race([
+                            deps.sleep(Math.min(VALUES_POLL_MS, Math.max(0, deadline - Date.now()))),
+                            stopped,
+                        ]);
+                        if (waitSignal.aborted || Date.now() >= deadline)
+                            break;
+                        const next = await Promise.race([
+                            read(Math.min(WAIT_READ_TIMEOUT_MS, deadline - Date.now()), waitSignal),
+                            stopped,
+                        ]);
+                        // A result after expiry says nothing about the last observed unread verdict.
+                        if (waitSignal.aborted || Date.now() >= deadline || !next)
+                            break;
+                        reading = next;
+                    }
+                }
+                finally {
+                    clearTimeout(timer);
+                    signal?.removeEventListener("abort", stop);
+                    owned.abort();
+                }
             }
-            if (loaded.source === "cache")
-                return waiting("required_values_unverified");
-            const readiness = loaded.doc.teams.find((team) => team.id === teamId)?.readiness;
-            const fresh = readiness?.checkedAt != null &&
-                readiness.expiresAt != null &&
-                readiness.expiresAt > ctx.now().getTime();
-            const check = fresh
-                ? readiness.checks.find((row) => row.id === "required_values")
-                : undefined;
-            if (check?.state === "pass")
+            if (signal?.aborted)
+                return waiting("interrupted");
+            if (reading.kind === "pass")
                 return { state: "done", evidence: { team: teamId } };
-            if (check?.state !== "fail")
-                return waiting("required_values_unverified");
-            return waiting("required_values_missing", {
-                team: teamId,
-                requiredValues: JSON.stringify(valuesFacts(check)),
-            });
+            if (reading.kind === "fail")
+                return waiting("required_values_missing", {
+                    team: teamId,
+                    requiredValues: JSON.stringify(valuesFacts(reading.check)),
+                });
+            if (reading.kind === "unread")
+                return waiting("required_values_unread", {
+                    team: teamId,
+                    repositories: named(reading.repositories),
+                });
+            return waiting("required_values_unverified");
         },
     };
 }

package/dist/onboard.js

@@ -135,6 +135,8 @@ export const ONBOARD_DEPENDENCIES = {
         "linear.automations",
         "accounts",
         "capacity",
+        // CTC-4744: no work is offered while the cloud is still reading the settings (dependencySettled).
+        "values",
     ],
 };
 const ADMIN_STEPS = new Set([
@@ -600,7 +602,7 @@ function printPlan(ctx, journal, identity, options) {
             ctx.stdout(line);
     let group;
     // Beside --json and headless output: the numbers JSON actions carry (CTC-4680).
-    for (const row of standalonePlan(journal, options?.scope, options?.runner, "json")) {
+    for (const row of standalonePlan(journal, options?.scope, options?.runner, "json", options?.runnerDeclinedBy)) {
         if (row.group !== group) {
             ctx.stdout("");
             ctx.stdout(row.group);
@@ -652,6 +654,18 @@ function sanitizedResult(id, result, at) {
     row.at = at;
     return row;
 }
+/** CTC-4744: whether a step a later one depends on has settled. Only the cloud actively reading
+ *  the settings (`required_values_unread`, after setup's own one-minute wait) holds a first
+ *  ticket. A finished check that found missing values has settled: the first phase needs no
+ *  values, and the missing ones are named. So has one that could not be checked at all (an older
+ *  cloud, a cached contract): holding work on it would hold it for good. */
+export function dependencySettled(step) {
+    return (stepSatisfied(step) ||
+        (step?.id === "values" &&
+            step.state === "waiting" &&
+            step.reason !== "required_values_unread" &&
+            step.reason !== "interrupted"));
+}
 export function stepSatisfied(step) {
     return (step?.state === "done" ||
         (step?.state === "skipped" &&
@@ -797,7 +811,15 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
         for (const id of ONBOARD_STEPS)
             reviewedScope.add(id);
     const planOptions = (journal) => ({
-        runner: args.flags.runner === true,
+        runner: args.flags.runner === true
+            ? true
+            : args.flags["no-runner"] === true
+                ? false
+                : undefined,
+        // Headless turns --runner no and CATALYST_ONBOARD_RUNNER=no into --no-runner; say which.
+        runnerDeclinedBy: args.flags.headless === true
+            ? "the headless runner input is no"
+            : "--no-runner was passed",
         localSync: args.flags["local-sync"] === true || journal.localSync === true,
         scope: ONBOARD_STEPS.filter((id) => reviewedScope.has(id)),
     });
@@ -1307,7 +1329,7 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
                     deps.ui?.stepEnd(journalStep(journal, id), journal);
                     continue;
                 }
-                const missing = (ONBOARD_DEPENDENCIES[id] ?? []).find((parent) => !stepSatisfied(journalStep(journal, parent)));
+                const missing = (ONBOARD_DEPENDENCIES[id] ?? []).find((parent) => !dependencySettled(journalStep(journal, parent)));
                 if (missing) {
                     recordStep({
                         id,

package/dist/ready-copy.js

@@ -299,8 +299,8 @@ export function teamCheckCopy(baseUrl, key, id, state, valuesFix) {
         case "required_values":
             return unknown
                 ? {
-                    line: team(`Catalyst hasn't read the settings of ${key}'s repository yet.`),
-                    fix: "catalyst setup reads them when you choose repositories. Run catalyst setup",
+                    line: team(`Catalyst hasn't finished reading the settings of ${key}'s repositories yet.`),
+                    fix: "nothing to do; Catalyst reads them on its own. Run catalyst ready again in a minute to see the result",
                 }
                 : {
                     line: team(`A variable ${key}'s repository needs has no value, so Catalyst can't run its work.`),

package/dist/setup-onboard-copy.js

@@ -1,4 +1,4 @@
-import { ONBOARD_DEPENDENCIES, ONBOARD_STEPS, ONBOARD_TITLES, } from "./onboard.js";
+import { dependencySettled, ONBOARD_DEPENDENCIES, ONBOARD_STEPS, ONBOARD_TITLES, } from "./onboard.js";
 import { dispatchStageName, onboardReasonText } from "./onboard-next.js";
 /** The step numbers `--json` reports. People read SETUP_PART_NUMBERS instead (CTC-4680). */
 export const SETUP_NUMBERS = {
@@ -250,6 +250,8 @@ function unfinished(step) {
             return step.state === "skipped" ? "not chosen" : "not done yet";
     }
 }
+/** CTC-4744: reasons a step waits on the cloud's own work, never on the person or an admin. */
+export const CLOUD_WORK = new Set(["required_values_unread"]);
 export function setupStepView(step, journal, required = false) {
     required ||= step.id === "runner" && step.evidence?.selected === true;
     let mark = step.state === "done"
@@ -265,12 +267,16 @@ export function setupStepView(step, journal, required = false) {
                     ? "skip"
                     : "act";
     let outcome = step.state === "done" ? succeeded(step) : unfinished(step);
-    if (mark === "later") {
+    if (step.state !== "done" && CLOUD_WORK.has(step.reason ?? "")) {
+        mark = "later";
+        outcome = "still in progress; Catalyst is reading the settings";
+    }
+    else if (mark === "later") {
         const waitsOn = step.reason === "github_install_pending"
             ? ["github.install"]
             : (ONBOARD_DEPENDENCIES[step.id] ?? []).filter((id) => {
                 const s = journal?.steps.find((s) => s.id === id);
-                return s?.state !== "done" && s?.state !== "skipped";
+                return s?.state !== "skipped" && !dependencySettled(s);
             });
         // Numbers restart in each part: this part's steps come bare, then each other part once.
         const byPart = new Map();
@@ -361,7 +367,7 @@ 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 empty = () => ({ total: 0, done: 0, needs: 0, working: 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();
@@ -379,6 +385,7 @@ moment = "end") {
             {
                 // 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,
+                working: step.state !== "done" && CLOUD_WORK.has(step.reason ?? ""),
                 kind: setupWaitsOnAdmin(step, journal)
                     ? "admin"
                     : step.reason === "member_scope" &&
@@ -400,6 +407,8 @@ moment = "end") {
             if (own.some((s) => s.mark === "fail"))
                 part.failed++;
         }
+        else if (own.some((s) => s.working))
+            part.working++;
         else if (steps.some((s) => s.kind === "admin"))
             part.admin++;
         else if (steps.some((s) => s.kind === "aside"))
@@ -445,6 +454,8 @@ export function setupTrackerRows(progress, moment) {
             return row("done", "");
         if (got.needs)
             return row(needsMark, `${steps(got.needs)} ${got.needs === 1 ? "needs" : "need"} someone`);
+        if (got.working)
+            return row("later", `${steps(got.working)} still in progress`);
         if (got.admin)
             return row("act", waiting(got.admin));
         if (got.aside)
@@ -532,10 +543,13 @@ export function setupFinalScreen(journal, base, paused = false, required = new S
     const roots = journal.steps
         .filter((step) => {
         const m = setupStepView(step, journal, required.has(step.id)).mark;
-        return ((m === "act" || m === "fail" || adminLeft.has(step.id)) &&
+        return ((m === "act" ||
+            m === "fail" ||
+            adminLeft.has(step.id) ||
+            (step.state !== "done" && CLOUD_WORK.has(step.reason ?? ""))) &&
             (ONBOARD_DEPENDENCIES[step.id] ?? []).every((id) => {
                 const parent = journal.steps.find((s) => s.id === id);
-                return parent?.state === "done" || parent?.state === "skipped";
+                return parent?.state === "skipped" || dependencySettled(parent);
             }));
     })
         .filter((step) => step.id !== "ready")
@@ -545,6 +559,8 @@ export function setupFinalScreen(journal, base, paused = false, required = new S
     const actions = unique
         .slice(0, 5)
         .map((step) => ({ id: step.id, text: action(step, base, journal) }));
+    // CTC-4744: the Next line is about what the person does; the cloud's own work is listed apart.
+    const personal = actions.filter((row) => !CLOUD_WORK.has(journal.steps.find((s) => s.id === row.id)?.reason ?? ""));
     const readiness = journal.steps.find((step) => step.id === "ready");
     const readinessCause = !paused &&
         !actions.length &&
@@ -578,19 +594,21 @@ export function setupFinalScreen(journal, base, paused = false, required = new S
             ? `Follow ${ticketUrl ?? key} in Linear; Catalyst comments there as each phase finishes.`
             : heading === "Setup complete"
                 ? `Next: move a ticket to ${dispatchStageName(firstTicket?.evidence?.stage)} in Linear.`
-                : journal.exit === 0 && actions[0]
-                    ? `Next: ${actions[0].text[0].toLowerCase() + actions[0].text.slice(1)}`
-                    : actions.length === 1
+                : journal.exit === 0 && personal[0]
+                    ? `Next: ${personal[0].text[0].toLowerCase() + personal[0].text.slice(1)}`
+                    : personal.length === 1
                         ? "Next: run catalyst onboard after you finish 1."
-                        : actions.length === 2
+                        : personal.length === 2
                             ? "Next: run catalyst onboard after you finish 1 and 2."
-                            : actions.length
+                            : personal.length
                                 ? "Next: run catalyst onboard after you finish 1 to " +
-                                    actions.length +
+                                    personal.length +
                                     "."
-                                : readyStep?.reason === "member_team_required"
-                                    ? "Next: run catalyst onboard --team <KEY> to check again."
-                                    : "Next: run catalyst onboard to check again.";
+                                : actions.length
+                                    ? "Next: nothing for you to do. catalyst ready shows when Catalyst has read the settings."
+                                    : readyStep?.reason === "member_team_required"
+                                        ? "Next: run catalyst onboard --team <KEY> to check again."
+                                        : "Next: run catalyst onboard to check again.";
     return {
         heading,
         readinessCause,
@@ -696,31 +714,34 @@ export function onboardJsonView(journal, base, paused = false, options = {}) {
             number: SETUP_NUMBERS[action.id] ?? 0,
             text: text.charAt(0).toUpperCase() + text.slice(1),
             ...(url ? { url } : {}),
-            who: admin
-                ? "admin"
-                : action.id === "github.install"
-                    ? "github-org-admin"
-                    : [
-                        "linear.personal",
-                        "github.personal",
-                        "signin",
-                        "linear.team",
-                        "github.repos",
-                        "projects",
-                        "first-ticket",
-                        "settings",
-                        "values",
-                        "accounts",
-                        "runner",
-                        "machine",
-                        "cli",
-                        "skills",
-                        "legacy",
-                        "daemon",
-                        "housekeeping",
-                    ].includes(action.id)
-                        ? "you"
-                        : "admin",
+            // CTC-4744: the cloud's own work is nobody's to do.
+            who: CLOUD_WORK.has(step.reason ?? "")
+                ? "catalyst"
+                : admin
+                    ? "admin"
+                    : action.id === "github.install"
+                        ? "github-org-admin"
+                        : [
+                            "linear.personal",
+                            "github.personal",
+                            "signin",
+                            "linear.team",
+                            "github.repos",
+                            "projects",
+                            "first-ticket",
+                            "settings",
+                            "values",
+                            "accounts",
+                            "runner",
+                            "machine",
+                            "cli",
+                            "skills",
+                            "legacy",
+                            "daemon",
+                            "housekeeping",
+                        ].includes(action.id)
+                            ? "you"
+                            : "admin",
         };
     });
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.15.4",
+  "version": "0.15.6",
   "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.4 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — 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.4 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — 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.4 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — 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.4 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — 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.4 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — 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.4 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — 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.4 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — 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.4 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — written in this repository for customer accounts -->
 
 # What's happening