@catalyst-cloud/cli 0.15.1 → 0.15.3

package/dist/onboard.js

@@ -6,11 +6,11 @@ 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";
-import { onboardReasonText, onboardTeamKey, savedOnboardBaseUrl, } from "./onboard-next.js";
+import { dispatchStageName, onboardReasonText, onboardTeamKey, savedOnboardBaseUrl, } from "./onboard-next.js";
 import { parseBootstrapPlan, bootstrapPlanHash, bootstrapPlanLines, } from "./onboard-bootstrap.js";
 export const ONBOARD_STEPS = [
     "machine",
@@ -37,6 +37,14 @@ export const ONBOARD_STEPS = [
     "first-ticket",
     "ready",
 ];
+function dailyUpdateChoice(value) {
+    const row = object(value);
+    if (row?.state === "on" || row?.state === "off")
+        return { state: row.state };
+    if (row?.state === "skipped" && row.reason === "no_scheduler")
+        return { state: "skipped", reason: "no_scheduler" };
+    return undefined;
+}
 export function onboardIdentityLines(identity) {
     if (!identity)
         return [
@@ -51,10 +59,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;
@@ -103,7 +112,8 @@ export const ONBOARD_DEPENDENCIES = {
     projects: ["linear.team", "github.repos"],
     accounts: ["signin"],
     settings: ["projects"],
-    values: ["settings"],
+    // The cloud's required-values check reads the registered repositories, not a local checkout.
+    values: ["projects"],
     capacity: ["projects"],
     // The join token names the selected team's pool.
     runner: ["linear.team"],
@@ -126,7 +136,7 @@ const ADMIN_STEPS = new Set([
     "github.repos",
     "projects",
     "settings",
-    "values",
+    // `values` is not here: its check only reads, so a member's run finds missing values too.
     "capacity",
     "runner",
     "first-ticket",
@@ -146,9 +156,9 @@ export const ONBOARD_TITLES = {
     "github.personal": "Connect your GitHub account",
     "github.repos": "Choose repositories",
     projects: "Register your projects",
-    accounts: "Check coding accounts",
+    accounts: "Check AI accounts",
     settings: "Review repository settings",
-    values: "Import selected local values",
+    values: "Check the repository's values",
     capacity: "Check runner capacity",
     runner: "Run Catalyst's work on this machine",
     daemon: "Check optional local sync",
@@ -250,6 +260,10 @@ function normalizeStep(value, fallbackAt) {
         "repository",
         "installation",
         "ticket",
+        // The team's dispatch stage name, as the contract gave it.
+        "stage",
+        // Admin-owned step ids a member's run found unfinished.
+        "admin",
         "cursor",
         "lag",
         "heartbeatAgeMs",
@@ -287,6 +301,8 @@ function normalizeStep(value, fallbackAt) {
         "org",
         "url",
         "actor",
+        // CTC-4716: which AI accounts the workspace may add, so the step's text offers only those.
+        "aiAccountKinds",
     ]) {
         const item = evidence?.[key];
         if (item === null ||
@@ -322,6 +338,7 @@ export function readOnboardJournal(path, cliVersion = "0.13.1", now = new Date()
         : typeof value.exitCode === "number"
             ? value.exitCode
             : null;
+    const dailyUpdate = dailyUpdateChoice(value.dailyUpdate);
     return {
         schema: 1,
         runId: typeof value.runId === "string" ? value.runId : randomUUID(),
@@ -353,6 +370,7 @@ export function readOnboardJournal(path, cliVersion = "0.13.1", now = new Date()
         ...(typeof value.localSync === "boolean"
             ? { localSync: value.localSync }
             : {}),
+        ...(dailyUpdate ? { dailyUpdate } : {}),
         operations: Object.fromEntries(Object.entries(object(value.operations) ?? {}).filter(([key, v]) => ONBOARD_STEPS.includes(key) &&
             typeof v === "string" &&
             /^[a-zA-Z0-9_.:-]{1,160}$/.test(v))),
@@ -572,7 +590,8 @@ function printPlan(ctx, journal, identity, options) {
         for (const line of onboardIdentityLines(identity))
             ctx.stdout(line);
     let group;
-    for (const row of standalonePlan(journal, options?.scope, options?.runner)) {
+    // Beside --json and headless output: the numbers JSON actions carry (CTC-4680).
+    for (const row of standalonePlan(journal, options?.scope, options?.runner, "json")) {
         if (row.group !== group) {
             ctx.stdout("");
             ctx.stdout(row.group);
@@ -628,14 +647,28 @@ export function stepSatisfied(step) {
     return (step?.state === "done" ||
         (step?.state === "skipped" &&
             (step.id === "legacy" ||
+                // Optional: a computer without the daily update still runs work.
+                step.id === "housekeeping" ||
                 step.reason === "member_scope" ||
                 (step.id === "daemon" && step.reason === "local_sync_not_selected") ||
                 (step.id === "runner" && step.reason === "runner_not_selected") ||
+                (step.id === "first-ticket" && step.reason === "first_ticket_skipped") ||
                 (step.id === "linear.automations" &&
                     step.reason === "automation_management_unavailable"))));
 }
+/** Optional work this computer or checkout cannot do. Work runs without it, so its wait never holds
+ * a complete setup. */
+const OPTIONAL_WAITS = new Set([
+    "settings_checkout_unverified",
+    "settings_approval_unverified",
+]);
+/** Satisfied, or an optional wait. What a complete setup needs of every step. */
+export function stepSettled(step) {
+    return (stepSatisfied(step) ||
+        (step?.state === "waiting" && OPTIONAL_WAITS.has(step.reason ?? "")));
+}
 /** Steps whose wait does not hold a full run's exit code: work runs without them. A failure still
- * fails the run, and the receipt's `complete` still needs them satisfied. Never used for gating. */
+ * fails the run, and the receipt's `complete` still needs them settled. Never used for gating. */
 export const ONBOARD_DEFERRED_STEPS = new Set([
     "settings",
     "values",
@@ -676,8 +709,11 @@ export function onboardNextActions(journal, baseUrl, only) {
         .filter((step) => (!only || step.id === only) && !stepSatisfied(step))
         .sort((a, b) => ONBOARD_STEPS.indexOf(a.id) - ONBOARD_STEPS.indexOf(b.id))
         .map((step) => `${ONBOARD_TITLES[step.id]}: ${onboardStepAction(journal, step, baseUrl)}`);
-    if (["projects", "accounts", "linear.adopt", "capacity"].every((id) => journalStep(journal, id)?.state === "done"))
-        lines.push(`Move a ticket in ${onboardTeamKey(journal) ?? "<TEAM KEY>"} to Todo; \`catalyst explain <ticket>\` says why it is or is not starting.`);
+    // A waiting first ticket already says to move a ticket, in its own line.
+    const firstTicket = journalStep(journal, "first-ticket");
+    if (["projects", "accounts", "linear.adopt", "capacity"].every((id) => journalStep(journal, id)?.state === "done") &&
+        firstTicket?.state !== "waiting")
+        lines.push(`Move a ticket in ${onboardTeamKey(journal) ?? "<TEAM KEY>"} to ${dispatchStageName(firstTicket?.evidence?.stage)}; \`catalyst explain <ticket>\` says why it is or is not starting.`);
     return lines;
 }
 function requireMatchingIdentity(journal, identity) {
@@ -726,9 +762,10 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
     const only = typeof args.flags.only === "string"
         ? args.flags.only
         : undefined;
+    // A member's values check reads the selected team, so without --team it waits on the same skip.
     const memberScopeSkips = (id) => ADMIN_STEPS.has(id) ||
-        (id === "linear.team" &&
-            only !== "linear.team" &&
+        ((id === "linear.team" || id === "values") &&
+            only !== id &&
             typeof args.flags.team !== "string");
     const resume = typeof args.flags["resume-from"] === "string"
         ? args.flags["resume-from"]
@@ -1068,7 +1105,7 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
         journal.complete =
             !only &&
                 code === 0 &&
-                ONBOARD_STEPS.every((id) => stepSatisfied(journalStep(journal, id)));
+                ONBOARD_STEPS.every((id) => stepSettled(journalStep(journal, id)));
         writeOnboardJournal(statePath, journal);
         if (args.json)
             ctx.stdout(JSON.stringify(journal));
@@ -1398,7 +1435,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",
@@ -1437,7 +1478,7 @@ export async function cmdOnboard(args, ctx, deps = {}, cliVersion = "0.13.1") {
             journal.complete =
                 !only &&
                     code === 0 &&
-                    ONBOARD_STEPS.every((id) => stepSatisfied(journalStep(journal, id)));
+                    ONBOARD_STEPS.every((id) => stepSettled(journalStep(journal, id)));
             const unfinished = journal.steps.filter((step) => !stepSatisfied(step));
             if (!only &&
                 !refused &&

package/dist/ready-copy.js

@@ -0,0 +1,325 @@
+// 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(/\/+$/, "");
+}
+const NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+const REPOSITORY = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}\/[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/;
+const identifiers = (value) => Array.isArray(value)
+    ? value.filter((name) => typeof name === "string" && NAME.test(name))
+    : [];
+const unresolvedFacts = (value) => Array.isArray(value)
+    ? value.flatMap((row) => typeof row?.name === "string" && NAME.test(row.name) && identifiers(row.references).length
+        ? [{ name: row.name, references: identifiers(row.references) }]
+        : [])
+    : [];
+/** The declared names a failing check carries, kept in the receipt for the fix line: which variables
+ * need a value, which refer to a secret with no value, and the same for the team's other
+ * repositories. Identifiers and repository names only. */
+export function valuesFacts(value) {
+    const row = (value ?? {});
+    return {
+        names: identifiers(row.names),
+        unresolved: unresolvedFacts(row.unresolved),
+        repos: Array.isArray(row.repos)
+            ? row.repos.flatMap((note) => typeof note?.repo === "string" && REPOSITORY.test(note.repo)
+                ? [{ repo: note.repo, names: identifiers(note.names), unresolved: unresolvedFacts(note.unresolved) }]
+                : [])
+            : [],
+    };
+}
+/** Where the named variables get their values. Names only: nothing here reads or prints a value. */
+function setValuesFix(baseUrl, names) {
+    return baseUrl
+        ? `set ${names.join(", ")} on the repository's Environment page: open ${origin(baseUrl)}/settings/projects, then the project, then the repository`
+        : `set ${names.join(", ")} on the repository's Environment page in Catalyst's project settings`;
+}
+function nameList(v) {
+    return Array.isArray(v)
+        ? v.filter((n) => typeof n === "string" && n.length > 0)
+        : [];
+}
+/** Entries whose name and references are both present; anything malformed is dropped, not guessed. */
+function unresolvedList(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.flatMap((u) => {
+        if (typeof u !== "object" || u === null)
+            return [];
+        const { name, references } = u;
+        const refs = nameList(references);
+        return typeof name === "string" && name.length > 0 && refs.length > 0
+            ? [{ name, references: refs }]
+            : [];
+    });
+}
+function unresolvedLine(u) {
+    const which = u.references.length === 1 ? "which has" : "which have";
+    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
+ *  the reference with no value, and each other repository's missing names from `repos[]`. `unresolved`
+ *  is a subset of `names` (the variable exists; its reference does not), so those are not told to be
+ *  "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. Shared with setup's values step, which has no web address when the
+ *  saved login has none. */
+export 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(setValuesFix(base, names));
+    for (const u of unresolved)
+        parts.push(unresolvedLine(u));
+    for (const note of Array.isArray(c.repos) ? c.repos : []) {
+        if (typeof note !== "object" ||
+            note === null ||
+            typeof note.repo !== "string" ||
+            note.repo.length === 0)
+            continue;
+        const repoUnresolved = unresolvedList(note.unresolved);
+        const skip = new Set(repoUnresolved.map((u) => u.name));
+        const missing = nameList(note.names).filter((n) => !skip.has(n));
+        if (missing.length > 0)
+            parts.push(`${note.repo} is missing ${missing.join(", ")}`);
+        for (const u of repoUnresolved)
+            parts.push(`in ${note.repo}, ${unresolvedLine(u)}`);
+    }
+    return parts.length === 0 ? null : parts.join(". ");
+}
+/** 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}`,
+        };
+}