@catalyst-cloud/cli 0.16.23 → 0.16.24

package/dist/onboard-runner.js

@@ -20,19 +20,21 @@ import { onboardStateRoot, } from "./onboard.js";
 /** The Compose project name the vendored file declares. */
 export const RUNNER_PROJECT = "catalyst-host";
 export const RUNNER_SESSION_NETWORK = "catalyst-session-v1";
-/** Catalyst's approved host release, generation 2 (hr-a19f7b0859a98147-9a96426c93e32173-63a9b20c3be3dc3e):
- * runner, supervisor and watchdog all built from catalyst-cloud 2ec4a551. A machine set up from these
+/** Catalyst's approved host release, generation 48 (hr-598fd0ef2675bfd8-69310962e37ad7f2-2d264b793edb843e):
+ * the runner built from catalyst-cloud caf921a4, the supervisor and watchdog from a4165555, the
+ * first supervisor that serves several teams (CTC-4455). A machine set up from these
  * pins then follows newer approved releases itself (`catalyst runner update`, CTC-4646).
  * Explicit environment values override these pins; a saved runner image is preserved. */
 export const RUNNER_HOST_IMAGES = {
-    supervisor: "ghcr.io/coalesce-labs/catalyst-supervisor@sha256:9a96426c93e32173a67e849aa5a462e9f5466b872e4117f9a8a7df1972b2a136",
-    watchdog: "ghcr.io/coalesce-labs/catalyst-deadline-watchdog@sha256:63a9b20c3be3dc3ea328d77aa68dece942a40be46cb3126d9a7868e082828feb",
-    runner: "ghcr.io/coalesce-labs/catalyst-runner@sha256:a19f7b0859a9814740935f7aadd8fe5c5c9c5974f9a5956a057b983ada16ea01",
+    supervisor: "ghcr.io/coalesce-labs/catalyst-supervisor@sha256:69310962e37ad7f21ccab5c131b0734f106a6b0cc9fb163cb5d8917c9d7a2fc1",
+    watchdog: "ghcr.io/coalesce-labs/catalyst-deadline-watchdog@sha256:2d264b793edb843e47b4c5a86fa6133dd2bd0b5ecdc0b7e997368893de074b28",
+    runner: "ghcr.io/coalesce-labs/catalyst-runner@sha256:598fd0ef2675bfd8e0665f70ef4ed8bf30706fba25fa2c39fc0df0801512a423",
 };
 export const IMAGE_REF = /^[a-z0-9][a-z0-9._:/-]{0,255}@sha256:[0-9a-f]{64}$/;
 const HOST_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$/;
 const JOIN_TOKEN = /^[A-Za-z0-9._~+/=-]{16,1024}$/;
-const ENROLLMENTS = "/api/v1/hosts/enrollments";
+const HOSTS = "/api/v1/hosts";
+const ENROLLMENTS = `${HOSTS}/enrollments`;
 const JOIN_TOKENS = "/api/v1/hosts/join-tokens";
 const CAPACITY = "/api/v1/me/runner-capacity";
 const RUNNER_UID = "10001:10001";
@@ -549,6 +551,7 @@ export function dockerRunnerEngine(deps = {}) {
         },
     };
 }
+const serves = (host, teamKey) => host.teams.includes(teamKey);
 const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value)
     ? value
     : null;
