@catalyst-cloud/cli 0.13.1 → 0.14.1

package/dist/project.js

@@ -18,7 +18,13 @@ export const WIP_LIMIT_MAX = 9999;
  *  two strings, so `capabilities` can judge them. */
 export const WIP_LIMIT_ROUTE = "/api/v1/agent/team-wip-limit";
 export const wipLimitPath = (team) => `${WIP_LIMIT_ROUTE}?team=${encodeURIComponent(team)}`;
-const SOURCE_TEXT = { project: "set for this project", flag: "workspace value", default: "default" };
+/** Admin-readable inventory of every Catalyst project, including projects with no saved stages. */
+export const PROJECT_LIST_ROUTE_SUFFIX = "/tenant/repositories";
+const SOURCE_TEXT = {
+    project: "set for this project",
+    flag: "workspace value",
+    default: "default",
+};
 const sourceText = (source) => SOURCE_TEXT[String(source)] ?? String(source ?? "unknown");
 /** The project `--team` names, or the only mapped project when the flag is absent. Never a guess between two. */
 export function resolveTeam(doc, wanted) {
@@ -54,7 +60,13 @@ export function ticketIds(value) {
     if (!Array.isArray(value))
         return [];
     return value
-        .map((t) => (typeof t === "string" ? t : t && typeof t === "object" ? String(t.identifier ?? t.id ?? "") : ""))
+        .map((t) => typeof t === "string"
+        ? t
+        : t && typeof t === "object"
+            ? String(t.identifier ??
+                t.id ??
+                "")
+            : "")
         .filter((t) => t !== "");
 }
 /** One line naming what holds the WIP, capped so a big team does not scroll; null when the cloud sent none. */
@@ -68,11 +80,46 @@ function inProgressLine(view) {
 function line(key, view) {
     const limit = view.limit;
     const inProgress = view.inProgress;
-    const at = typeof limit === "number" && typeof inProgress === "number" && inProgress >= limit ? " — at the limit: a new ticket waits until one in progress finishes" : "";
+    const at = typeof limit === "number" &&
+        typeof inProgress === "number" &&
+        inProgress >= limit
+        ? " — at the limit: a new ticket waits until one in progress finishes"
+        : "";
     return `${key}: ${typeof inProgress === "number" ? inProgress : "?"} in progress, limit ${typeof limit === "number" ? limit : "?"} (${sourceText(view.source)})${at}`;
 }
 export async function cmdProject(args, ctx) {
     const [sub, action, value, ...extra] = positionals(args);
+    if (sub === "list") {
+        if (action !== undefined || value !== undefined || extra.length > 0)
+            throw new UsageError("project list takes no arguments");
+        const cfg = requireConfig(ctx);
+        const { doc } = await loadContract(ctx, cfg);
+        const route = doc.routes.find((r) => r.method === "GET" && r.path.endsWith(PROJECT_LIST_ROUTE_SUFFIX));
+        if (!route)
+            throw new UsageError("this cloud does not publish the tenant project list route yet (needs a newer cloud)");
+        const response = await apiClient(cfg, ctx).getJson(route.path, { accept: [403, 404] });
+        if (response.status === 403) {
+            const message = response.body
+                ?.message;
+            throw new UsageError(`listing tenant projects needs a workspace owner or admin${message ? ` (${message})` : ""}`);
+        }
+        if (response.status === 404)
+            throw new UsageError("this cloud does not serve tenant project listing yet (needs a newer cloud)");
+        const projects = Array.isArray(response.body?.repositories)
+            ? response.body.repositories
+            : [];
+        if (projects.length === 0 && !Array.isArray(response.body?.repositories)) {
+            throw new UsageError("the tenant project list response did not contain repositories");
+        }
+        if (args.json)
+            ctx.stdout(JSON.stringify(projects));
+        else {
+            for (const project of projects) {
+                ctx.stdout(`${project.name} | ${project.linearTeamKey ?? project.linearTeamId} | ${project.githubRepoOwner}/${project.githubRepoName} | ${project.status} | ${project.id}`);
+            }
+        }
+        return 0;
+    }
     if (sub !== "wip-limit")
         throw new UsageError("project needs wip-limit <get|set <n>|default>");
     if (action !== "get" && action !== "set")
@@ -88,15 +135,19 @@ export async function cmdProject(args, ctx) {
     const key = team.key ?? team.id;
     const client = apiClient(cfg, ctx);
     const accept = [400, 403, 404];
-    const emit = (body, lines) => { if (args.json)
-        ctx.stdout(JSON.stringify(body));
-    else
-        for (const l of lines)
-            ctx.stdout(l); };
+    const emit = (body, lines) => {
+        if (args.json)
+            ctx.stdout(JSON.stringify(body));
+        else
+            for (const l of lines)
+                ctx.stdout(l);
+    };
     const refuse = (status, reply) => {
         // The cloud's error bodies carry `error` (the code to match on) and a human `message`.
         const body = reply ?? {};
-        const detail = body.message || body.reason ? ` (${String(body.message ?? body.reason)})` : "";
+        const detail = body.message || body.reason
+            ? ` (${String(body.message ?? body.reason)})`
+            : "";
         const why = status === 403
             ? `setting the limit needs a workspace owner or admin; any member can read it with catalyst project wip-limit get${detail}`
             : status === 404 && body.error === "team-unknown"
@@ -104,16 +155,23 @@ export async function cmdProject(args, ctx) {
                 : status === 404
                     ? "this Catalyst Cloud does not serve the wip-limit route yet (needs a newer cloud)"
                     : `${String(body.error ?? body.code ?? "bad request")}${detail}`;
-        emit({ status, team: { id: team.id, key }, ...body }, [`refused (${status}): ${why}`]);
+        emit({ status, team: { id: team.id, key }, ...body }, [
+            `refused (${status}): ${why}`,
+        ]);
         return 1;
     };
-    const before = await client.getJson(wipLimitPath(team.id), { accept, parseAccepted: true });
+    const before = await client.getJson(wipLimitPath(team.id), {
+        accept,
+        parseAccepted: true,
+    });
     if (before.status !== 200)
         return refuse(before.status, before.body);
     if (action === "get") {
         emit({ team: { id: team.id, key }, ...before.body }, [
             line(key, before.body),
-            ...(inProgressLine(before.body) === null ? [] : [inProgressLine(before.body)]),
+            ...(inProgressLine(before.body) === null
+                ? []
+                : [inProgressLine(before.body)]),
             `change it: catalyst project wip-limit set <n> --team ${key} (owner or admin; set default returns to the workspace value)`,
         ]);
         return 0;
@@ -121,7 +179,11 @@ export async function cmdProject(args, ctx) {
     const after = await client.postJson(WIP_LIMIT_ROUTE, { team: team.id, limit }, { accept });
     if (after.status !== 200)
         return refuse(after.status, after.body);
-    emit({ team: { id: team.id, key }, ...after.body, previous: { limit: before.body.limit, source: before.body.source } }, [
+    emit({
+        team: { id: team.id, key },
+        ...after.body,
+        previous: { limit: before.body.limit, source: before.body.source },
+    }, [
         `${key}: limit ${String(before.body.limit)} (${sourceText(before.body.source)}) → ${String(after.body.limit)} (${sourceText(after.body.source)})${after.body.limit === 0 ? "; 0 holds every new start" : ""}`,
         line(key, after.body),
     ]);

package/dist/ready.js

@@ -131,12 +131,22 @@ function unresolvedLine(u) {
  *  identifier or a repository name, never a value, and nothing here reads a value. Any other check
  *  keeps the generic line. */
 function teamCheckFix(label, c) {
+    const automationRules = {
+        linear_automation_pr_open: "On PR open",
+        linear_automation_pr_review: "On PR review request or activity",
+        linear_automation_pr_ready: "On PR ready for merge",
+        linear_automation_pr_merge: "On PR merge",
+    };
+    const rule = automationRules[c.id];
+    if (rule) {
+        return `in Linear, open Settings → Teams → ${label} → Workflow → Workflows & automations → Pull request and commit automations and set ${rule} to No action, including branch-specific overrides; then run catalyst team check ${label}`;
+    }
     const unresolved = unresolvedList(c.unresolved);
     const unresolvedNames = new Set(unresolved.map((u) => u.name));
     const names = nameList(c.names).filter((n) => !unresolvedNames.has(n));
     const parts = [];
     if (names.length > 0) {
-        parts.push(`set ${names.join(", ")} on the repository's Environment page under Settings → Repositories ` +
+        parts.push(`set ${names.join(", ")} on the repository's Environment page under Settings → Your projects → the project → Repositories → the repository ` +
             `(team ${label}; ${names.length === 1 ? "it has" : "they have"} no value at repository or account scope)`);
     }
     for (const u of unresolved)

package/dist/secret.js

@@ -25,6 +25,7 @@ import { requireConfig } from "./config.js";
 import { CliError, UsageError } from "./errors.js";
 import { promptSecret, stdinIsTty } from "./prompt.js";
 import { apiClient } from "./transport.js";
+import { filterEnvFileNames } from "./env/parse-env.js";
 export const SECRETS_PATH = "/me/secrets";
 export const SECRETS_IMPORT_PATH = "/me/secrets/import";
 const NAME_RE = /^[A-Z][A-Z0-9_]*$/;
@@ -105,7 +106,19 @@ export async function cmdSecret(args, ctx, deps = {}) {
         throw new UsageError(sub === "set" ? "secret set takes one NAME" : "secret import takes one file (a .env file)");
     }
     const repo = requireRepo(args, sub);
-    return sub === "set" ? setOne(args, ctx, deps, rest[0], repo) : importFile(args, ctx, rest[0], repo);
+    return sub === "set" ? setOne(args, ctx, deps, rest[0], repo) : importFile(args, ctx, rest[0], repo, requestedNames(args));
+}
+function requestedNames(args) {
+    const raw = flagList(args, "names");
+    if (raw.length === 0)
+        return undefined;
+    const names = [...new Set(raw.flatMap((part) => part.split(",").map((name) => name.trim())).filter(Boolean))].sort();
+    if (names.length === 0)
+        throw new UsageError("--names needs one or more variable names");
+    const invalid = names.find((name) => !NAME_RE.test(name));
+    if (invalid !== undefined)
+        throw new UsageError(`--names includes an invalid env-style name: ${invalid}`);
+    return names;
 }
 async function setOne(args, ctx, deps, name, repo) {
     if (!NAME_RE.test(name))
@@ -150,7 +163,7 @@ async function setOne(args, ctx, deps, name, repo) {
         ctx.stdout(line);
     return 0;
 }
-async function importFile(args, ctx, file, repo) {
+async function importFile(args, ctx, file, repo, names) {
     if (flagString(args, "command") !== undefined)
         throw new UsageError("--command belongs to secret set");
     let text;
@@ -160,6 +173,9 @@ async function importFile(args, ctx, file, repo) {
     catch (err) {
         throw new UsageError(`could not read ${file}: ${err instanceof Error ? err.message : String(err)}`);
     }
+    const filtered = names === undefined ? { text, found: [] } : filterEnvFileNames(text, new Set(names));
+    if (names !== undefined)
+        text = filtered.text;
     const cfg = requireConfig(ctx);
     const rotate = flagList(args, "rotate");
     const res = await apiClient(cfg, ctx).postJson(SECRETS_IMPORT_PATH, { repo, text, rotateExisting: rotate, source: `import: ${basename(file)}` }, { accept: ACCEPT });
@@ -175,13 +191,18 @@ async function importFile(args, ctx, file, repo) {
     const rotated = body.rotated ?? [];
     const errors = body.errors ?? [];
     if (args.json) {
-        ctx.stdout(JSON.stringify({ repo, created, rotated, errors, declared: body.declared ?? null }));
+        ctx.stdout(JSON.stringify({ repo, created, rotated, errors, declared: body.declared ?? null, ...(names === undefined ? {} : { requested: names, notFoundInFile: names.filter((name) => !filtered.found.includes(name)) }) }));
         return errors.length > 0 ? 1 : 0;
     }
     const stored = created.length + rotated.length;
     ctx.stdout(stored === 0 ? `stored nothing for ${repo}` : `stored ${stored} for ${repo}: ${[...created, ...rotated].join(", ")}`);
     if (rotated.length > 0)
         ctx.stdout(`  replaced: ${rotated.join(", ")}`);
+    if (names !== undefined) {
+        const missing = names.filter((name) => !filtered.found.includes(name));
+        if (missing.length > 0)
+            ctx.stdout(`not found in ${basename(file)}: ${missing.join(", ")}`);
+    }
     for (const e of errors)
         ctx.stdout(`not stored: ${e.name} (${IMPORT_REASONS[e.reason] ?? e.reason})`);
     for (const line of renderDeclared(body.declared, repo))

package/dist/var.js

@@ -0,0 +1,118 @@
+// var.ts — plain repository/workspace environment values. Values are sent only to the private
+// /me/env-vars routes and are never included in CLI output.
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { flagList, flagString, positionals } from "./args.js";
+import { requireConfig } from "./config.js";
+import { readContractCache } from "./contract.js";
+import { UsageError } from "./errors.js";
+import { parseEnvAssignments } from "./env/parse-env.js";
+import { promptSecret, stdinIsTty } from "./prompt.js";
+import { apiClient } from "./transport.js";
+export const ENV_VARS_PATH = "/me/env-vars";
+const NAME_RE = /^[A-Z][A-Z0-9_]*$/;
+const REPO_RE = /^[^/\s]+\/[^/\s]+$/;
+const ACCEPT = [400, 401, 403, 404, 409, 422];
+function scope(args) {
+    const repo = flagString(args, "repo");
+    if (repo !== undefined && !REPO_RE.test(repo))
+        throw new UsageError(`--repo must be owner/name (got "${repo}")`);
+    return repo === undefined ? { scope: "tenant" } : { scope: "repo", repo };
+}
+function selectedNames(args) {
+    const raw = flagList(args, "names");
+    if (raw.length === 0)
+        return undefined;
+    const names = [...new Set(raw.flatMap((part) => part.split(",").map((name) => name.trim())).filter(Boolean))].sort();
+    if (names.length === 0)
+        throw new UsageError("--names needs one or more variable names");
+    const bad = names.find((name) => !NAME_RE.test(name));
+    if (bad !== undefined)
+        throw new UsageError(`--names includes an invalid env-style name: ${bad}`);
+    return names;
+}
+function scopeBody(target, ctx) {
+    if (target.scope === "tenant")
+        return { scope: "tenant" };
+    const [owner, name] = target.repo.split("/");
+    const repositories = readContractCache(ctx.home)?.doc.merge.repositories ?? [];
+    const repo = repositories.find((entry) => entry.owner.toLocaleLowerCase() === owner.toLocaleLowerCase() && entry.name.toLocaleLowerCase() === name.toLocaleLowerCase());
+    if (!repo)
+        throw new UsageError(`--repo ${target.repo} is not in the cached workspace contract; refresh catalyst contract and try again`);
+    return { scope: "repo", repoId: repo.repoId };
+}
+async function stdinText() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}
+export async function cmdVar(args, ctx, deps = {}) {
+    const [sub, ...rest] = positionals(args);
+    if (sub !== "set" && sub !== "import")
+        throw new UsageError(`unknown var subcommand "${sub ?? ""}": set | import`);
+    if (rest.length !== 1)
+        throw new UsageError(sub === "set" ? "var set takes one NAME" : "var import takes one file (a .env file)");
+    const target = scope(args);
+    const writeScope = scopeBody(target, ctx);
+    const cfg = requireConfig(ctx);
+    const client = deps.client ?? apiClient(cfg, ctx);
+    if (sub === "set") {
+        const name = rest[0];
+        if (!NAME_RE.test(name))
+            throw new UsageError(`"${name}" is not an env-style name (A-Z, 0-9 and _, starting with a letter)`);
+        const raw = (deps.isTty ?? stdinIsTty)()
+            ? await (deps.prompt ?? promptSecret)(`Value for ${name} (input hidden): `)
+            : await (deps.readStdin ?? stdinText)();
+        const value = raw.endsWith("\r\n") ? raw.slice(0, -2) : raw.endsWith("\n") ? raw.slice(0, -1) : raw;
+        if (value.length === 0)
+            throw new UsageError("var set needs a non-empty value");
+        const reply = await client.postJson(ENV_VARS_PATH, { ...writeScope, name, value }, { accept: ACCEPT });
+        if (reply.status !== 200 && reply.status !== 201) {
+            ctx.stderr(`var set refused (${reply.status}): ${reply.body.message ?? reply.body.error ?? "no reason given"}`);
+            return 1;
+        }
+        if (args.json)
+            ctx.stdout(JSON.stringify({ name, scope: target.scope, repo: target.repo ?? null, created: reply.body.created ?? null }));
+        else
+            ctx.stdout(`stored ${name} (${target.scope}${target.repo ? `: ${target.repo}` : ""}${reply.body.created ? "; new" : "; updated"})`);
+        return 0;
+    }
+    let text;
+    try {
+        text = readFileSync(rest[0], "utf8");
+    }
+    catch (err) {
+        throw new UsageError(`could not read ${rest[0]}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const names = selectedNames(args);
+    const entries = parseEnvAssignments(text, names === undefined ? undefined : new Set(names));
+    const found = new Set(entries.map(({ name }) => name));
+    const created = [];
+    const updated = [];
+    const errors = [];
+    for (const entry of entries) {
+        const reply = await client.postJson(ENV_VARS_PATH, { ...writeScope, ...entry }, { accept: ACCEPT });
+        if (reply.status !== 200 && reply.status !== 201) {
+            errors.push({ name: entry.name, reason: reply.body.message ?? reply.body.error ?? `HTTP ${reply.status}` });
+        }
+        else if (reply.body.created)
+            created.push(entry.name);
+        else
+            updated.push(entry.name);
+    }
+    const absent = names?.filter((name) => !found.has(name)) ?? [];
+    if (args.json)
+        ctx.stdout(JSON.stringify({ scope: target.scope, repo: target.repo ?? null, created, updated, errors, ...(names === undefined ? {} : { requested: names, notFoundInFile: absent }) }));
+    else {
+        const count = created.length + updated.length;
+        ctx.stdout(count === 0 ? `stored nothing (${target.scope}${target.repo ? `: ${target.repo}` : ""})` : `stored ${count} variables: ${[...created, ...updated].join(", ")}`);
+        if (updated.length > 0)
+            ctx.stdout(`  updated: ${updated.join(", ")}`);
+        if (absent.length > 0)
+            ctx.stdout(`not found in ${basename(rest[0])}: ${absent.join(", ")}`);
+        for (const error of errors)
+            ctx.stdout(`not stored: ${error.name} (${error.reason})`);
+    }
+    return errors.length > 0 ? 1 : 0;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.13.1",
-  "description": "Customer skill bundle for Catalyst Cloud, named from the executive's seat — get set up, see what is happening, see what needs you, run a project, unstick what is stuck — plus the catalyst CLI that reads through the Catalyst Cloud SDK, writes through the agent proxy, and connects your machine to your cloud account with one command. The skills directory is the roster; this line never counts it.",
+  "version": "0.14.1",
+  "description": "Customer skill bundle for Catalyst Cloud, named from the executive's seat \u2014 get set up, see what is happening, see what needs you, run a project, unstick what is stuck \u2014 plus the catalyst CLI that reads through the Catalyst Cloud SDK, writes through the agent proxy, and connects your machine to your cloud account with one command. The skills directory is the roster; this line never counts it.",
   "license": "MIT",
   "type": "module",
   "publishConfig": {
@@ -50,6 +50,7 @@
   },
   "dependencies": {
     "@catalyst-cloud/sdk": "^0.13.1",
+    "smol-toml": "^1.7.1",
     "yaml": "^2.9.0"
   },
   "devDependencies": {

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.13.1 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.1 — 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 local replica when it is fresh and the origin-fresh API otherwise, 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.13.1 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.1 — 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.13.1 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.1 — written in this repository for customer accounts -->
 
 # Onboard me
 

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

@@ -1,17 +1,24 @@
-# Declaring what one repository's containers need
+# Drafting one repository's settings
 
-The cloud containers build and test the repository and need the names of the variables and secrets it reads. You write the names; the person enters the values in the app. Never read or print a value. Say which files you will read and what you will write, and wait for a yes. An existing file gets verified against the inventory, not rewritten.
+The assistant prepares `.catalyst/catalyst.toml` from the repository. Never ask the person to write TOML or copy environment names by hand. Never read or print values from `.env`, CI secrets, or other local secret stores.
 
-## The inventory, in order
+## Inspect before drafting
 
-1. Start from what builds and tests the repository: the README's setup section, the scripts in `package.json` or its equivalent, and CI's build and test steps. A name none of them reads does not belong in the file.
-2. Tie each name to the file it came from: a `.env.example` (never `.env`, which holds live values), a CI secret in a workflow's `env:` block, or a platform binding. A name you cannot tie to a file is a guess; say so instead of listing it.
-3. Leave out platform bindings and deploy-only secrets, since containers build and test but never deploy, unless the person says the build needs one.
-4. Write the names into `.catalyst/catalyst.toml`, the only file the cloud reads, and open a pull request. Each merged change to it is proposed as a new revision, which an owner or admin approves at Settings → Repositories → the repository → Environment → Setup declaration → Approve this revision; the person enters values on that page's Environment variables and Secrets tabs.
+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.
+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.
 
-## The file's shape
+## Ask before writing or opening the PR
 
-`[project]` with `linear_team` is required; every other section is optional.
+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. Once merged, give the owner or admin a direct link to approve the new declaration revision 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
+
+`[project]` with `linear_team` is required; other sections are optional. Environment names belong under `[[environment.variables]]`:
 
 ```toml
 #:schema https://staging.catalystcloud.dev/schemas/catalyst.schema.json
@@ -21,11 +28,11 @@ linear_team = "ENG"
 
 [[environment.variables]]
 name = "DATABASE_URL"
-required = true
+required = false
 
 [[environment.variables]]
 name = "STRIPE_API_KEY"
-required = true
+required = false
 secret = true
 
 [[environment.setup]]
@@ -33,4 +40,4 @@ name = "install"
 run = ["npm", "ci"]
 ```
 
-`linear_team` is the Linear team's key. `run` is an argument list, not a shell string, and `name` is kebab-case; `verify` steps share the shape and carry the test commands. The schema lists the optional tables (`toolchains`, `system_packages`, `services`). After the merge, `catalyst ready` reports `environment_declared` with the next step.
+`run` is an argument list, not a shell string. `verify` steps use the same shape and carry the repository's test commands. Secret and variable values belong in Catalyst Cloud, never in this file.

package/skills/catalyst-onboard/references/reading-ready.md

@@ -46,7 +46,7 @@ A team is `ready`, `degraded`, `blocked` or `unchecked` (no pass yet, a note). S
 | `hosts_current` | no connected host runs an older mapping | `references/what-a-phase-needs.md`; `no_host_connected` is waiting | whoever runs that host |
 | `environment_declared` | the default repository's `.catalyst/catalyst.toml` is ingested, valid and approved | the reason names the step: register a default repository, commit or fix the file, or approve it (`references/declaring-a-repository.md`) | owner or admin, except committing the file, which is whoever can push |
 | `tools_resolvable` | every MCP server and CLI the declaration names resolves | `tool_reference_unresolved`: add the secret or fix the declaration; `toolchain_cli_missing` is not self-service | owner or admin, in the declaration or Settings → Environment |
-| `reviewer_required` | the repository can merge under its policy | a strict policy with no reviewer: configure one at Settings → Repositories → Code reviews, or relax the policy; only the merge waits | owner or admin, in settings |
+| `reviewer_required` | the repository can merge under its policy | a strict policy with no reviewer: configure one at Settings → Your projects → the project → Repositories → the repository → Code reviews, or relax the policy; only the merge waits | owner or admin, in settings |
 | `reviewer_configured` | a code reviewer is configured at all | configure one there; a fail never blocks or degrades | owner or admin, in settings; nobody is required when it fails |
 
 ## The machine checks the CLI adds

package/skills/catalyst-onboard/references/the-one-path.md

@@ -12,7 +12,7 @@ Only when the script says the machine is not connected: ask "Shall I start the l
 
 ## 1b. Leftovers of the old local runtime
 
-Only when the script notes them (from the CLI's fixed list; current jobs are never on it); left in place they can start old jobs or shadow current commands. Ask once, recommending it: "Shall I remove the old runtime's leftovers now? It keeps your data folders." On a yes, run `catalyst legacy --remove --yes` and read back its `removed:` and `re-checked:` lines; offer `--data` separately. On a no, the note stays.
+Only when the script notes them (from the CLI's fixed list; current jobs are never on it); left in place they can start old jobs or shadow current commands. Ask once, recommending it: "Shall I remove the old runtime's leftovers now? It keeps your data folders." On a yes, run `catalyst legacy --remove --yes` and read back its `removed:` and `re-checked:` lines; keep all shared data folders. Never offer data deletion. On a no, the note stays.
 
 ## 2. A coding account
 
@@ -28,7 +28,7 @@ A card moved into an unmapped project does nothing, the most common reason a new
 
 `catalyst team list` shows the teams without checking readiness; the person picks one key. `catalyst team map <KEY>` or `catalyst team adopt <KEY>` prints a preview to approve before `--yes --plan-hash <hash>` (exit 3 applied nothing). Run `catalyst team check <KEY>` only for the selected team. `team migrate <KEY>`, its `--retire`, and `team adopt <KEY> --undo` each preview and need their own approval. `catalyst capabilities` says which verbs this cloud serves.
 
-A `blocked` project is not set up. Linear's own Git automation rules change only in Linear (Settings → Teams → the team → Workflow → Git automation → No action); hand that over, then re-check.
+A `blocked` project is not set up. Change Linear's own Git automation rules in Linear for now (Settings → Teams → the team → Workflow → Workflows & automations → Pull request and commit automations → No action); hand that over, then re-check.
 
 ## 5. Install the GitHub App
 
@@ -36,7 +36,7 @@ Without it Catalyst cannot touch code. On the same page, the owner or admin inst
 
 ## 6. Register the repository
 
-On `<their cloud>/settings/repositories`, add the repository **and attach it to the project from step 4** in the same form. A repository registered without a project is listed and never receives work.
+On `<their cloud>/settings/projects`, add the repository **and attach it to the project from step 4** in the same form. A repository registered without a project is listed and never receives work.
 
 ## 7. Connect your own accounts
 
@@ -44,7 +44,7 @@ The person's own logins, so work done for them is attributed to them and their a
 
 ## 8. The repository's settings file
 
-Ask "Shall I draft it from your repository's own build files?", then follow `references/declaring-a-repository.md`. Mention the approval after the merge as context, not a second task. A workspace-wide declaration goes through `catalyst environment` (read, propose, `--approve`).
+Inspect and draft the repository settings file yourself from its build and test files; follow `references/declaring-a-repository.md`. Show the summary and get approval before writing or opening the PR. Mention the declaration approval after merge as context, not a second task. A workspace-wide declaration goes through `catalyst environment` (read, propose, `--approve`).
 
 Once you know the checkout path, rerun `node scripts/where-am-i.mjs --next --repo <path>` (a read) and follow `references/repository-agent-setup.md` for the offers it notes.
 

package/skills/catalyst-onboard/references/what-the-browser-owns.md

@@ -8,7 +8,7 @@ Each is an authorization a person grants in their own session, so no command wil
 | -- | -- |
 | approving the login | the URL and short code `catalyst login` printed |
 | enrolling a coding account, or replacing its credential | the AI accounts page the script printed |
-| connecting the Linear integration, installing the GitHub App | `<their cloud>/settings/connections` |
+| connecting the Linear integration, installing the GitHub App | `<their cloud>/settings/connections` (Settings → Integrations) |
 | creating `<your GitHub org>/thoughts` and letting the App reach it | GitHub, then the App's installation page for that org: All repositories, or add `thoughts` (step 5 of `references/the-one-path.md`) |
 | connecting personal Linear, then personal GitHub | the URL `catalyst connections personal <linear\|github> start` printed |
 
@@ -18,7 +18,7 @@ Their routes take a browser session, not a key. Call them gaps, route the person
 
 | step | where |
 | -- | -- |
-| registering a repository and attaching it to a project | `<their cloud>/settings/repositories` |
+| registering a repository and attaching it to a project | `<their cloud>/settings/projects` (Settings → Your projects) |
 | approving one repository's declaration, and entering its values | that repository's Environment page (`references/declaring-a-repository.md`) |
 
 `catalyst environment` handles a workspace-wide declaration. ⛔ Only the CLI makes requests; if you find yourself building a URL for one of these, stop.

package/skills/catalyst-onboard/scripts/lib/project-coverage.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// Shared coverage formatter used by where-am-i; --help documents its input contract.
+if (process.argv.includes("--help")) {
+  process.stdout.write(
+    "Usage: imported by where-am-i; compares project rows with saved team stage mappings.\n",
+  );
+  process.exit(0);
+}
+
+/** Compare the full Catalyst project inventory with teams that actually have saved stage rows. */
+export function projectCoverage(projects, teams) {
+  const mappedTeamIds = new Set(
+    teams
+      .filter(
+        (team) =>
+          team &&
+          (team.id ?? team.teamId) &&
+          team.stages &&
+          Object.keys(team.stages).length > 0,
+      )
+      .map((team) => team.id ?? team.teamId),
+  );
+  const mapped = [];
+  const unmapped = [];
+  for (const project of projects) {
+    (mappedTeamIds.has(project.linearTeamId) ? mapped : unmapped).push(project);
+  }
+  return { mapped, unmapped, total: projects.length };
+}
+
+export function projectCoverageLines(projects, teams) {
+  const coverage = projectCoverage(projects, teams);
+  const teamById = new Map(teams.map((team) => [team.id ?? team.teamId, team]));
+  const lines = [
+    `${coverage.mapped.length} of your ${coverage.total} projects have their Linear team mapped.`,
+  ];
+  for (const project of coverage.mapped) {
+    const team = teamById.get(project.linearTeamId);
+    const readiness = team?.readiness ?? {};
+    const bad = Array.isArray(readiness.checks)
+      ? readiness.checks.filter((check) => check.state !== "pass")
+      : [];
+    lines.push(
+      `${project.name} (${project.linearTeamKey ?? team?.teamKey ?? project.linearTeamId}): ${readiness.status ?? "unchecked"}${bad.length ? ` — ${bad.map((check) => `${check.id} ${check.state}`).join(", ")}` : ""}`,
+    );
+  }
+  if (coverage.unmapped.length > 0) {
+    lines.push(
+      `These ${coverage.unmapped.length} do not: ${coverage.unmapped.map((project) => project.name).join(", ")}`,
+    );
+  }
+  return { ...coverage, lines };
+}