@catalyst-cloud/cli 0.15.0 → 0.15.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.15.2
+
+- `catalyst setup` is the command to set up Catalyst. It runs the same steps as `catalyst onboard`, which still works.
+- When a browser link times out, setup says so and asks whether you are ready to try again. Yes gives a new link; stopping pauses setup without moving on to steps that depend on it.
+- The GitHub link opens GitHub's install page directly. An install request already waiting on an organization owner is not requested again, and setup still shows the link to install it yourself.
+- Setup asks whether to run work on this machine only after Catalyst is installed on GitHub.
+- Sign-in says which Catalyst workspace you joined, without internal account numbers. `catalyst ready` describes each team problem in plain words, with the page to fix it and who can fix it.
+
+## 0.15.1
+
+- Runner setup accepts verified personal team admission before a repository has been mapped to that team. Older cloud servers keep their existing admission check.
+
 ## 0.15.0
 
 - Installation and onboarding share a plan and progress display. Browser approvals stay in the same flow, and resumed runs recheck saved choices against current access.

package/README.md

@@ -4,13 +4,22 @@
 
 ## Install
 
-Run the installer, then type `/catalyst-onboard` in your coding agent:
+Set up Catalyst Cloud and manage your account from the command line.
+
+Check ticket progress and see which decisions need your attention.
+
+Install: `npm install -g @catalyst-cloud/cli`
+
+[CLI documentation](https://github.com/coalesce-labs/catalyst-cloud-skills#readme)
+
+Run the installer, then run `catalyst onboard`:
 
 ```sh
 curl -fsSL https://staging.catalystcloud.dev/install.sh | sh
+catalyst onboard
 ```
 
-The installer puts the CLI and both skill packs on this machine and connects it with one browser approval. It ends by printing the next step. Then open a new session of your coding agent in any directory and type `/catalyst-onboard` (`$catalyst-onboard` in Codex). The onboarding skill reads where this machine stands and walks you through the rest one step at a time. It asks before it writes anything to your machine. Everything else on this page is the reference it follows.
+The installer puts the CLI and both skill packs on this machine and connects it with one browser approval. Run `catalyst onboard` to finish setup from the command line. You can also use the onboarding skill in your coding agent after that. Everything else on this page is the reference.
 
 This repository supplies skills for setting up and operating your Catalyst Cloud account. A coding workstation also uses [`coalesce-labs/catalyst-dev-skills`](https://github.com/coalesce-labs/catalyst-dev-skills) for research, planning, implementation, review, and shipping.
 

package/dist/args.js

@@ -457,7 +457,7 @@ export const FLAG_TABLES = {
     },
 };
 export const VERB_USAGE = {
-    setup: "setup --engine <file> --engine-sha256 <hex> [-- <install options>]   (run by install.sh; install.sh --help lists the options)",
+    setup: "setup [onboard options]   (sets up Catalyst step by step; same as catalyst onboard) | setup --engine <file> --engine-sha256 <hex> [-- <install options>]   (run by install.sh; install.sh --help lists the options)",
     login: "login [--base-url <url>] [--start-replica]   (keyless; or --key <personal-key> / CATALYST_CLOUD_TOKEN)",
     onboard: "onboard [--team <ID|key>] [--repo <owner/name>]... [--coding-account <slot>] [--resume-from <step>] [--only <step>] [--local-sync] [--runner|--no-runner] [--yes] [--dry-run] [--json] | onboard --headless [--key-file <path>] [--team ...] [--repo ...]... [--coding-account ...] [--runner yes|no] [--json]",
     install: "install [--skills-dir <dir>] [--force]",

package/dist/capabilities.js

@@ -5,7 +5,9 @@ const agent = (method, name) => ({ method, path: `/api/v1/agent/${name}` });
  *  the person, the workspace, the project, the repository, then work. A new verb is a new row here
  *  in the same change, or `catalyst capabilities` lies to every guide that reads it. */
 export const CAPABILITIES = [
-    { verb: "setup", does: "show install.sh's plan, progress and sign-in in this terminal, and ask its questions", needs: "member", routes: [], since: "0.15.0", engineProtocol: 1 },
+    // CTC-4680: plain `catalyst setup` runs the onboard flow, so install.sh may hand off to it. install.sh
+    // reads this flag rather than `setup --help`, which already exits 0 on 0.15.x.
+    { verb: "setup", does: "set up Catalyst step by step, or show install.sh's plan, progress and sign-in in this terminal", needs: "member", routes: [], since: "0.15.0", engineProtocol: 1, bootstrapHandoff: true },
     { verb: "onboard", does: "run and resume Catalyst setup with a saved step record", needs: "member", routes: [], since: "0.14.0", bootstrapHandoff: true, headless: true },
     { verb: "status", does: "say whether this machine is connected, as whom, and to which cloud", needs: "member", routes: [], since: "0.1.0" },
     { verb: "me", does: "read the person's seat, role and Linear identity", needs: "member", routes: [], since: "0.1.0" },

package/dist/cli.js

@@ -69,7 +69,7 @@ const VERB_ALIASES = { join: "login" };
 const HUMAN_VERBS = new Set(["login", "install", "status", "notice"]);
 export function usageText() {
     return [
-        `${PACKAGE_NAME} — the Catalyst Cloud customer CLI: connect to your tenant, read through the SDK, write through the agent proxy`,
+        `${PACKAGE_NAME} — the Catalyst Cloud customer CLI: connect to your Catalyst workspace, read through the SDK, write through the agent proxy`,
         "",
         "Usage:",
         "  catalyst login [--base-url <url>] [--start-replica]   (keyless: logs you in as yourself)",
@@ -96,7 +96,7 @@ export function usageText() {
         "  catalyst var set <NAME> | var import <file> [--repo <owner/name>] [--names NAME[,NAME...]]   (plain environment variables)",
         "  catalyst team <list|check|map|adopt|migrate|checklist> ...",
         "  catalyst capabilities [--json]   (what this CLI can do, the role each verb needs, and whether this cloud serves it)",
-        "  catalyst project list [--json]   (all tenant projects, including those with no stage mapping)",
+        "  catalyst project list [--json]   (all workspace projects, including those with no stage mapping)",
         "  catalyst project wip-limit <get|set <n>|set default> [--team K]   (a project's new-start WIP limit; members read, owners and admins set)",
         "  catalyst repo <agents-block <path> [--write]|agent-setup <path> [--apply] [--with-check]>   (a checkout's AGENTS.md block and portable agent layout; working tree only)",
         "  catalyst legacy [--remove [--data] [--yes]]   (leftovers of the old local Catalyst runtime: list them; remove them only on a yes)",
@@ -110,8 +110,8 @@ export function usageText() {
         "--key (or set CATALYST_CLOUD_TOKEN) to use a personal or account key instead. The base URL defaults",
         `to CATALYST_CLOUD_BASE_URL or ${DEFAULT_BASE_URL}.`,
         "",
-        "login discovers your tenant from GET /api/v1/me, writes ~/.config/catalyst-cloud/customer.json",
-        "(0600) holding your login session (or key) and this CLI's path, and caches the tenant contract",
+        "login finds your Catalyst workspace, writes ~/.config/catalyst-cloud/customer.json",
+        "(0600) holding your login session (or key) and this CLI's path, and caches the workspace contract",
         "beside it. A keyless session's short-lived token refreshes silently on every request. login does",
         "not install skills: your agent's own install command does that, and `install` is only here to",
         "repair a copy this package made.",
@@ -208,9 +208,15 @@ function maybePrintUpdateNotice(args, ctx) {
 }
 export async function main(argv, ctx = defaultCtx(), deps = {}) {
     // CTC-4625: setup passes the install options through to its engine untouched, so they never meet
-    // this CLI's own flag tables.
-    if (argv[0] === "setup")
-        return runSetup(argv.slice(1), ctx, deps);
+    // this CLI's own flag tables. CTC-4680: without --engine, `setup` is the name a person types for
+    // the onboard flow, so it runs exactly that.
+    if (argv[0] === "setup") {
+        const rest = argv.slice(1);
+        const own = rest.indexOf("--") === -1 ? rest : rest.slice(0, rest.indexOf("--"));
+        if (own.includes("--engine") || own.includes("--help") || own.includes("-h"))
+            return runSetup(rest, ctx, deps);
+        argv = ["onboard", ...rest];
+    }
     let args;
     try {
         args = parseArgs(argv.map((a, i) => (i === 0 && VERB_ALIASES[a] ? VERB_ALIASES[a] : a)));
@@ -231,7 +237,9 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
         onboardHeadlessRequested(args, ctx.env))
         return headlessUsageRefusal(ctx, "--help and --version print text, not the headless document; run them without --json", true, manifest.version);
     if (args.version) {
-        ctx.stdout(`${PACKAGE_NAME} ${manifest.version} (tenant contract range: ${manifest.tenantContractRange})`);
+        ctx.stdout(
+        // Machine-read: install.sh and catalyst-cloud's onboarding harness match this exact line.
+        `${PACKAGE_NAME} ${manifest.version} (tenant contract range: ${manifest.tenantContractRange})`);
         return 0;
     }
     if (args.command === null) {
@@ -687,26 +695,25 @@ async function cmdLogin(args, ctx, deps, personalOnly = false) {
     };
     checkCancelled();
     const written = writeConfig(ctx.home, config);
-    ctx.stdout(`Connected to ${me.name} (${me.slug}) — account ${me.account}`);
+    ctx.stdout(`Catalyst workspace: ${me.name} (${me.slug})`);
     if (me.user) {
-        ctx.stdout(`Connected as ${me.user.label} (${me.user.role})${me.user.linearUserId
+        ctx.stdout(`Signed in to Catalyst as ${me.user.label} (${me.user.role})${me.user.linearUserId
             ? ""
             : ' — your Linear identity is not matched yet, so "what needs me" will show everyone\'s asks until an admin matches it in Settings'}`);
     }
     else {
-        ctx.stderr(`[catalyst] this is the tenant's account key (a host credential), not your own — the skills work, but nothing your agent writes will carry your name and "what needs me" cannot mean you. Mint a personal key at Settings → API keys and log in with that.`);
+        ctx.stderr(`[catalyst] this is your Catalyst workspace's shared key (a host credential), not your own. The skills work, but nothing your agent writes will carry your name, and "what needs me" cannot mean you. Make a personal key at Settings → API keys and sign in with that.`);
     }
     ctx.stdout(`Config written to ${written.path} (mode ${formatMode(written.mode)}, holds your ${auth ? "login session" : "key"} and the CLI path)${written.mode === CONFIG_MODE
         ? ""
         : ` — expected ${formatMode(CONFIG_MODE)}; chmod it by hand`}`);
-    ctx.stdout(`Tenant contract range: ${manifest.tenantContractRange}`);
     try {
         const loaded = await loadContract(ctx, config, {
             refresh: true,
             signal: deps.signal,
         });
         checkCancelled();
-        ctx.stdout(`Tenant contract ${loaded.doc.contractVersion} cached at ${loaded.path}`);
+        ctx.stdout(`Saved your workspace settings (version ${loaded.doc.contractVersion}) to ${loaded.path}`);
     }
     catch (err) {
         checkCancelled();

package/dist/consent-browser.js

@@ -54,5 +54,7 @@ export const openConsentBrowser = createConsentBrowserOpener();
 /** The web page that finishes a consent step when no browser opens here. The signed link stays private. */
 export function finishOnTheWeb(baseUrl, page, action) {
     const origin = baseUrl.replace(/\/+$/, "");
-    return `No browser opened on this computer. In a browser signed in to Catalyst, open ${origin}/settings/${page} and ${action}. Setup keeps waiting here.`;
+    // CTC-4680: the GitHub install has a route that goes straight to GitHub; Integrations starts nothing.
+    const path = page === "github-install" ? "/connect/github/start" : `/settings/${page}`;
+    return `No browser opened on this computer. In a browser signed in to Catalyst, open ${origin}${path} and ${action}. Setup keeps waiting here.`;
 }

package/dist/onboard-github.js

@@ -215,6 +215,18 @@ function observation(body, now) {
         return waiting("github_installation_status_unavailable");
     if (outdated)
         return outdated;
+    // CTC-4680 round 5: a request already waiting for an org owner on GitHub is not a new install.
+    if (row.installations.length === 0 && row.pending.length > 0) {
+        const org = object(row.pending[0])?.githubOrg;
+        return {
+            state: "waiting",
+            reason: "github_installation_approval_pending",
+            evidence: {
+                provider: "github",
+                ...(typeof org === "string" ? { org } : {}),
+            },
+        };
+    }
     if (!allConnected)
         return { state: "pending" };
     if (permissionsUnverified)
@@ -464,7 +476,7 @@ export function githubInstallationAdapter(options) {
                 if (signal?.aborted)
                     return waiting("interrupted");
                 browserUnavailable = true;
-                ctx.stderr(finishOnTheWeb(current.baseUrl, "connections", "install the GitHub App"));
+                ctx.stderr(finishOnTheWeb(current.baseUrl, "github-install", "install Catalyst on your GitHub organization"));
             }
             let latest = waiting("github_installation_status_unavailable");
             const run = () => pollConsent({

package/dist/onboard-headless.js

@@ -323,7 +323,9 @@ function headlessRetryText(text, keys) {
     return text
         .replace(/\b(?:Renew your login with|Sign in as one with|Sign in with|[Rr]un) catalyst login\b/g, key)
         .replace(/\bRenew your login with catalyst onboard\b/g, key)
-        .replace(/\bcatalyst onboard\b(?! --help\b)(?: --runner)?(?: again)?/g, "the same headless setup command");
+        // CTC-4680: `catalyst setup` is the same flow as `catalyst onboard`, and bare, it drops the
+        // headless flags and inputs just the same.
+        .replace(/\bcatalyst (?:onboard|setup)\b(?! --help\b)(?: --runner)?(?: again)?/g, "the same headless setup command");
 }
 /** The report's view of a finished journal: each unsatisfied step as one named item. */
 export function headlessStepItems(journal, baseUrl, requireRunner = false, only) {
@@ -457,7 +459,7 @@ export async function runOnboardHeadless(args, ctx, hooks, cliVersion) {
                 const loginGuidance = headlessLoginGuidance(journal.steps.find((step) => step.id === action.step)?.reason ?? "", keys);
                 return { ...action, text: loginGuidance ?? headlessRetryText(action.text, keys), ...(loginGuidance ? { url: keys } : {}) };
             });
-            const next = headlessRetryText(view.next.replace(/(?:run )?catalyst onboard(?: --runner)?(?: again)?/g, "run the same headless setup command"), keys);
+            const next = headlessRetryText(view.next.replace(/(?:run )?catalyst (?:onboard|setup)(?: --runner)?(?: again)?/g, "run the same headless setup command"), keys);
             ctx.stdout(JSON.stringify({ ...view, actions, next, headless: report }));
         }
         else

package/dist/onboard-next.js

@@ -20,8 +20,8 @@ const REASONS = {
     personal_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard to resume.",
     onboard_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard to resume.",
     personal_status_unavailable: "Your personal connection could not be checked. Run catalyst onboard to try again.",
-    workspace_browser_unavailable: "This computer could not open a browser. Connect Linear from this workspace’s Integrations page in your browser, then run catalyst onboard to resume.",
-    personal_browser_unavailable: "This computer could not open a browser. Finish this login’s connection from Connected accounts in your browser, then run catalyst onboard to resume.",
+    workspace_browser_unavailable: "The link to connect Linear timed out. Run catalyst setup for a new one.",
+    personal_browser_unavailable: "The link to connect your own account timed out. Run catalyst setup for a new one.",
     onboarding_capability_unavailable: "The server's setup capabilities could not be checked. Run catalyst onboard to try again.",
     onboarding_capability_identity_unverified: "The server's setup capabilities belong to another login or workspace. Sign in to the original workspace to resume.",
     onboarding_capability_login_refresh_required: "Your login needs a refresh before setup capabilities can be checked. Run catalyst login, then catalyst onboard.",
@@ -34,7 +34,10 @@ const REASONS = {
     github_installation_identity_refused: "GitHub setup belongs to another login or workspace. Sign in to the original workspace to resume.",
     github_installation_admin_required: "A workspace owner or administrator approves the GitHub App installation.",
     github_installation_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard to resume.",
-    github_installation_browser_unavailable: "This computer could not open a browser. Install the GitHub App from this workspace’s Integrations page in your browser, then run catalyst onboard to resume.",
+    github_installation_browser_unavailable: "The link to install Catalyst on GitHub timed out. Run catalyst setup for a new one.",
+    github_installation_approval_pending: "An install request is waiting on GitHub. An owner of your GitHub organization approves it there, then run catalyst setup.",
+    github_install_pending: "Runs after Catalyst is installed on GitHub.",
+    consent_timeout: "The link timed out. Run catalyst setup for a new one.",
     skills_install_unverified: "The Catalyst skills are not in this user's skills folder. Run catalyst install, then run catalyst onboard.",
     step_not_available_in_this_release: "This setup step is not available yet.",
     prerequisite_not_ready: "Waiting for an earlier setup step.",
@@ -269,13 +272,22 @@ export function onboardReasonText(step, context = {}) {
         const path = reason === "workspace_approval_required"
             ? "/settings/connections?connect=linear"
             : reason === "github_installation_approval_required"
-                ? "/settings/connections?install=github"
+                ? "/connect/github/start"
                 : `/settings/connected-accounts?connect=${step.id === "github.personal" ? "github" : "linear"}`;
         const where = context.baseUrl
             ? `${normalizeBaseUrl(context.baseUrl)}${path}`
             : "Catalyst settings";
         return `Open ${where} and approve this connection, then run catalyst onboard.`;
     }
+    // CTC-4680: only a Catalyst owner or admin can start the GitHub install (the start route refuses
+    // anyone else), so a member is told who to ask and where, on every channel.
+    if (step.id === "github.install" &&
+        (reason === "github_installation_admin_required" || reason === "member_scope"))
+        return `Only an owner or admin of your Catalyst workspace can install Catalyst on GitHub. Ask one to open ${context.baseUrl ? `${normalizeBaseUrl(context.baseUrl)}/settings/connections` : "Catalyst settings, Integrations,"} and install it there.`;
+    // An install request can sit on GitHub for good (a wrong organization, or an owner who said no),
+    // so the step always keeps a way to install it directly.
+    if (reason === "github_installation_approval_pending" && context.baseUrl)
+        return `${REASONS[reason] ?? ""} If you own the organization, or want a different one, install it at ${normalizeBaseUrl(context.baseUrl)}/connect/github/start.`;
     if (reason === "workflow_mapping_unverified")
         return `This team's workflow mapping is not verified yet. Run catalyst team adopt ${onboardTeamKey(context.journal) ?? "<TEAM KEY>"} to preview the adoption plan. Run it again with the --yes --plan-hash value it prints. Then run catalyst onboard.`;
     if (reason === "team_created_not_adopted" ||

package/dist/onboard-runner.js

@@ -639,9 +639,13 @@ export function onboardRunnerAdapter(input = {}) {
                 if (!admission.ready)
                     return mayAct && !afterAct ? pending() : waiting("runner_admission_disabled", evidence);
             }
-            const admission = await onboardTeamAdmission(ctx, p.teamKey, signal);
-            if (admission !== true)
-                return waiting(admission === false ? "runner_admission_operator" : "runner_admission_unverified", evidence);
+            else {
+                // Legacy capacity only names repo-mapped teams. The supported personal route above
+                // verifies runner admission independently of repository setup.
+                const admission = await onboardTeamAdmission(ctx, p.teamKey, signal);
+                if (admission !== true)
+                    return waiting(admission === false ? "runner_admission_operator" : "runner_admission_unverified", evidence);
+            }
             input.message?.(`This machine runs Catalyst's work as host ${name}, with ${host.capacity} slots free.`);
             return { state: "done", evidence };
         },

package/dist/onboard-runtime.js

@@ -18,7 +18,15 @@ import { onboardAccountsAdapter } from "./onboard-accounts.js";
 import { githubInstallationAdapter } from "./onboard-github.js";
 import { guardOnboardCapabilities, } from "./onboard-capabilities.js";
 import { onboardSettingsAdapter, } from "./onboard-settings.js";
+import { TIMED_OUT_REASONS } from "./setup-onboard-copy.js";
 import { fetchMe } from "./transport.js";
+const HOLD_ON_TIMEOUT = [
+    "linear.workspace",
+    "linear.personal",
+    "github.install",
+    "github.personal",
+    "accounts",
+];
 const waiting = (reason) => ({
     state: "waiting",
     reason,
@@ -136,12 +144,19 @@ export function createOnboardRuntime(args, ctx, hooks) {
         !args.json &&
         args.flags.yes !== true &&
         args.flags.headless !== true;
+    // CTC-4680 round 5: whether the step now acting ran a browser wait, so a timed-out wait can be
+    // re-offered with a fresh link instead of moving on to steps that need it.
+    let waited = false;
+    const waitFor = (message, run) => {
+        waited = true;
+        return hooks.ui.wait(message, run);
+    };
     const personalAdapter = (provider) => personalConsentAdapter({
         provider,
         openBrowser: hooks.openBrowser ?? openConsentBrowser,
         sleep: hooks.sleep,
         wait: interactiveWait
-            ? (message, run) => hooks.ui.wait(message, run)
+            ? (message, run) => waitFor(message, run)
             : undefined,
     });
     const linear = existingLinearAdapters(args, hooks.ui?.chooseTeam
@@ -218,14 +233,14 @@ export function createOnboardRuntime(args, ctx, hooks) {
             fallback: linear["linear.workspace"],
             openBrowser: hooks.openBrowser ?? openConsentBrowser,
             wait: interactiveWait
-                ? (message, work) => hooks.ui.wait(message, work)
+                ? (message, work) => waitFor(message, work)
                 : undefined,
             sleep: hooks.sleep,
         }),
         "github.install": githubInstallationAdapter({
             openBrowser: hooks.openBrowser ?? openConsentBrowser,
             wait: interactiveWait
-                ? (message, work) => hooks.ui.wait(message, work)
+                ? (message, work) => waitFor(message, work)
                 : undefined,
             sleep: hooks.sleep,
         }),
@@ -254,7 +269,7 @@ export function createOnboardRuntime(args, ctx, hooks) {
                 args.flags.yes !== true &&
                 args.flags.headless !== true
                 ? {
-                    waitForAccount: (work) => hooks.ui.wait("Waiting for a coding account", work),
+                    waitForAccount: (work) => waitFor("Waiting for a coding account", work),
                     sleep: hooks.sleep,
                 }
                 : {}),
@@ -376,6 +391,49 @@ export function createOnboardRuntime(args, ctx, hooks) {
                 message: (text) => hooks.ui ? hooks.ui.message(text) : ctx.stderr(text),
             });
     }
+    // CTC-4680 round 5: a browser link that ran out of time holds the step. The person gets a fresh
+    // link on yes; on stop the UI pauses setup, so nothing that depends on the step runs.
+    const retry = interactiveWait ? hooks.ui?.retryTimedOut?.bind(hooks.ui) : undefined;
+    if (retry)
+        for (const step of HOLD_ON_TIMEOUT) {
+            const adapter = adapters[step];
+            if (!adapter?.act)
+                continue;
+            const act = adapter.act;
+            adapters[step] = {
+                ...adapter,
+                act: async (stepCtx, journal, signal) => {
+                    for (;;) {
+                        waited = false;
+                        const result = await act(stepCtx, journal, signal);
+                        const timedOut = result.state === "waiting" &&
+                            (TIMED_OUT_REASONS.has(result.reason ?? "") ||
+                                (step === "accounts" &&
+                                    result.reason === "account_enrollment_required"));
+                        if (!timedOut || !waited || signal?.aborted || hooks.ui?.signal.aborted)
+                            return result;
+                        if (!(await retry(step)))
+                            return result;
+                    }
+                },
+            };
+        }
+    // Round 5: the runner question waits until Catalyst is on GitHub; asking it earlier left people
+    // answering later steps while nothing could work.
+    const runner = adapters.runner;
+    if (runner?.act && hooks.ui?.chooseRunner && args.flags.runner !== true && args.flags["no-runner"] !== true) {
+        const { check, act } = runner;
+        const githubPending = (journal) => {
+            const github = journal.steps.find((step) => step.id === "github.install");
+            return Boolean(github && github.state !== "done" && github.state !== "skipped");
+        };
+        // Both: the engine runs check before act, and the runner's check is where the question is asked.
+        adapters.runner = {
+            ...runner,
+            check: async (stepCtx, journal, signal) => githubPending(journal) ? waiting("github_install_pending") : check(stepCtx, journal, signal),
+            act: async (stepCtx, journal, signal) => githubPending(journal) ? waiting("github_install_pending") : act(stepCtx, journal, signal),
+        };
+    }
     // Public auth discovery and the existing /me sign-in bootstrap establish identity before the
     // tenant-bound step guards can run. Unsupported/local-only steps make no endpoint requests.
     return {

package/dist/onboard-ui.js

@@ -508,6 +508,40 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
             }
             return answer === "yes";
         },
+        async retryTimedOut(id) {
+            if (abort.signal.aborted)
+                return false;
+            if (renderer && active) {
+                // The wait frame is still live: its status and a last line say why it ended.
+                renderer.update("the link timed out");
+                renderer.detail("The link timed out.");
+            }
+            else if (renderer) {
+                renderer.begin(SETUP_NUMBERS[id] ?? 0, title(id), "the link timed out");
+                renderer.detail("The link timed out.");
+                active = true;
+            }
+            else {
+                stop();
+                prompts.log.message(`${title(id)}: the link timed out.`, {
+                    output: streams.output,
+                });
+            }
+            const answer = await select({
+                ...options,
+                message: "Ready to try again?",
+                initialValue: "again",
+                options: [
+                    { value: "again", label: "Yes, give me a new link" },
+                    { value: "stop", label: "Stop here. Run catalyst setup later to carry on." },
+                ],
+            });
+            if (prompts.isCancel(answer) || answer !== "again") {
+                abort.abort();
+                return false;
+            }
+            return true;
+        },
         stagedSigninEnd(state, cause) {
             if (!renderer)
                 return false;
@@ -847,6 +881,7 @@ export function createClackOnboardUi(prompts, streams, deps = {}) {
         delete ui.chooseFirstRepository;
         delete ui.reviewSettings;
         delete ui.chooseRunner;
+        delete ui.retryTimedOut;
         delete ui.confirmWorkflowAdoption;
     }
     return ui;

package/dist/onboard.js

@@ -6,7 +6,7 @@ import { dirname, isAbsolute, join } from "node:path";
 import { parseMachinePaths, resolveCatalystPath, } from "../vendor/paths/index.js";
 import { machinePathsFile } from "../vendor/paths/node.js";
 import { configPathFor } from "./config.js";
-import { onboardJsonView } from "./setup-onboard-copy.js";
+import { onboardJsonView, TIMED_OUT_REASONS } from "./setup-onboard-copy.js";
 import { standalonePlan, standalonePlanNotes, } from "./onboard-standalone-copy.js";
 import { CliError, UsageError } from "./errors.js";
 import { onboardFileSnapshot } from "./onboard-file-snapshot.js";
@@ -51,10 +51,11 @@ export function onboardIdentityLines(identity) {
     const person = label(display?.personLabel || identity.membershipId);
     const email = display?.email ? label(display.email) : "";
     const workspace = label(display?.workspaceName || identity.account);
-    const slug = display?.workspaceSlug ? label(display.workspaceSlug) : "";
+    // CTC-4680 (Ryan, round 2): "Signed in to Catalyst as …" and "Catalyst workspace: …", with no
+    // repeated email and no internal slug.
     return [
-        `Signed in as ${person}${email ? ` (${email})` : ""}`,
-        `Workspace: ${workspace}${slug ? ` (${slug})` : ""} · ${identity.role}`,
+        `Signed in to Catalyst as ${person}${email && email !== person ? ` (${email})` : ""}`,
+        `Catalyst workspace: ${workspace} · ${identity.role}`,
     ];
 }
 const EXIT_FAILED = 10;
@@ -1398,7 +1399,11 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
                 }
                 if (signal.aborted) {
                     const settled = journalStep(journal, id);
-                    if (settled?.state !== "done" && settled?.state !== "failed")
+                    // CTC-4680 round 5: a person who stopped at "Ready to try again?" stopped a step whose link
+                    // timed out; keep that reason so the summary says so, not "skipped for now".
+                    if (settled?.state !== "done" &&
+                        settled?.state !== "failed" &&
+                        !TIMED_OUT_REASONS.has(settled?.reason ?? ""))
                         recordStep({
                             id,
                             state: "waiting",

package/dist/ready-copy.js

@@ -0,0 +1,238 @@
+// ready-copy.ts — CTC-4680: what `catalyst ready` says about a team, in words a person can act on.
+//
+// The check ids, states and reason codes stay in `--json` (`id`) for scripts. The `line`, `fix` and
+// `who` a person reads never carry a check id, a reason code, an API route or the word "tenant", and
+// every fix is either a full URL or a step in Linear's own settings. `line` keeps its `team KEY: `
+// prefix because install.sh strips exactly that before printing a team row.
+const FIXER = {
+    oauth_scope: "owner_or_admin",
+    token_live: "owner_or_admin",
+    team_visible: "owner_or_admin_in_linear",
+    mapped_states_exist: "owner_or_admin",
+    mapping_total: "owner_or_admin",
+    types_compatible: "owner_or_admin",
+    labels_present: "nobody",
+    writes_land: "owner_or_admin",
+    webhook_covers_team: "owner_or_admin",
+    hosts_current: "host_operator",
+    environment_declared: "owner_or_admin",
+    tools_resolvable: "owner_or_admin",
+    required_values: "owner_or_admin",
+    reviewer_required: "owner_or_admin",
+    reviewer_configured: "nobody",
+    reviewer_answering: "repository_admin",
+    linear_automation_pr_open: "owner_or_admin_in_linear",
+    linear_automation_pr_review: "owner_or_admin_in_linear",
+    linear_automation_pr_ready: "owner_or_admin_in_linear",
+    linear_automation_pr_merge: "owner_or_admin_in_linear",
+    merge_queue_configured: "repository_admin",
+    coding_account_enrolled: "owner_or_admin",
+    github_app_installed: "repository_admin",
+    thoughts_reachable: "repository_admin",
+};
+const WHO = {
+    nobody: "nobody; it clears on its own",
+    owner_or_admin: "an owner or admin of your Catalyst workspace",
+    owner_or_admin_in_linear: "an admin of your Linear workspace",
+    host_operator: "whoever runs your Catalyst host",
+    repository_admin: "an admin of the team's GitHub repository",
+};
+/** Who fixes a check, as a phrase. An unknown check goes to the workspace's owners and admins. */
+export function whoFixes(checkId) {
+    return WHO[FIXER[checkId] ?? "owner_or_admin"];
+}
+const SLOT_WORDS = {
+    dispatch: "starting work",
+    intake: "intake",
+    research: "research",
+    plan: "planning",
+    implement: "writing the code",
+    remediate: "fixing review findings",
+    verify: "checking the work",
+    review: "review",
+    pr: "pull requests",
+    done: "Done",
+    canceled: "Canceled",
+};
+function wordList(items) {
+    if (items.length <= 1)
+        return items.join("");
+    return `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;
+}
+function slotList(slots) {
+    return wordList(slots.map((s) => SLOT_WORDS[s] ?? s.replaceAll("_", " ")));
+}
+function origin(baseUrl) {
+    return baseUrl.replace(/\/+$/, "");
+}
+/** The team's own page in Catalyst settings, optionally one of its sub-pages (`map`, `adopt`). */
+export function teamPage(baseUrl, key, sub) {
+    return `${origin(baseUrl)}/settings/linear-teams/${encodeURIComponent(key)}${sub ? `/${sub}` : ""}`;
+}
+/** The dispatch gate: whether Catalyst may start any ticket in the team. */
+export function dispatchGateCopy(baseUrl, key, status, missingSlots) {
+    if (status === "open")
+        return { line: `team ${key}: Catalyst can start ${key} tickets` };
+    // CTC-4708: the cloud says the mapping is saved and its copy of Linear hasn't caught up. That is a
+    // wait, not something to fix.
+    if (status === "stages_syncing")
+        return {
+            line: `team ${key}: Catalyst is still copying ${key}'s stages from Linear. It starts ${key} tickets once that finishes.`,
+        };
+    const slots = missingSlots.length > 0 ? slotList(missingSlots) : "its moves";
+    if (status === "mapping_missing")
+        return {
+            line: `team ${key}: Catalyst doesn't know which ${key} stages to use for ${slots}. Until it does, it starts no ${key} tickets.`,
+            fix: `pick them at ${teamPage(baseUrl, key, "map")}`,
+        };
+    if (status === "mapping_state_unresolved")
+        // The gate reads Catalyst's own copy of the team, which can lag Linear by a minute after a team
+        // is created or its workflow is set up (CTC-4680 Rerun A). Say that, not "map your stages".
+        return {
+            line: `team ${key}: Catalyst can't find the stages it uses for ${slots} in its copy of ${key} yet. Until it can, it starts no ${key} tickets.`,
+            fix: `if you just set up ${key}, run catalyst ready again in a minute. If this stays, press Re-check at ${teamPage(baseUrl, key)}`,
+        };
+    return {
+        line: `team ${key}: Catalyst can't start ${key} tickets yet.`,
+        fix: `open ${teamPage(baseUrl, key)} to see why`,
+    };
+}
+const AUTOMATION_RULES = {
+    linear_automation_pr_open: { rule: "On PR open", when: "when a pull request opens" },
+    linear_automation_pr_review: {
+        rule: "On PR review request or activity",
+        when: "when a pull request gets a review",
+    },
+    linear_automation_pr_ready: {
+        rule: "On PR ready for merge",
+        when: "when a pull request is ready to merge",
+    },
+    linear_automation_pr_merge: { rule: "On PR merge", when: "when a pull request merges" },
+};
+/** Plain names for checks with no sentence of their own below. */
+const CHECK_NAMES = {
+    labels_present: "Catalyst's labels in Linear",
+    writes_land: "Catalyst's changes to Linear",
+    webhook_covers_team: "events from Linear and GitHub for this team",
+    hosts_current: "your connected Catalyst hosts",
+    environment_declared: "the repository's settings file",
+    tools_resolvable: "the tools the repository's settings name",
+    reviewer_required: "the required code reviewer",
+    reviewer_configured: "a code reviewer",
+    reviewer_answering: "the code reviewer's answers",
+    merge_queue_configured: "the repository's merge queue",
+    github_app_installed: "Catalyst on GitHub",
+    thoughts_reachable: "the thoughts repository",
+};
+/** The names above that read as plural ("labels need attention"). */
+const PLURAL = new Set([
+    "labels_present",
+    "writes_land",
+    "webhook_covers_team",
+    "hosts_current",
+    "tools_resolvable",
+    "reviewer_answering",
+]);
+/** The settings page that owns each check, from the cloud's CHECK_COPY settingsPath. */
+const CHECK_PAGES = {
+    oauth_scope: "/settings/connections",
+    token_live: "/settings/connections",
+    webhook_covers_team: "/settings/projects",
+    hosts_current: "/settings/projects",
+    environment_declared: "/settings/projects",
+    tools_resolvable: "/settings/environment",
+    required_values: "/settings/projects",
+    reviewer_required: "/settings/projects",
+    reviewer_configured: "/settings/projects",
+    reviewer_answering: "/settings/projects",
+    merge_queue_configured: "/settings/projects",
+    coding_account_enrolled: "/settings/coding-accounts",
+    github_app_installed: "/settings/projects",
+    thoughts_reachable: "/settings/projects",
+};
+const AGAIN = "run catalyst ready again in a few minutes";
+/** One failing or unknown team check, in plain words. `valuesFix` is the variable-naming fix the
+ *  caller already built for `required_values`, or null when the cloud named no variable. */
+export function teamCheckCopy(baseUrl, key, id, state, valuesFix) {
+    const team = (text) => `team ${key}: ${text}`;
+    const base = origin(baseUrl);
+    const unknown = state === "unknown";
+    const automation = AUTOMATION_RULES[id];
+    if (automation)
+        return unknown
+            ? {
+                line: team(`Catalyst couldn't read ${key}'s pull request automations in Linear.`),
+                fix: AGAIN,
+            }
+            : {
+                line: team(`Linear moves ${key}'s tickets by itself ${automation.when}. That fights Catalyst, which moves them itself.`),
+                fix: `in Linear, open Settings → Teams → ${key} → Workflow → Pull request and commit automations and set "${automation.rule}" to No action, including any branch overrides. Then run catalyst ready again`,
+            };
+    switch (id) {
+        case "oauth_scope":
+            return unknown
+                ? { line: team("Catalyst couldn't check its Linear connection."), fix: `check that Linear is connected at ${base}/settings/connections` }
+                : {
+                    line: team("Catalyst's Linear connection is missing a permission it needs."),
+                    fix: `reconnect Linear at ${base}/settings/connections?reauthorize=linear`,
+                };
+        case "token_live":
+            return unknown
+                ? { line: team("Catalyst couldn't reach Linear to check its connection."), fix: AGAIN }
+                : {
+                    line: team("Linear stopped accepting Catalyst's connection. It was revoked or expired."),
+                    fix: `reconnect Linear at ${base}/settings/connections`,
+                };
+        case "team_visible":
+            return unknown
+                ? { line: team(`Catalyst hasn't confirmed it can see ${key} in Linear yet.`), fix: AGAIN }
+                : {
+                    line: team(`Catalyst can't see ${key} in Linear, usually because the team is private.`),
+                    fix: `in Linear, open Settings → API → Catalyst Cloud → Team access and add ${key}`,
+                };
+        case "mapped_states_exist":
+        case "mapping_total":
+        case "types_compatible":
+            if (unknown)
+                return { line: team(`Catalyst is still reading ${key}'s stages from Linear.`), fix: "run catalyst ready again in a minute" };
+            if (id === "mapped_states_exist")
+                return {
+                    line: team(`A stage Catalyst uses in ${key} was deleted or renamed in Linear.`),
+                    fix: `pick its replacement at ${teamPage(baseUrl, key, "map")}`,
+                };
+            if (id === "mapping_total")
+                return {
+                    line: team(`${key}'s stages aren't all mapped yet, so Catalyst doesn't know where to move its tickets.`),
+                    fix: `map them at ${teamPage(baseUrl, key, "map")}, or set up Catalyst's workflow at ${teamPage(baseUrl, key, "adopt")}`,
+                };
+            return {
+                line: team(`A stage mapped in ${key} is the wrong kind, for example a Done stage that Linear treats as in progress.`),
+                fix: `choose the right stages at ${teamPage(baseUrl, key, "map")}`,
+            };
+        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(`A variable ${key}'s repository needs has no value, so Catalyst can't run its work.`),
+                    fix: valuesFix ?? `add the missing values on the repository's Environment page: open ${base}/settings/projects, then the project, then the repository`,
+                };
+        case "coding_account_enrolled":
+            return unknown
+                ? { line: team("Catalyst couldn't check your AI accounts."), fix: AGAIN }
+                : {
+                    line: team("Catalyst has no AI account to do the work with."),
+                    fix: `run catalyst setup to add one, or add it at ${base}/settings/coding-accounts`,
+                };
+    }
+    const name = CHECK_NAMES[id] ?? id.replaceAll("_", " ");
+    const page = CHECK_PAGES[id] ?? `/settings/linear-teams/${encodeURIComponent(key)}`;
+    return unknown
+        ? { line: team(`Catalyst hasn't checked ${name} yet.`), fix: AGAIN }
+        : {
+            line: team(`${name.charAt(0).toUpperCase()}${name.slice(1)} ${PLURAL.has(id) ? "need" : "needs"} attention.`),
+            fix: `open ${base}${page}`,
+        };
+}

package/dist/ready.js

@@ -3,7 +3,7 @@
 // is a note, never a failure; the HTTP SDK loading is a check for cloud reads.
 import { accessSync, constants, existsSync, readFileSync, realpathSync, statSync, } from "node:fs";
 import { basename, delimiter, dirname, join } from "node:path";
-import { LEGACY_PACKAGE_NAME, PACKAGE_NAME, defaultSkillsDirFor, loadConfig, normalizeBaseUrl, readManifest, upgradeCommand, } from "./config.js";
+import { DEFAULT_BASE_URL, LEGACY_PACKAGE_NAME, PACKAGE_NAME, defaultSkillsDirFor, loadConfig, normalizeBaseUrl, readManifest, upgradeCommand, } from "./config.js";
 import { contractVersionInRange, readContractCache } from "./contract.js";
 import { CliError } from "./errors.js";
 import { latestPublishedVersion } from "./published.js";
@@ -15,6 +15,7 @@ import { FIRST_STAMPED_VERSION } from "./skill-shape.js";
 import { installedBundleVersion } from "./skills.js";
 import { onboardingReadyReport, observeCloudOnboarding, } from "./onboard-ready.js";
 import { selectedOnboardTeam } from "./onboard-existing.js";
+import { dispatchGateCopy, teamCheckCopy, teamPage, whoFixes } from "./ready-copy.js";
 import { onboardStatePath, readOnboardJournal } from "./onboard.js";
 export { semverOlder };
 /** `ready`'s own wording for the replica. It never recommends adopting the replica — until the
@@ -40,7 +41,7 @@ function readyReplicaLine(s) {
         case "not-configured":
             return "replica: not configured — run login first";
         case "absent":
-            return `replica: absent at ${s.dbPath} — optional, and off by default for large tenants while the snapshot path is being made safe; every read works through the API`;
+            return `replica: absent at ${s.dbPath} — optional, and off by default for large workspaces while the snapshot path is being made safe; every read works through the API`;
         case "fresh":
             return `replica: fresh at ${s.dbPath} (cursor ${s.cursor}, heartbeat ${s.heartbeatAgeMs}ms ago${s.lag !== undefined ? `, ${s.lag} behind head ${s.head}` : ""})`;
         case "stale":
@@ -132,7 +133,7 @@ function unresolvedList(v) {
 }
 function unresolvedLine(u) {
     const which = u.references.length === 1 ? "which has" : "which have";
-    return `${u.name} references ${u.references.join(", ")}, ${which} no value; the checkout refuses it before work starts`;
+    return `${u.name} refers to ${u.references.join(", ")}, ${which} no value, so Catalyst can't start work there`;
 }
 /** A team check's fix line. A check that carries `names` (CTC-3561: `required_values`, contract
  *  1.24.0) names them and where to set them. CTC-3606: it also names each `unresolved` variable and
@@ -141,24 +142,13 @@ function unresolvedLine(u) {
  *  "set". Every field is optional so an older cloud still works. Everything printed is a declared
  *  identifier or a repository name, never a value, and nothing here reads a value. Any other check
  *  keeps the generic line. */
-function teamCheckFix(label, c) {
-    const automationRules = {
-        linear_automation_pr_open: "On PR open",
-        linear_automation_pr_review: "On PR review request or activity",
-        linear_automation_pr_ready: "On PR ready for merge",
-        linear_automation_pr_merge: "On PR merge",
-    };
-    const rule = automationRules[c.id];
-    if (rule) {
-        return `in Linear, open Settings → Teams → ${label} → Workflow → Workflows & automations → Pull request and commit automations and set ${rule} to No action, including branch-specific overrides; then run catalyst team check ${label}`;
-    }
+function valuesFix(base, c) {
     const unresolved = unresolvedList(c.unresolved);
     const unresolvedNames = new Set(unresolved.map((u) => u.name));
     const names = nameList(c.names).filter((n) => !unresolvedNames.has(n));
     const parts = [];
     if (names.length > 0) {
-        parts.push(`set ${names.join(", ")} on the repository's Environment page under Settings → Your projects → the project → Repositories → the repository ` +
-            `(team ${label}; ${names.length === 1 ? "it has" : "they have"} no value at repository or account scope)`);
+        parts.push(`set ${names.join(", ")} on the repository's Environment page: open ${base}/settings/projects, then the project, then the repository`);
     }
     for (const u of unresolved)
         parts.push(unresolvedLine(u));
@@ -176,15 +166,7 @@ function teamCheckFix(label, c) {
         for (const u of repoUnresolved)
             parts.push(`in ${note.repo}, ${unresolvedLine(u)}`);
     }
-    if (parts.length === 0)
-        return `open settings for team ${label} and resolve ${c.id}`;
-    return parts.join(". ");
-}
-function whoCanAnswer(doc) {
-    const roles = doc.humans.map((h) => `${h.role} ${h.linearUserId}`);
-    return roles.length
-        ? roles.join(", ")
-        : "a tenant owner or admin (none resolved on the contract)";
+    return parts.length === 0 ? null : parts.join(". ");
 }
 export async function readyReport(ctx, deps) {
     const checks = [];
@@ -265,7 +247,7 @@ export async function readyReport(ctx, deps) {
                 id: "bundle",
                 ok: false,
                 note: true,
-                line: `bundle: ${installed} installed is older than the tenant's minimum ${minVersion} — upgrade: ${upgradeCommand()}`,
+                line: `bundle: ${installed} installed is older than your workspace's minimum ${minVersion} — upgrade: ${upgradeCommand()}`,
             });
         }
     }
@@ -394,7 +376,7 @@ export async function readyReport(ctx, deps) {
     });
     if (cache) {
         const doc = cache.doc;
-        const who = whoCanAnswer(doc);
+        const base = (cfg?.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
         for (const team of doc.teams) {
             const label = team.key ?? team.id;
             // The team's dispatch gate, straight off the cached contract: an older cloud omits it and this
@@ -404,28 +386,36 @@ export async function readyReport(ctx, deps) {
             // checked still reports its gate, which is exactly the team most likely to be unmapped.
             const dg = team.dispatchGate;
             if (dg && typeof dg.status === "string") {
-                const slots = (dg.missingSlots ?? []).join(", ");
-                checks.push(dg.status === "open"
+                // CTC-4680: the cloud's own remedy text names an API route and says "tenant", so the words
+                // come from ready-copy; the status and slots stay readable in the check id's JSON neighbours.
+                const copy = dispatchGateCopy(base, label, dg.status, dg.missingSlots ?? []);
+                checks.push(dg.status === "stages_syncing"
                     ? {
-                        id: `team:${label}:dispatchGate`,
-                        ok: true,
-                        line: `team ${label}: dispatch gate open`,
-                    }
-                    : {
                         id: `team:${label}:dispatchGate`,
                         ok: false,
-                        line: `team ${label}: dispatch gate ${dg.status}${slots ? ` (${slots})` : ""}, blocking`,
-                        fix: dg.remedy ??
-                            `open settings for team ${label} and map its stages`,
-                        who,
-                    });
+                        note: true,
+                        line: copy.line,
+                    }
+                    : dg.status === "open"
+                        ? {
+                            id: `team:${label}:dispatchGate`,
+                            ok: true,
+                            line: copy.line,
+                        }
+                        : {
+                            id: `team:${label}:dispatchGate`,
+                            ok: false,
+                            line: copy.line,
+                            ...(copy.fix ? { fix: copy.fix } : {}),
+                            who: whoFixes("mapping_total"),
+                        });
             }
             if (team.readiness.status === "unchecked") {
                 checks.push({
                     id: `team:${label}`,
                     ok: true,
                     note: true,
-                    line: `team ${label}: readiness not checked yet`,
+                    line: `team ${label}: Catalyst hasn't checked this team yet`,
                 });
                 continue;
             }
@@ -441,13 +431,14 @@ export async function readyReport(ctx, deps) {
             for (const c of bad) {
                 const meta = doc.readinessChecks.find((r) => r.id === c.id);
                 const needsAnswer = meta?.needsAnswer ?? true;
+                const copy = teamCheckCopy(base, label, c.id, c.state === "fail" ? "fail" : "unknown", valuesFix(base, c));
                 checks.push({
                     id: `team:${label}:${c.id}`,
                     ok: !needsAnswer && c.state !== "fail",
                     note: !needsAnswer,
-                    line: `team ${label}: ${c.id} is ${c.state}${c.reason ? ` (${c.reason}${c.count !== undefined ? ` ×${c.count}` : ""})` : ""}${meta ? `, ${meta.severity}` : ""}`,
-                    fix: teamCheckFix(label, c),
-                    who: needsAnswer ? who : "nobody yet; it is informational",
+                    line: copy.line,
+                    ...(copy.fix ? { fix: copy.fix } : {}),
+                    who: needsAnswer ? whoFixes(c.id) : "nobody yet; it is informational",
                 });
             }
             if (bad.length === 0 && team.readiness.status !== "ready") {
@@ -455,9 +446,11 @@ export async function readyReport(ctx, deps) {
                     id: `team:${label}`,
                     ok: team.readiness.status !== "blocked",
                     note: team.readiness.status === "degraded",
-                    line: `team ${label}: ${team.readiness.status}`,
-                    fix: `open settings for team ${label}`,
-                    who,
+                    line: team.readiness.status === "degraded"
+                        ? `team ${label}: works, with some optional settings still missing`
+                        : `team ${label}: not ready for work yet`,
+                    fix: `open ${teamPage(base, label)}`,
+                    who: whoFixes("mapping_total"),
                 });
             }
         }

package/dist/setup-onboard-copy.js

@@ -47,6 +47,16 @@ export const CONNECTION_REPAIR_REASONS = new Set([
     "github_app_permissions_unverified", "github_app_repository_access_unverified",
     "linear_workspace_permissions_unverified", "personal_permissions_unverified",
 ]);
+/** CTC-4680: the signed-in browser route that goes straight to GitHub's install page. The settings
+ *  page it replaces opened Integrations and started nothing. */
+export const GITHUB_INSTALL_START = "/connect/github/start";
+/** CTC-4680 round 5: a browser wait that ran its whole window without the person finishing. */
+export const TIMED_OUT_REASONS = new Set([
+    "consent_timeout",
+    "workspace_browser_unavailable",
+    "personal_browser_unavailable",
+    "github_installation_browser_unavailable",
+]);
 const clean = (s) => s.replace(/[\u0000-\u001f\u007f]/g, "").slice(0, 300);
 function value(step, key) {
     const v = step.evidence?.[key];
@@ -114,6 +124,10 @@ function unfinished(step) {
         return "could not read them; checked again before work starts";
     if (step.reason === "interrupted")
         return "skipped for now";
+    if (TIMED_OUT_REASONS.has(step.reason ?? ""))
+        return "the link timed out";
+    if (step.reason === "github_installation_approval_pending")
+        return "waiting for an owner of your GitHub organization";
     if (step.state === "failed")
         return "could not finish this step";
     switch (step.id) {
@@ -143,6 +157,7 @@ export function setupStepView(step, journal, required = false) {
         : step.state === "failed"
             ? "fail"
             : step.reason === "prerequisite_not_ready" ||
+                step.reason === "github_install_pending" ||
                 (step.state === "pending" && !step.reason)
                 ? "later"
                 : !required &&
@@ -160,6 +175,8 @@ export function setupStepView(step, journal, required = false) {
                 .map((id) => SETUP_NUMBERS[id])
                 .filter((n) => n !== undefined)),
         ];
+        if (step.reason === "github_install_pending")
+            numbers.splice(0, numbers.length, SETUP_NUMBERS["github.install"]);
         outcome =
             step.state === "pending" && !step.reason
                 ? "not checked yet"
@@ -188,7 +205,8 @@ function page(base, path) {
     }
 }
 function action(step, base, journal) {
-    if (CONNECTION_REPAIR_REASONS.has(step.reason ?? ""))
+    if (CONNECTION_REPAIR_REASONS.has(step.reason ?? "") ||
+        step.reason === "github_installation_approval_pending")
         return onboardReasonText(step, { baseUrl: base, journal });
     const link = (path, verb) => {
         const url = page(base, path);
@@ -202,7 +220,12 @@ function action(step, base, journal) {
         case "linear.personal":
             return link("/settings/connected-accounts?connect=linear", "connect your Linear account");
         case "github.install":
-            return link("/settings/connections?install=github", "install Catalyst on your GitHub organization");
+            // The start route answers 403 to anyone but an owner or admin, so a member gets the
+            // Integrations page and who to ask instead.
+            if (step.reason === "github_installation_admin_required" ||
+                step.reason === "member_scope")
+                return onboardReasonText(step, { baseUrl: base, journal });
+            return link(GITHUB_INSTALL_START, "install Catalyst on your GitHub organization");
         case "github.personal":
             return link("/settings/connected-accounts?connect=github", "connect your GitHub account");
         case "accounts":
@@ -317,7 +340,7 @@ export function setupBrowserInstruction(id, base, opened = false) {
             "Connect your Linear account",
         ],
         "github.install": [
-            "/settings/connections?install=github",
+            GITHUB_INSTALL_START,
             "install Catalyst on your GitHub organization",
             "Install Catalyst on your GitHub organization",
         ],
@@ -386,6 +409,8 @@ export function onboardJsonView(journal, base, paused = false, options = {}) {
         const step = view.steps.find((step) => step.id === action.id);
         const role = view.steps.find((step) => step.id === "signin" && step.state === "done")?.evidence?.role;
         const admin = step.reason === "member_scope" ||
+            // CTC-4680: refused by the person's Catalyst role, not by GitHub, so a workspace admin acts.
+            step.reason === "github_installation_admin_required" ||
             step.reason?.endsWith("_identity_unverified") ||
             (action.id === "accounts" && role !== "owner" && role !== "admin");
         const url = action.text

package/dist/setup-render.js

@@ -86,7 +86,9 @@ export function createSetupRenderer(stream, env) {
         .replace(/\u001b\]8;;[^\u001b]*\u001b\\/g, "")
         .replace(/\u001b\[[0-9;]*m/g, "");
     const rail = traits.unicode ? "│" : "";
-    const titleCol = traits.unicode ? 6 : 11;
+    // CTC-4680: details sit 4 columns in (under the rail in Unicode), not under the step title at 6 or
+    // 11, so the eye doesn't travel across a small screen to read them.
+    const titleCol = 4;
     const outcomeCol = traits.unicode ? 38 : 43;
     const prefix = (col) => rail + " ".repeat(col - rail.length);
     const mark = (kind) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@catalyst-cloud/cli",
-  "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.",
+  "version": "0.15.2",
+  "description": "Set up Catalyst Cloud, check your tickets and manage your account from the command line.",
   "license": "MIT",
   "type": "module",
   "publishConfig": {

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.0 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.2 — written in this repository for customer accounts -->
 
 # Catalyst's GitHub
 

package/skills/catalyst-linear/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's view of Linear on the customer's own cloud account. Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the cloud API by default, with local replica reads available as an explicit opt-in, always naming the source; searches tickets, PRs, projects and initiatives; writes comments, card moves, labels and new tickets through the account's agent proxy as the app actor, with every route, stage id, label id and marker read from the account's contract. Knows what a ticket accumulates as Catalyst works it (phase-outcome comments, the document per phase, the agent session, the labels, the single blocks relation, the bookkeeping marker, the eyes acknowledgement). Use when a person says "show me the ticket", "what did Catalyst write on it", "comment on it", "move it", "label it" or "file a ticket". Not for raising a decision for a human (what-needs-me) and not for pull requests (catalyst-github).
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.0 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.2 — written in this repository for customer accounts -->
 
 # Catalyst Linear
 

package/skills/catalyst-onboard/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Set up Catalyst Cloud and say whether setup is working. Walks a person from nothing to their first ticket running, one step at a time: the coding account, the project, the integrations and connected accounts, each repository's settings file, then one real ticket moving. Also logs this machine in, reads the readiness verdict with who can fix each failure, and checks the optional local replica. Use when someone says "set me up", "onboard me", "I just signed up", "get me started", "what do I do first", "log me in", "which account is this machine on", "am I set up", "what is missing", "why does nothing happen" or "is the replica running", when a login expired, or when a skill script exits 2 saying this machine is not connected. Does every step a key can do through the catalyst CLI, hands over the exact page for the steps only a browser can do, and never claims a step it did not watch succeed.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.0 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.2 — written in this repository for customer accounts -->
 
 # Onboard me
 

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

@@ -140,7 +140,8 @@ const field = (name) => {
   const line = statusLines.find((l) => l.startsWith(`${name}:`));
   return line ? line.slice(name.length + 1).trim() : null;
 };
-const tenant = field("Tenant");
+// A newer CLI prints "Catalyst workspace:"; an older one prints "Tenant:".
+const tenant = field("Catalyst workspace") ?? field("Tenant");
 const api = field("API");
 const connected = tenant !== null && tryLoadConfig() !== null;
 // The app and the API share an origin; the base URL is whatever this machine was connected to, so

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