@@ -565,6 +568,8 @@ function parseHosts(body) {
             typeof host.hostId !== "string" ||
             typeof host.hostName !== "string" ||
             typeof host.team !== "string" ||
+            (host.teams !== undefined &&
+                (!Array.isArray(host.teams) || !host.teams.every((team) => typeof team === "string"))) ||
             !(host.revokedAtMs === null || typeof host.revokedAtMs === "number") ||
             (host.capability !== null &&
                 (!capability ||
@@ -578,6 +583,9 @@ function parseHosts(body) {
             hostId: host.hostId,
             hostName: host.hostName,
             team: host.team,
+            teams: Array.isArray(host.teams) && host.teams.includes(host.team)
+                ? host.teams
+                : [host.team],
             revoked: host.revokedAtMs !== null,
             capacity: capability ? capability.runtimeLive
                 ? capability.placeableCapacity
@@ -755,8 +763,8 @@ export function onboardRunnerAdapter(input = {}) {
         const teamKey = teamId ? await liveTeamKey(ctx, teamId, signal ?? new AbortController().signal) : null;
         if (!teamId || !teamKey)
             return waiting("runner_context_unverified", selected);
-        if (credential && !isUnenrolled(credential) && credential.team !== teamKey)
-            return waiting("runner_enrolled_for_other_team", selected);
+        // An installation enrolled for another team serves this one too once setup adds it (CTC-4455).
+        const otherTeamHost = credential && !isUnenrolled(credential) && credential.team !== teamKey ? credential.hostId : undefined;
         const runnerSupport = await verifyRunnerRoutes(ctx, journal, [{ method: "GET", path: "/api/v1/agent/runner-admission" }], signal);
         if ("reason" in runnerSupport && runnerSupport.reason !== "cloud_capability_unavailable")
             return waiting(runnerSupport.reason, selected);
@@ -773,7 +781,8 @@ export function onboardRunnerAdapter(input = {}) {
             return waiting("runner_native_egress_setup_required", selected);
         return { account, baseUrl: normalizeBaseUrl(cfg.baseUrl), teamKey, teamId, cloud, dir, info, images,
             ...(installation && installation !== "missing" ? { installedName: installation.hostName,
-                installedSupervisorImage: installation.supervisorImage } : {}) };
+                installedSupervisorImage: installation.supervisorImage } : {}),
+            ...(otherTeamHost ? { otherTeamHost } : {}) };
     }
     async function desiredEnv(p, ctx, joinToken) {
         const saved = readEnvFile(join(p.dir, ".env")) ?? {};
@@ -857,6 +866,58 @@ export function onboardRunnerAdapter(input = {}) {
             return waiting(signal?.aborted ? "interrupted" : "runner_join_token_unavailable", selected);
         }
     }
+    /**
+     * CTC-4455: adds the selected team to this machine's enrollment. The cloud refuses until the
+     * machine's supervisor advertises that it serves a set of teams. Before setup starts the new
+     * supervisor that refusal is `deferred`; after, it is retried for as long as setup waits for the
+     * supervisor. An older cloud without the route answers 404, and setup refuses as it used to.
+     */
+    async function addTeam(ctx, p, hostId, retry, signal) {
+        const evidence = { ...selected, hostId };
+        const cfg = loadConfig(ctx.home);
+        const expiry = cfg?.auth ? Date.parse(cfg.auth.expiresAt) - ctx.now().getTime() : 0;
+        const bearer = cfg?.key ||
+            (cfg?.auth && Number.isFinite(expiry) && expiry > 30_000 ? cfg.auth.accessToken : undefined);
+        if (!bearer)
+            return waiting("runner_login_refresh_required", evidence);
+        for (let attempt = 1;; attempt++) {
+            let status;
+            let body;
+            try {
+                const response = await ctx.fetch(`${p.baseUrl}${HOSTS}/${encodeURIComponent(hostId)}/teams?account=${encodeURIComponent(p.account)}`, {
+                    method: "POST",
+                    redirect: "error",
+                    signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000),
+                    headers: {
+                        authorization: `Bearer ${bearer}`,
+                        "content-type": "application/json",
+                        accept: "application/json",
+                    },
+                    body: JSON.stringify({ version: 1, team: p.teamKey }),
+                });
+                status = response.status;
+                body = object(await response.json().catch(() => null));
+            }
+            catch {
+                return waiting(signal?.aborted ? "interrupted" : "runner_team_add_failed", evidence);
+            }
+            if (status === 200 && body?.ok === true && Array.isArray(body.teams) && body.teams.includes(p.teamKey))
+                return true;
+            if (status === 404 && body?.error !== "unknown_host")
+                return waiting("runner_enrolled_for_other_team", evidence);
+            if (status === 401 || status === 403)
+                return waiting("runner_identity_unverified", evidence);
+            if (body?.error === "team_limit")
+                return waiting("runner_team_limit", evidence);
+            if (body?.error !== "supervisor_outdated")
+                return waiting("runner_team_add_failed", evidence);
+            if (!retry)
+                return "deferred";
+            if (attempt >= Math.max(1, Math.ceil(waitMs / pollMs)) || signal?.aborted)
+                return waiting("runner_supervisor_outdated", evidence);
+            await sleep(pollMs);
+        }
+    }
     function orgKeyFromFile(ctx) {
         const path = ctx.env.CATALYST_RUNNER_ORG_KEY_FILE;
         if (!path)
@@ -887,13 +948,13 @@ export function onboardRunnerAdapter(input = {}) {
             if (p.info.vm && persistedCustody(p.dir, saved) !== "installed")
                 return mayAct && !afterAct ? { state: "pending" } : waiting(mayAct ? "runner_thoughts_custody_unavailable" : "runner_needs_runner_flag", { ...selected, hostName: name });
             let enrolled = null;
-            const live = (hosts) => hosts?.find((host) => host.hostId === enrolled?.hostId && host.team === p.teamKey && !host.revoked);
+            const live = (hosts) => hosts?.find((host) => host.hostId === enrolled?.hostId && serves(host, p.teamKey) && !host.revoked);
             let hosts = await listHosts(ctx, p, signal);
             if (!hosts)
                 return waiting("runner_enrollment_unavailable", selected);
             const existingCredential = await engine.enrollment(p.dir, signal);
             if ((!existingCredential || isUnenrolled(existingCredential)) &&
-                hosts.some((host) => host.hostName === name && !host.revoked && host.team !== p.teamKey))
+                hosts.some((host) => host.hostName === name && !host.revoked && !serves(host, p.teamKey)))
                 return waiting("runner_enrolled_for_other_team", {
                     ...selected,
                     hostName: name,
@@ -902,8 +963,11 @@ export function onboardRunnerAdapter(input = {}) {
                 !isUnenrolled(existingCredential) &&
                 hosts.some((host) => host.hostId === existingCredential.hostId &&
                     !host.revoked &&
-                    host.team !== p.teamKey))
-                return waiting("runner_enrolled_for_other_team", { ...selected, hostName: name });
+                    !serves(host, p.teamKey)))
+                // CTC-4455: setup's act adds the selected team to a runner enrolled for another one.
+                return mayAct && !afterAct
+                    ? { state: "pending" }
+                    : waiting(mayAct ? "runner_team_not_added" : "runner_needs_runner_flag", { ...selected, hostName: name });
             const running = await engine.composeRunning(p.dir, signal);
             let composeMatches = false;
             try {
@@ -931,13 +995,11 @@ export function onboardRunnerAdapter(input = {}) {
                     return waiting("runner_enrollment_unavailable", hostEvidence);
                 if (enrolled && (enrolled.tenant !== p.account || enrolled.enrollmentKind !== "self_hosted"))
                     return waiting("runner_identity_unverified", hostEvidence);
-                if (enrolled && enrolled.team !== p.teamKey)
-                    return waiting("runner_enrolled_for_other_team", hostEvidence);
                 if (enrolled) {
                     const exact = hosts.find((host) => host.hostId === enrolled.hostId);
                     if (exact?.revoked)
                         return waiting("runner_enrollment_revoked", { ...hostEvidence, hostId: enrolled.hostId });
-                    if (!exact || exact.team !== p.teamKey)
+                    if (!exact || !serves(exact, p.teamKey))
                         return waiting("runner_enrollment_unverified", hostEvidence);
                 }
                 const host = live(hosts);
@@ -986,6 +1048,23 @@ export function onboardRunnerAdapter(input = {}) {
                 return p;
             if (!mayAct)
                 return waiting("runner_needs_runner_flag", selected);
+            // Settle a team the installed runner does not serve before anything on this machine changes.
+            let addTeamTo = null;
+            if (p.otherTeamHost) {
+                const hosts = await listHosts(ctx, p, signal);
+                if (!hosts)
+                    return waiting("runner_enrollment_unavailable", selected);
+                const exact = hosts.find((host) => host.hostId === p.otherTeamHost && !host.revoked);
+                if (!exact)
+                    return waiting("runner_enrolled_for_other_team", selected);
+                if (!serves(exact, p.teamKey)) {
+                    const added = await addTeam(ctx, p, exact.hostId, false, signal);
+                    if (added === "deferred")
+                        addTeamTo = exact.hostId;
+                    else if (added !== true)
+                        return added;
+                }
+            }
             let replacingContainers = false;
             try {
                 mkdirSync(p.dir, { recursive: true, mode: 0o700 });
@@ -1104,20 +1183,25 @@ export function onboardRunnerAdapter(input = {}) {
             if (!hosts)
                 return waiting("runner_enrollment_unavailable", selected);
             if (!enrolled &&
-                hosts.some((host) => host.hostName === name && !host.revoked && host.team !== p.teamKey))
+                hosts.some((host) => host.hostName === name && !host.revoked && !serves(host, p.teamKey)))
                 return waiting("runner_enrolled_for_other_team", { ...selected, hostName: name });
             if (enrolled && (enrolled.tenant !== p.account || enrolled.enrollmentKind !== "self_hosted"))
                 return waiting("runner_identity_unverified", { ...selected, hostName: name });
-            if (enrolled && enrolled.team !== p.teamKey)
-                return waiting("runner_enrolled_for_other_team", { ...selected, hostName: name });
             if (hasCredential && !isUnenrolled(credential)) {
                 if (!enrolled)
                     return waiting("runner_credential_unverified", { ...selected, hostName: name });
                 const exact = hosts.find((host) => host.hostId === enrolled.hostId);
                 if (exact?.revoked)
                     return waiting("runner_enrollment_revoked", { ...selected, hostName: name, hostId: enrolled.hostId });
-                if (!exact || exact.team !== p.teamKey)
+                if (!exact)
                     return waiting("runner_enrollment_unverified", { ...selected, hostName: name });
+                if (!serves(exact, p.teamKey) && addTeamTo === null) {
+                    const added = await addTeam(ctx, p, exact.hostId, false, signal);
+                    if (added === "deferred")
+                        addTeamTo = exact.hostId;
+                    else if (added !== true)
+                        return added;
+                }
             }
             // A lost volume also lost the secret that redeemed the old token. Mint a new token and match
             // the new host id from the supervisor's credential, never an old advertisement with this name.
@@ -1184,6 +1268,14 @@ export function onboardRunnerAdapter(input = {}) {
             if (!up.ok)
                 return { state: "failed", reason: "runner_compose_failed", evidence: { ...selected,
                         project: RUNNER_PROJECT, ...(up.error ? { composeError: up.error } : {}) } };
+            // The supervisor just started can serve a set of teams; the cloud accepts the team once it says so.
+            if (addTeamTo) {
+                const added = await addTeam(ctx, p, addTeamTo, true, signal);
+                if (added === "deferred")
+                    return waiting("runner_supervisor_outdated", selected);
+                if (added !== true)
+                    return added;
+            }
             acted = true;
             if (input.autoUpdate) {
                 try {

package/dist/prompt.js

@@ -1,10 +1,23 @@
-// prompt.ts — the one interactive read in the CLI: asking for the personal key on a terminal without
-// echoing it. The streams are parameters so the tests can drive it without a real TTY.
+// prompt.ts — the CLI's interactive reads: asking for the personal key on a terminal without
+// echoing it, and one [y/N] question. The streams are parameters so the tests can drive it without a real TTY.
 import { createInterface } from "node:readline";
+import { createInterface as createPromiseInterface } from "node:readline/promises";
 /** True when there is a terminal to prompt on. Both ends matter: the question needs somewhere to go. */
 export function stdinIsTty() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
+/** Ask a `[y/N]` question on stderr and read the answer. False without a terminal, and for anything but y/yes. */
+export async function confirmYesNo(question) {
+    if (!stdinIsTty())
+        return false;
+    const prompt = createPromiseInterface({ input: process.stdin, output: process.stderr });
+    try {
+        return /^(y|yes)$/i.test((await prompt.question(question)).trim());
+    }
+    finally {
+        prompt.close();
+    }
+}
 /**
  * Read one line without echoing it. Everything readline would write after the question itself goes
  * to a muted stream, so the key never reaches the screen or a scrollback buffer; the caller still

package/dist/secret.js

@@ -31,7 +31,7 @@ export const SECRETS_IMPORT_PATH = "/me/secrets/import";
 const NAME_RE = /^[A-Z][A-Z0-9_]*$/;
 const REPO_RE = /^[^/\s]+\/[^/\s]+$/;
 /** Why an import line was not stored, in words a person can act on. */
-const IMPORT_REASONS = {
+export const IMPORT_REASONS = {
     name_exists: "already set for this repository; pass --rotate <NAME> to replace it",
     name_taken_by_env_var: "already a plain environment variable; a name is a secret or a variable, never both",
     invalid_name: "not an env-style name (A-Z, 0-9 and _, starting with a letter)",
@@ -69,7 +69,7 @@ function requireRepo(args, verb) {
     return repo;
 }
 /** The cloud's refusal, in its own words, plus what to do for the two we can explain. */
-function refusalLine(status, body, repo) {
+export function refusalLine(status, body, repo) {
     if (status === 401) {
         return "refused (401): the cloud did not accept your credential here. If `catalyst me` works, this cloud predates secret writes from the CLI and needs a newer release; otherwise log in again.";
     }
@@ -91,7 +91,7 @@ function renderDeclared(declared, repo) {
         return [`every declared secret has a value (${declared.declared.length})`];
     return [`declared but still without a value (${declared.missing.length}): ${declared.missing.join(", ")}`];
 }
-const ACCEPT = [400, 401, 403, 404, 409, 422];
+export const ACCEPT = [400, 401, 403, 404, 409, 422];
 async function readStdinText() {
     const chunks = [];
     for await (const chunk of process.stdin)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.16.23",
+  "version": "0.16.24",
   "description": "Set up Catalyst Cloud, check your tickets and manage your account from the command line.",
   "license": "MIT",
   "type": "module",
@@ -53,16 +53,16 @@
     "prepublishOnly": "node scripts/release-train-check.mjs --publish cli"
   },
   "dependencies": {
-    "@catalyst-cloud/sdk": "0.16.9",
+    "@catalyst-cloud/sdk": "0.16.11",
     "@clack/prompts": "1.8.1",
     "fast-string-width": "3.0.2",
     "fast-wrap-ansi": "0.2.2",
     "smol-toml": "^1.7.1",
     "yaml": "^2.9.0",
-    "@catalyst-cloud/sdk-replica-node": "0.16.9"
+    "@catalyst-cloud/sdk-replica-node": "0.16.11"
   },
   "devDependencies": {
-    "@catalyst-cloud/schema": "0.16.7",
+    "@catalyst-cloud/schema": "0.16.9",
     "@types/node": "^26.3.0",
     "@vitest/coverage-v8": "^4.1.11",
     "typescript": "^7.0.2",

package/skills/catalyst-github/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's GitHub: show a ticket's pull request with its checks, reviews and review threads, say whether it is mergeable under this repository's policy, and explain what a PR accumulates as the ticket moves (the branch, the draft, the rewrite, the force-pushes, the labels, the queue). Use when someone asks "show me the PR", "what are the checks saying", "why hasn't it merged", "what does the queue need", "what does that label mean", or wants the branch and merge conventions Catalyst follows.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.23 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.24 — 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.16.23 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.24 — 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.16.23 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.24 — written in this repository for customer accounts -->
 
 # Onboard me
 

package/skills/catalyst-onboard/references/declaring-a-repository.md

@@ -6,7 +6,7 @@ The assistant prepares `.catalyst/catalyst.toml` from the repository. Never ask
 
 1. Check `.catalyst/catalyst.toml` and `catalyst.env.json` in the selected repository. Classify it as missing, legacy-only, valid TOML, or invalid TOML. `catalyst env check --json` checks the TOML environment table; when only the legacy file exists, it reports that the JSON declaration is no longer read.
 2. For a legacy file, run `catalyst env migrate [path-to-catalyst.env.json]`. It prints a TOML environment table containing names only; every name is optional, and names identified as secrets are marked `secret = true`. Do not copy JSON values or provenance into the new file.
-3. For missing or invalid declarations, inspect the repository's package manager files, README setup instructions, `package.json` scripts or equivalent, build and test workflows, `.env.example`, and source references. Use `catalyst env inventory [repo] --json` as supporting evidence. Do not inspect `.env` values or run repository scripts just to infer settings.
+3. For missing or invalid declarations, run `catalyst env draft --root <repo> --json` first. It drafts names from the repository's standard files and from this computer: the names the repository's `.envrc` exports, and the HTTP MCP servers in Claude Code's `~/.claude.json` with each header turned into a variable reference. It never writes or prints a value, and it lists what it did not draft and why. Then refine the draft from the repository's package manager files, README setup instructions, `package.json` scripts or equivalent, build and test workflows, `.env.example`, and source references. Use `catalyst env inventory [repo] --json` as supporting evidence. Do not inspect `.env` values or run repository scripts just to infer settings.
 4. Draft `#:schema https://staging.catalystcloud.dev/schemas/catalyst.schema.json`, `[project]` with the mapped project's `linear_team`, the environment variables evidenced by build/test/setup, and setup/verify steps based on the repository's real package manager and build/test commands. Exclude deploy-only variables and platform bindings unless build or tests use them. Mark known secrets with `secret = true`. Set `required = false` on every variable; never make a phase depend on a newly declared value by default.
 5. Validate the complete draft against the live schema at the URL in its `#:schema` line, then run `catalyst env check <path>`. The environment check is an additional check; it does not replace full schema validation. If a live-schema validator is unavailable or either check fails, fix the draft or report the exact blocker without claiming it is valid.
 
@@ -14,7 +14,11 @@ The assistant prepares `.catalyst/catalyst.toml` from the repository. Never ask
 
 Show a short preview with the project/team, setup and verify commands, variable names, which are marked secret, and confirmation that every variable is optional. Do not include values. Ask the person to approve this exact draft. Before approval, do not write or replace `.catalyst/catalyst.toml`, remove `catalyst.env.json`, or open a settings PR.
 
-After approval, write the validated file. When converting a legacy-only repository, remove `catalyst.env.json` in the same change. Open the settings PR, then offer to watch it merge. A reviewed merge is the approval. Catalyst approves the exact merged revision, with no second step, when someone other than the PR's author approved the merged head commit, or when a workspace owner or admin merged the PR. Tell the person this before they merge: the approving review is their consent to the setup commands and secret names in the file, so a reviewer should read it like code. A direct push, an unreviewed merge, or an approval left before the last commit leaves the revision proposed. No command approves one repository's revision yet, so only then give an owner or admin a direct link to approve it at Settings → Your projects → the project → Repositories → the repository → Environment → Setup declaration → Approve this revision. The direct route is `/settings/projects/$projectId/repositories/$repoId/environment/declaration`; use the project and repository ids from Catalyst instead of guessing them.
+After approval, write the validated file.
+
+When the approved file came from `catalyst env draft`, ask: "Want me to store this computer's values for these names in Catalyst?" On a yes, run `catalyst env import --root <repo> --yes --json` and report its `stored`, `kept`, `noValue` and `notStored` names, with the fix it gives for each. The command reads the values itself and never prints them, so do not read them yourself. It needs an admin or owner seat. A name in `noValue` that `.envrc` computes needs the command run in the person's own shell, where direnv has loaded the repository.
+
+When converting a legacy-only repository, remove `catalyst.env.json` in the same change. Open the settings PR, then offer to watch it merge. A reviewed merge is the approval. Catalyst approves the exact merged revision, with no second step, when someone other than the PR's author approved the merged head commit, or when a workspace owner or admin merged the PR. Tell the person this before they merge: the approving review is their consent to the setup commands and secret names in the file, so a reviewer should read it like code. A direct push, an unreviewed merge, or an approval left before the last commit leaves the revision proposed. No command approves one repository's revision yet, so only then give an owner or admin a direct link to approve it at Settings → Your projects → the project → Repositories → the repository → Environment → Setup declaration → Approve this revision. The direct route is `/settings/projects/$projectId/repositories/$repoId/environment/declaration`; use the project and repository ids from Catalyst instead of guessing them.
 
 ## File shape
 

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.16.23 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.24 — 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.16.23 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.24 — 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.16.23 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.24 — 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.16.23 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.24 — 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?", "what machines do we have?", "how much capacity do we have?", "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.16.23 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.24 — written in this repository for customer accounts -->
 
 # What's happening