@catalyst-cloud/cli 0.15.2 → 0.15.4

package/dist/onboard-next.js

@@ -1,20 +1,28 @@
 import { nativeEgressInstallCommands } from "./onboard-runner-egress.js";
-import { loadConfig, normalizeBaseUrl } from "./config.js";
+import { INSTALL_COMMAND, loadConfig, normalizeBaseUrl } from "./config.js";
 import { githubInstallationPage } from "./onboard-permissions.js";
+import { valuesFacts, valuesFix } from "./ready-copy.js";
 /** What a person reads for a step that is not done. Each line ends in an action they can take. */
 const REASONS = {
-    account_identity_unverified: "Your login changed while coding accounts were checked. Run catalyst onboard again to verify your person and workspace.",
-    account_inventory_unavailable: "Coding accounts could not be read. Run catalyst onboard again to retry.",
-    account_inventory_unverified: "The server did not return a fresh supported coding-account list. Run catalyst onboard after the server update.",
-    coding_account_not_found: "The coding account named by --coding-account is not enrolled in this workspace. Run catalyst accounts to list the slots, then run catalyst onboard with one of them.",
-    account_validation_admin_required: "An administrator must check the workspace's coding-account access.",
+    account_identity_unverified: "Your login changed while AI accounts were checked. Run catalyst onboard again to verify your person and workspace.",
+    account_inventory_unavailable: "AI accounts could not be read. Run catalyst onboard again to retry.",
+    account_inventory_unverified: "The server did not return a fresh supported AI account list. Run catalyst onboard after the server update.",
+    connect_checklist_refused: "Catalyst refused to show this login the Connect accounts page's status. Sign in again with catalyst login, then run catalyst onboard.",
+    connect_checklist_identity_unverified: "Your login changed while setup was checking the Connect accounts page. Run catalyst onboard again to verify your person and workspace.",
+    coding_account_inactive: "The AI account named by --coding-account is turned off. Turn it on in the workspace's AI account settings, then run catalyst onboard.",
+    coding_account_ended: "The AI account named by --coding-account was removed or its access has ended. Name another one with --coding-account, or add one in the workspace's AI account settings.",
+    coding_account_needs_login: "The AI account named by --coding-account needs its key added again. Replace it in the workspace's AI account settings, then run catalyst onboard.",
+    coding_account_quarantined: "The AI account named by --coding-account is held after repeated failures. Check it in the workspace's AI account settings, then run catalyst onboard.",
+    coding_account_walled: "The AI account named by --coding-account has used its usage limit for now. Check when it resets, then run catalyst onboard again.",
+    coding_account_not_found: "The AI account named by --coding-account is not in this workspace. Run catalyst accounts to list the slots, then run catalyst onboard with one of them.",
+    account_validation_admin_required: "An administrator must check the workspace's AI account access.",
     account_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard.",
     account_validation_unavailable: "The provider check could not finish. Run catalyst onboard again to retry.",
     account_validation_unverified: "The server did not return a fresh provider check. Run catalyst onboard after the server update.",
-    account_provider_access_unverified: "Coding-account provider access is not freshly verified. Check the account in the workspace's coding-account settings, then resume setup.",
+    account_provider_access_unverified: "AI account access is not freshly verified. Check the account in the workspace's AI account settings, then resume setup.",
     codex_provider_access_unverified: "Codex credentials are stored, but provider access is not freshly verified. Setup did not refresh or rotate the Codex login.",
     account_provider_walled: "Claude's usage limit is spent for now. Check the account's reset time, then run catalyst onboard again.",
-    account_provider_rejected: "Claude refused the stored login. Replace it in the workspace's coding-account settings, then resume setup.",
+    account_provider_rejected: "Claude refused the stored login. Replace it in the workspace's AI account settings, then resume setup.",
     personal_consent_handoff: "The browser approval link could not be verified. Run catalyst onboard to try again.",
     personal_identity_refused: "Your current login no longer matches this setup. Resume with the original workspace and person.",
     personal_login_refresh_required: "Renew your login with catalyst login, then run catalyst onboard to resume.",
@@ -44,6 +52,7 @@ const REASONS = {
     local_sync_not_selected: "Using cloud reads. Local sync was not selected.",
     local_sync_capability_unavailable: "Local sync was selected but could not be verified.",
     member_scope: "Your workspace administrator handles this step.",
+    member_team_required: "Setup needs your Linear team to check what Catalyst can work on. Run catalyst setup again with --team <KEY>, using your team's key from Linear.",
     onboarding_checks_pending: "Some required checks are still unverified.",
     interrupted: "Setup paused. Run the same command to resume.",
     signin_timeout: "Sign-in timed out. Run catalyst onboard to try again.",
@@ -138,7 +147,15 @@ 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.",
+    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.",
+    housekeeping_off_chosen: "The daily update is off, as you chose when you installed. It is optional. catalyst says when an update is out.",
+    housekeeping_no_scheduler: "The daily update can't run on this computer: it needs launchd on macOS or systemd --user on Linux. It is optional. catalyst says when an update is out.",
+    housekeeping_not_loaded: "The daily update is installed but not turned on. Run launchctl load ~/Library/LaunchAgents/dev.catalystcloud.housekeeping.plist to turn it on.",
+    housekeeping_not_enabled: "The daily update is installed but not turned on. Run systemctl --user enable --now catalyst-housekeeping.timer to turn it on.",
+    housekeeping_not_scheduled: `The daily update is not scheduled on this computer. Run the installer again to schedule it: ${INSTALL_COMMAND} -s -- --housekeeping yes`,
 };
 /** The saved login's web address, or nothing when the config is missing, unreadable or not http(s). */
 export function savedOnboardBaseUrl(home) {
@@ -261,6 +278,26 @@ export function onboardStepDetail(step) {
         : undefined;
     return granted ? `granted ${granted}` : undefined;
 }
+/** The dispatch stage's name as the contract gave it, or what it does when unknown. */
+export function dispatchStageName(value) {
+    return typeof value === "string" && /^[\p{L}\p{N}][\p{L}\p{N} ._&'()-]{0,59}$/u.test(value)
+        ? value
+        : "the stage that starts Catalyst's work";
+}
+function firstTicketText(reason, key, stage) {
+    const move = `move one of ${key ? `${key}'s` : "your team's"} tickets to ${dispatchStageName(stage)} in Linear`;
+    switch (reason) {
+        case "first_ticket_choice_required":
+            return `${move.charAt(0).toUpperCase()}${move.slice(1)}. Catalyst picks it up next.`;
+        case "first_ticket_move_refused":
+            return `Catalyst could not move the ticket for you. Ask a Catalyst owner or admin to check its Linear connection, or ${move} yourself.`;
+        case "first_ticket_unavailable":
+            return `Setup could not read or move the team's tickets. Run catalyst setup to try again, or ${move} yourself.`;
+        case "first_ticket_unverified":
+            return `Setup could not confirm which ticket moved. Check ${dispatchStageName(stage)} in Linear before choosing again.`;
+    }
+    return undefined;
+}
 /** One step's next action. `waitsFor` names the unfinished step a prerequisite wait is blocked on. */
 export function onboardReasonText(step, context = {}) {
     const reason = step.reason ?? "";
@@ -284,6 +321,36 @@ export function onboardReasonText(step, context = {}) {
     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.`;
+    if (reason === "admin_setup_pending") {
+        const words = {
+            "linear.workspace": "connect Linear",
+            "github.install": "install Catalyst on GitHub",
+            "linear.adopt": "set up the team's Catalyst workflow",
+        };
+        const left = String(step.evidence?.admin ?? "")
+            .split(",")
+            .flatMap((id) => (words[id] ? [words[id]] : []));
+        const list = left.length > 1 ? `${left.slice(0, -1).join(", ")} and ${left.at(-1)}` : (left[0] ?? "finish setup");
+        return `A Catalyst owner or admin still has to ${list}. Ask one to open ${context.baseUrl ? `${normalizeBaseUrl(context.baseUrl)}/settings/connections` : "Catalyst settings"}, then run catalyst setup.`;
+    }
+    // A member is told which admin action is left and where an admin takes it.
+    if (reason === "member_scope") {
+        const key = onboardTeamKey(context.journal);
+        const adminOnly = {
+            "linear.workspace": ["connect Linear", "/settings/connections", " and connect it there"],
+            "linear.adopt": [
+                "set up the team's Catalyst workflow",
+                key ? `/settings/linear-teams/${encodeURIComponent(key)}/adopt` : "/settings/linear-teams",
+                "",
+            ],
+        };
+        const admin = adminOnly[step.id];
+        if (admin) {
+            const [what, path, rest] = admin;
+            const url = context.baseUrl ? `${normalizeBaseUrl(context.baseUrl)}${path}` : "Catalyst settings";
+            return `Only a Catalyst owner or admin can ${what}. Ask one to open ${url}${rest}.`;
+        }
+    }
     // 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)
@@ -302,11 +369,22 @@ export function onboardReasonText(step, context = {}) {
         if (team)
             return `Setup could not confirm whether Linear created the team ${team}. Check Linear for it. If it is there: ${adopt(team)} If it is not, run catalyst onboard to create it again.`;
     }
+    if (reason === "ai_account_not_usable") {
+        const where = context.baseUrl
+            ? `at ${normalizeBaseUrl(context.baseUrl)}/settings/coding-accounts`
+            : "in the web app on the Settings → AI accounts page";
+        return `No AI account in this workspace can take work yet. A workspace owner or administrator checks them ${where}: one may need its key replaced, or may have reached its usage limit. Then run catalyst onboard.`;
+    }
     if (reason === "account_enrollment_required") {
         const where = context.baseUrl
             ? `at ${normalizeBaseUrl(context.baseUrl)}/settings/coding-accounts, the Settings → AI accounts page`
             : "in the web app on the Settings → AI accounts page";
-        return `No coding account is enrolled. A workspace owner or administrator adds one ${where}. A Claude account needs its email and the token printed by \`claude setup-token\`. Then run catalyst onboard.`;
+        // CTC-4716: subscriptions are offered only to a workspace the cloud enables for them.
+        const kinds = step.evidence?.aiAccountKinds;
+        const what = typeof kinds === "string" && kinds.split(",").includes("subscription")
+            ? "an API key, billed per token, or a subscription, a fixed monthly plan"
+            : "an API key, billed per token";
+        return `No AI account is added yet. A workspace owner or administrator adds one ${where}: ${what}. Then run catalyst onboard.`;
     }
     if (reason === "automation_management_unavailable") {
         const conflicts = typeof step.evidence?.automations === "string" &&
@@ -357,6 +435,27 @@ 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.`;
+    if (reason === "required_values_missing") {
+        let facts;
+        try {
+            facts = JSON.parse(String(step.evidence?.requiredValues ?? "null"));
+        }
+        catch {
+            facts = null;
+        }
+        const fix = valuesFix(context.baseUrl, valuesFacts(facts)) ??
+            valuesFix(context.baseUrl, { names: ["the missing values"] });
+        // A member cannot set a value; the line says who does, and still never prints one.
+        const member = context.journal?.steps.find((row) => row.id === "signin")?.evidence?.role === "member";
+        if (member)
+            return fix.startsWith("set ")
+                ? `Ask a Catalyst owner or admin to ${fix}. Then run catalyst setup.`
+                : `${fix.charAt(0).toUpperCase()}${fix.slice(1)}. Ask a Catalyst owner or admin to fix it, then run catalyst setup.`;
+        return `${fix.charAt(0).toUpperCase()}${fix.slice(1)}. Then run catalyst setup.`;
+    }
+    const firstTicket = firstTicketText(reason, onboardTeamKey(context.journal), step.evidence?.stage);
+    if (step.id === "first-ticket" && firstTicket)
+        return firstTicket;
     if (reason === "prerequisite_not_ready" && context.waitsFor)
         return `Runs after "${context.waitsFor}".`;
     const permission = permissionText(step, context.baseUrl);

package/dist/onboard-ready.js

@@ -1,5 +1,6 @@
 import { loadConfig } from "./config.js";
 import { loadContract } from "./contract.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;
 function cleanCheck(check) {
@@ -32,6 +33,66 @@ export async function onboardingReadyReport(ctx, deps) {
         : required.length === 0 || required.some(check => check.state === "unknown") || work.state === "unknown" ? "unknown" : "complete";
     return { schema: 1, readMode: deps.localSync ? "local" : "cloud", state, checks, work };
 }
+/** Team check outcomes that do not hold setup's readiness, as `check:reason`: the cloud's four
+ * WAITING_PAIRS (nothing has happened yet before a first ticket: a webhook delivery, a write, a host
+ * attaching, a reviewer's first answer), plus two of setup's own. A missing value is the values
+ * step's action; a reference with no value is not here, because the checkout refuses it before any
+ * work starts. A team with no reviewer still runs. */
+const READY_EXEMPT = new Set([
+    "webhook_covers_team:delivery_window_empty",
+    "writes_land:no_write_observed",
+    "hosts_current:no_host_connected",
+    "reviewer_answering:reviewer_not_yet_answered",
+    "required_values:required_value_missing",
+    "reviewer_configured:no_reviewer_configured",
+]);
+/** Admin-owned steps a member's run skips, and the team checks that show an admin finished them. A
+ * member's skip is not a finished setup: readiness holds until these checks pass. */
+const ADMIN_OWNED = [
+    ["linear.workspace", ["oauth_scope", "token_live"]],
+    ["github.install", ["github_app_installed"]],
+    ["linear.adopt", ["mapping_total", "mapped_states_exist"]],
+];
+/** The setup step's verdict. Every required step must be satisfied, and every required check must
+ * pass or be one of the exempt outcomes above. A failing check fails; anything else unread (a stale
+ * or unverified team, a check the cloud could not read, the cloud itself) waits. Work nobody can
+ * observe yet does not hold it. */
+export function onboardReadyStep(report, journal) {
+    const evidence = {
+        checks: report.checks.length,
+        passed: report.checks.filter((check) => check.state === "pass").length,
+    };
+    const failedStep = (journal?.steps ?? []).some((step) => step.id !== "ready" &&
+        !ONBOARD_DEFERRED_STEPS.has(step.id) &&
+        step.state === "failed");
+    if (onboardRequiredStepsWaiting(journal) || failedStep)
+        return { state: "waiting", reason: "onboarding_checks_pending", evidence };
+    const skipped = (id) => journal?.steps.some((step) => step.id === id && step.state === "skipped" && step.reason === "member_scope");
+    // A member's plain run has no team, so nothing can show what an admin finished.
+    if (skipped("linear.team"))
+        return { state: "waiting", reason: "member_team_required", evidence };
+    // Only a check read from a fresh team (`team.<id>.<check>`) that fails counts. An absent, stale or
+    // unknown one (an outage, a workflow just adopted) says nothing about the admin step, so it falls
+    // through to the waits below.
+    const read = new Map(report.checks
+        .filter((check) => /^team\.[^.]+\.[a-z0-9_]+$/.test(check.id))
+        .map((check) => [check.id.split(".")[2], check.state]));
+    const adminLeft = ADMIN_OWNED.filter(([id, checks]) => skipped(id) && checks.some((check) => read.get(check) === "fail")).map(([id]) => id);
+    if (adminLeft.length)
+        return { state: "waiting", reason: "admin_setup_pending", evidence: { ...evidence, admin: adminLeft.join(",") } };
+    const open = report.checks.filter((check) => {
+        if (!check.required || check.state === "pass")
+            return false;
+        // `team.<id>.<check>` is one team check; `team.<id>` alone is the team's whole check list.
+        const parts = check.id.split(".");
+        return !(parts[0] === "team" && parts.length === 3 && READY_EXEMPT.has(`${parts[2]}:${check.reason}`));
+    });
+    if (open.some((check) => check.state === "fail"))
+        return { state: "failed", reason: "onboarding_checks_pending", evidence };
+    if (open.length)
+        return { state: "waiting", reason: "onboarding_checks_pending", evidence };
+    return { state: "done", evidence };
+}
 /** The current contract exposes checked project setup, but not fresh starter-ticket proof. */
 export async function observeCloudOnboarding(ctx, scope = {}) {
     const cfg = loadConfig(ctx.home);

package/dist/onboard-runtime.js

@@ -15,7 +15,11 @@ import { onboardRunnerAdapter } from "./onboard-runner.js";
 import { onboardAutomationManagementAdapter } from "./onboard-automation-management.js";
 import { onboardWorkflowVerificationAdapter } from "./onboard-workflow.js";
 import { onboardAccountsAdapter } from "./onboard-accounts.js";
+import { onboardFirstTicketAdapter } from "./onboard-first-ticket.js";
+import { onboardValuesAdapter } from "./onboard-values.js";
 import { githubInstallationAdapter } from "./onboard-github.js";
+import { connectChecklistAdapter, } from "./onboard-checklist.js";
+import { onboardHousekeepingAdapter, } from "./onboard-housekeeping.js";
 import { guardOnboardCapabilities, } from "./onboard-capabilities.js";
 import { onboardSettingsAdapter, } from "./onboard-settings.js";
 import { TIMED_OUT_REASONS } from "./setup-onboard-copy.js";
@@ -147,9 +151,21 @@ export function createOnboardRuntime(args, ctx, hooks) {
     // 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) => {
+    const waitFor = (message, run, page) => {
         waited = true;
-        return hooks.ui.wait(message, run);
+        return hooks.ui.wait(message, run, page);
+    };
+    // CTC-4680: the Connect accounts page opens once per run, whichever step needs it first.
+    const connectPage = { openedBy: null };
+    const checklistOptions = {
+        openBrowser: hooks.openBrowser ?? openConsentBrowser,
+        wait: interactiveWait
+            ? (message, work, page) => waitFor(message, work, page)
+            : undefined,
+        note: (text) => hooks.ui?.note ? hooks.ui.note(text) : hooks.ui ? hooks.ui.message(text) : ctx.stderr(text),
+        sleep: hooks.sleep,
+        page: connectPage,
+        cache: { last: null },
     };
     const personalAdapter = (provider) => personalConsentAdapter({
         provider,
@@ -237,12 +253,17 @@ export function createOnboardRuntime(args, ctx, hooks) {
                 : undefined,
             sleep: hooks.sleep,
         }),
-        "github.install": githubInstallationAdapter({
-            openBrowser: hooks.openBrowser ?? openConsentBrowser,
-            wait: interactiveWait
-                ? (message, work) => waitFor(message, work)
-                : undefined,
-            sleep: hooks.sleep,
+        "github.install": connectChecklistAdapter({
+            ...checklistOptions,
+            step: "github.install",
+            item: "github-app",
+            fallback: githubInstallationAdapter({
+                openBrowser: hooks.openBrowser ?? openConsentBrowser,
+                wait: interactiveWait
+                    ? (message, work) => waitFor(message, work)
+                    : undefined,
+                sleep: hooks.sleep,
+            }),
         }),
         settings: onboardSettingsAdapter({
             ...hooks.settings,
@@ -262,21 +283,23 @@ export function createOnboardRuntime(args, ctx, hooks) {
                 : undefined,
             message: (text) => (hooks.ui ? hooks.ui.message(text) : ctx.stderr(text)),
         }),
-        accounts: onboardAccountsAdapter({
-            ...(hooks.ui &&
-                hooks.ui.interactive !== false &&
-                !args.json &&
-                args.flags.yes !== true &&
-                args.flags.headless !== true
-                ? {
-                    waitForAccount: (work) => waitFor("Waiting for a coding account", work),
-                    sleep: hooks.sleep,
-                }
-                : {}),
-            message: (text) => (hooks.ui ? hooks.ui.message(text) : ctx.stderr(text)),
-            ...(typeof args.flags["coding-account"] === "string"
-                ? { slot: args.flags["coding-account"] }
-                : {}),
+        accounts: connectChecklistAdapter({
+            ...checklistOptions,
+            step: "accounts",
+            item: "ai-account",
+            // A named account is checked on its own: the checklist answers for the whole workspace.
+            enabled: typeof args.flags["coding-account"] !== "string",
+            fallback: onboardAccountsAdapter({
+                ...(interactiveWait
+                    ? {
+                        waitForAccount: (work) => waitFor("Waiting for an AI account", work),
+                        sleep: hooks.sleep,
+                    }
+                    : {}),
+                ...(typeof args.flags["coding-account"] === "string"
+                    ? { slot: args.flags["coding-account"] }
+                    : {}),
+            }),
         }),
         capacity: onboardCapacityAdapter({
             message: (text) => (hooks.ui ? hooks.ui.message(text) : ctx.stderr(text)),
@@ -315,9 +338,14 @@ export function createOnboardRuntime(args, ctx, hooks) {
                     evidence: { provider: "cloud" },
                 },
         },
-        housekeeping: {
-            check: async () => waiting("housekeeping_service_unverified"),
-        },
+        housekeeping: onboardHousekeepingAdapter(hooks.scheduler),
+        values: onboardValuesAdapter(),
+        // Only a person at a terminal picks a ticket; --yes, JSON and headless runs leave it waiting.
+        "first-ticket": onboardFirstTicketAdapter(interactiveWait && hooks.ui?.chooseFirstTicket
+            ? {
+                choose: (tickets, where) => hooks.ui.chooseFirstTicket(tickets.map((ticket) => ({ ...ticket })), { ...where }),
+            }
+            : {}),
         ready: { check: hooks.ready },
     };
     const get = (path) => ({ method: "GET", path });
@@ -377,6 +405,10 @@ export function createOnboardRuntime(args, ctx, hooks) {
             check: [get("/api/v1/repos"), get("/api/v1/agent/contract")],
             fallback: "connections",
         },
+        values: {
+            check: [get("/api/v1/agent/contract")],
+            fallback: "connections",
+        },
         ready: {
             check: [get("/api/v1/agent/contract")],
             fallback: "connections",
@@ -409,7 +441,8 @@ export function createOnboardRuntime(args, ctx, hooks) {
                         const timedOut = result.state === "waiting" &&
                             (TIMED_OUT_REASONS.has(result.reason ?? "") ||
                                 (step === "accounts" &&
-                                    result.reason === "account_enrollment_required"));
+                                    (result.reason === "account_enrollment_required" ||
+                                        result.reason === "ai_account_not_usable")));
                         if (!timedOut || !waited || signal?.aborted || hooks.ui?.signal.aborted)
                             return result;
                         if (!(await retry(step)))

package/dist/onboard-standalone-copy.js

@@ -1,60 +1,36 @@
-import { setupStepView, SETUP_NUMBERS } from "./setup-onboard-copy.js";
+import { setupPartHeading, setupStepView, SETUP_NUMBERS, SETUP_PART_NUMBERS, SETUP_PART_OF, } from "./setup-onboard-copy.js";
 export const COMPUTER_CHECKS = ["machine", "cli", "skills", "legacy"];
 const PLAN = [
     ["On this computer", "signin", "you approve once in your browser"],
-    [
-        "On this computer",
-        "housekeeping",
-        "schedule the daily update, where supported",
-    ],
-    [
-        "In Linear and GitHub",
-        "linear.workspace",
-        "an admin connects the workspace",
-    ],
-    [
-        "In Linear and GitHub",
-        "linear.personal",
-        "you connect your own Linear account",
-    ],
+    ["On this computer", "housekeeping", "schedule the daily update"],
+    ["In Linear and GitHub", "linear.workspace", "an admin connects the workspace"],
+    ["In Linear and GitHub", "linear.personal", "you connect your own Linear account"],
     ["In Linear and GitHub", "linear.team", "you choose the team"],
-    [
-        "In Linear and GitHub",
-        "linear.adopt",
-        "review any states and labels to add",
-    ],
-    [
-        "In Linear and GitHub",
-        "linear.automations",
-        "check how pull requests change issue states",
-    ],
-    [
-        "In Linear and GitHub",
-        "github.install",
-        "an admin chooses access on GitHub",
-    ],
-    [
-        "In Linear and GitHub",
-        "github.personal",
-        "you connect your own GitHub account",
-    ],
-    [
-        "In Linear and GitHub",
-        "github.repos",
-        "you choose where Catalyst can work",
-    ],
-    ["Work", "accounts", "check a coding account"],
+    ["In Linear and GitHub", "linear.adopt", "review any states and labels to add"],
+    ["In Linear and GitHub", "linear.automations", "check how pull requests change issue states"],
+    ["In Linear and GitHub", "github.install", "an admin chooses access on GitHub"],
+    ["In Linear and GitHub", "github.personal", "you connect your own GitHub account"],
+    ["In Linear and GitHub", "github.repos", "you choose where Catalyst can work"],
+    ["Work", "accounts", "check an AI account"],
     ["Work", "capacity", "check which runners can take work"],
     ["Work", "settings", "you review settings before saving them"],
+    ["Work", "values", "check every value the repositories need has one"],
     ["Work", "first-ticket", "you choose a ticket to start"],
 ];
-export function standalonePlan(journal, scope, runnerSelected = false) {
+/**
+ * The plan's rows. `parts` is what the terminal draws: part headings, numbers restarting in each
+ * 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") {
+    const json = numbering === "json";
     const includes = (id) => !scope || scope.includes(id);
     const steps = new Map(journal.steps.map((step) => [step.id, step]));
     const rows = [];
     if (COMPUTER_CHECKS.some((id) => includes(id)))
         rows.push({
-            group: "On this computer",
+            group: json ? "On this computer" : setupPartHeading(1, false),
+            part: 1,
             number: 1,
             title: "Check this computer",
             detail: includes("legacy")
@@ -62,9 +38,31 @@ export function standalonePlan(journal, scope, runnerSelected = false) {
                 : "check the selected machine requirements",
         });
     for (const [group, id, detail] of PLAN) {
+        // The terminal gives this computer's runner its own row after "Check runners". The plain-text
+        // plan keeps it folded into that row, under the number JSON reports for both.
+        if (!json && id === "capacity") {
+            const row = (step, text) => rows.push({
+                group: setupPartHeading(3, false),
+                part: 3,
+                number: SETUP_PART_NUMBERS[step],
+                title: setupStepView({ id: step, state: "pending" }).title,
+                detail: steps.get(step)?.state === "done" ? `check again; ${text}` : text,
+            });
+            if (includes("capacity"))
+                row("capacity", detail);
+            if (includes("runner"))
+                row("runner", runnerSelected
+                    ? "start a Catalyst runner here with Docker"
+                    : "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
+        // into the settings row, under the number JSON reports for both.
+        if (json && id === "values")
+            continue;
         if (!includes(id) &&
             !(id === "capacity" && includes("runner")) &&
-            !(id === "settings" && includes("values")))
+            !(json && id === "settings" && includes("values")))
             continue;
         const reviewedDetail = id === "capacity" && includes("runner") && runnerSelected
             ? "start a Catalyst runner here with Docker"
@@ -72,8 +70,9 @@ export function standalonePlan(journal, scope, runnerSelected = false) {
                 ? "review the optional runner on this machine; start only if selected"
                 : detail;
         rows.push({
-            group,
-            number: SETUP_NUMBERS[id],
+            group: json ? group : setupPartHeading(SETUP_PART_OF[id], false),
+            part: SETUP_PART_OF[id],
+            number: (json ? SETUP_NUMBERS : SETUP_PART_NUMBERS)[id],
             title: setupStepView({ id, state: "pending" }).title,
             detail: steps.get(id)?.state === "done"
                 ? `check again; ${reviewedDetail}`
@@ -82,29 +81,37 @@ export function standalonePlan(journal, scope, runnerSelected = false) {
     }
     return rows;
 }
-export function pendingContinuation(journal) {
-    const unfinished = (...ids) => ids.some((id) => {
-        const step = journal.steps.find((step) => step.id === id);
-        return (step &&
-            step.state !== "done" &&
-            setupStepView(step, journal).mark !== "skip");
-    });
-    const next = [];
-    if (unfinished("github.repos", "projects"))
-        next.push("chooses repositories");
-    if (unfinished("accounts"))
-        next.push("checks a coding account");
-    if (unfinished("capacity", "runner"))
-        next.push("checks runners");
-    if (unfinished("settings", "values"))
-        next.push("reviews repository settings");
-    if (unfinished("first-ticket"))
-        next.push("starts a first ticket");
+/** What setup does next on its own, in the order it runs: steps not finished and not already listed
+ *  as something a person must do (`listed`). A step setup never reached because it paused is here. */
+const CONTINUES = [
+    [["linear.workspace"], "connects your Linear workspace"],
+    [["linear.personal"], "connects your Linear account"],
+    [["linear.team"], "chooses a Linear team"],
+    [["linear.adopt"], "sets up the team's workflow"],
+    [["linear.automations"], "checks Linear's pull request automations"],
+    [["github.install"], "installs Catalyst on GitHub"],
+    [["github.personal"], "connects your GitHub account"],
+    [["github.repos", "projects"], "chooses repositories"],
+    [["accounts"], "checks an AI account"],
+    [["capacity", "runner"], "checks runners"],
+    [["settings"], "reviews repository settings"],
+    [["values"], "checks repository values"],
+    [["first-ticket"], "starts a first ticket"],
+];
+export function pendingContinuation(journal, listed = new Set()) {
+    const unfinished = (ids) => !ids.some((id) => listed.has(id)) &&
+        ids.some((id) => {
+            const step = journal.steps.find((step) => step.id === id);
+            return (step &&
+                step.state !== "done" &&
+                setupStepView(step, journal).mark !== "skip");
+        });
+    const next = CONTINUES.filter(([ids]) => unfinished(ids)).map(([, words]) => words);
     if (!next.length)
         return null;
     const last = next.pop();
     return `Then setup ${next.length ? `${next.join(", ")} and ` : ""}${last}.`;
 }
 export function standalonePlanNotes(localSync) {
-    return `${localSync ? "Local sync is selected." : "Local sync stays off, so Catalyst reads from the cloud."} Checking a coding account sends Claude one short request, which counts toward its usage. Completed steps are checked again before work starts. Codex credentials are not refreshed. Your code, git settings and other skills stay as they are.`;
+    return `${localSync ? "Local sync is selected." : "Local sync stays off, so Catalyst reads from the cloud."} Setup reads your AI accounts without sending them a request. Completed steps are checked again before work starts. Your code, git settings and other skills stay as they are.`;
 }