@catalyst-cloud/cli 0.9.4 → 0.13.0

package/dist/team.js

@@ -0,0 +1,329 @@
+// Team setup uses the person's saved login and the SDK's typed personal-admin methods.
+// A fresh SDK client per call refreshes a device-login token across a multi-chunk migration.
+import { createHash } from "node:crypto";
+import { flagBool, flagList, flagString, positionals } from "./args.js";
+import { requireConfig } from "./config.js";
+import { loadContract } from "./contract.js";
+import { UsageError } from "./errors.js";
+import { bearerFor } from "./oauth.js";
+import { loadHttpSdk } from "./sdk.js";
+const SLOTS = ["dispatch", "intake", "research", "plan", "implement", "remediate", "verify", "review", "pr", "done", "canceled"];
+function isSlot(value) { return SLOTS.includes(value); }
+const NAMES = {
+    dispatch: ["todo", "to do", "ready"], intake: ["intake", "triage"], research: ["research"],
+    plan: ["plan", "planning"], implement: ["implement", "in progress", "doing"],
+    remediate: ["remediate", "fix"], verify: ["verify", "validate", "testing"], review: ["review"],
+    pr: ["pr", "in review", "pull request"], done: ["done", "completed"], canceled: ["canceled", "cancelled"],
+};
+const MAX_CHUNKS = 100;
+const MAX_RUN_MS = 5 * 60_000;
+function routes(doc) {
+    const read = doc.routes.find((r) => r.method === "GET" && r.path.endsWith("/team-workflow"))?.path;
+    if (!read)
+        throw new UsageError("team setup needs a newer Catalyst Cloud (team-workflow route absent)");
+    const desired = { teams: read.replace(/\/team-workflow$/, "/teams"), read, check: `${read}/check`, save: `${read}/save`, adopt: `${read}/adopt`, undo: `${read}/adopt-undo`, migrate: `${read}/migrate` };
+    for (const [name, path] of Object.entries(desired)) {
+        const method = name === "teams" || name === "read" ? "GET" : "POST";
+        if (!doc.routes.some((r) => r.method === method && r.path === path))
+            throw new UsageError(`team setup needs a newer Catalyst Cloud (${method} ${path} absent)`);
+    }
+    return desired;
+}
+function key(args) {
+    const [sub, team, ...extra] = positionals(args);
+    if (extra.length > 0)
+        throw new UsageError(`team ${sub ?? ""} takes one team key`);
+    if (!team && !(sub === "list" || (sub === "check" && flagBool(args, "all"))))
+        throw new UsageError(`team ${sub ?? ""} needs a team key`);
+    if (team && flagBool(args, "all"))
+        throw new UsageError("team check takes a key or --all, not both");
+    return team ?? "";
+}
+function emit(ctx, args, value, lines) {
+    if (args.json)
+        ctx.stdout(JSON.stringify(value));
+    else
+        for (const line of lines)
+            ctx.stdout(line);
+}
+function refusal(ctx, args, reply) {
+    const { body, status } = reply;
+    emit(ctx, args, { status, ...body }, [`refused (${status}): ${String(body.error ?? "http")}${body.reason || body.message ? ` — ${String(body.reason ?? body.message)}` : ""}`]);
+    return 1;
+}
+function readinessLines(value) {
+    if (value === null || typeof value !== "object")
+        return ["the change landed, but readiness could not be checked; run team check"];
+    const r = value;
+    return [`readiness: ${String(r.status ?? "unknown")}; checked at ${String(r.checkedAt ?? "unknown")}`,
+        ...(Array.isArray(r.checks) ? r.checks : []).filter((c) => c.state === "fail").map((c) => `  ${String(c.id)}: ${String(c.reason ?? "failed")} (${String(c.owner ?? c.whoCanFix ?? "team admin")})`)];
+}
+function fromSdk(result) {
+    if (result.outcome === "ok") {
+        const { outcome: _outcome, status, ...body } = result;
+        return { status, body: body };
+    }
+    return {
+        status: result.outcome === "shape" ? 502 : "status" in result ? result.status : 503,
+        body: { error: "error" in result ? result.error ?? result.outcome : result.outcome, reason: result.reason, ...(result.outcome === "shape" ? { upstreamStatus: result.status } : {}) },
+    };
+}
+function isRefusal(reply) { return typeof reply.body.error === "string" || !((reply.status >= 200 && reply.status < 300) || reply.status === 304); }
+function assignments(values, label) {
+    return values.map((value) => {
+        const split = value.indexOf("=");
+        if (split <= 0 || split === value.length - 1)
+            throw new UsageError(`--${label} needs left=right (got ${value})`);
+        return [value.slice(0, split), value.slice(split + 1)];
+    });
+}
+function mapping(view, explicit) {
+    if (view.stageSource === "none" || !Array.isArray(view.stages))
+        throw new UsageError("live Linear stages are unreadable; retry team map after the connection is healthy");
+    const stages = view.stages;
+    const selected = new Map();
+    const unresolved = [];
+    if (explicit.length > 0) {
+        for (const [slot, stateName] of explicit) {
+            if (!isSlot(slot))
+                throw new UsageError(`unknown workflow role: ${slot}`);
+            if (selected.has(slot))
+                throw new UsageError(`duplicate workflow role: ${slot}`);
+            const found = stages.filter((s) => s.name.toLocaleLowerCase() === stateName.toLocaleLowerCase() || s.id === stateName);
+            if (found.length !== 1)
+                throw new UsageError(`${stateName} matches ${found.length} live Linear stages; choose an unambiguous name or id`);
+            selected.set(slot, found[0].id);
+        }
+    }
+    else {
+        for (const slot of SLOTS) {
+            const names = NAMES[slot] ?? [];
+            const match = names.flatMap((name) => stages.filter((stage) => stage.name.toLocaleLowerCase() === name));
+            const unique = [...new Map(match.map((stage) => [stage.id, stage])).values()];
+            if (unique.length === 1)
+                selected.set(slot, unique[0].id);
+            else
+                unresolved.push(slot);
+        }
+    }
+    const previous = new Map((view.rows ?? []).map((r) => [r.slot, r.linearStateId]));
+    const diff = SLOTS.map((slot) => {
+        const before = previous.get(slot) ?? null;
+        const after = selected.get(slot) ?? null;
+        return { slot, before, after, change: before === after ? "unchanged" : before === null ? "added" : after === null ? "removed" : "changed" };
+    });
+    return { rows: SLOTS.filter((slot) => selected.has(slot)).map((slot) => ({ slot, linearStateId: selected.get(slot), source: "chosen" })), diff, unresolved };
+}
+function hashPlan(value) { return createHash("sha256").update(JSON.stringify(value)).digest("hex"); }
+function planLines(title, rows, hash) {
+    return [title, ...rows.map((row) => `  ${JSON.stringify(row)}`), `Plan hash: ${hash}`, `Review this plan with the person, then rerun with --yes --plan-hash ${hash} to apply exactly it.`];
+}
+export async function cmdTeam(args, ctx, deps = {}) {
+    const [sub] = positionals(args);
+    if (!sub || !["list", "check", "map", "adopt", "migrate", "checklist"].includes(sub))
+        throw new UsageError("team needs list | check | map | adopt | migrate | checklist");
+    const team = key(args);
+    if (sub !== "check" && flagBool(args, "all"))
+        throw new UsageError("--all belongs to team check");
+    if (sub !== "adopt" && flagBool(args, "undo"))
+        throw new UsageError("--undo belongs to team adopt");
+    if (sub !== "migrate" && (flagBool(args, "retire") || flagList(args, "choice").length))
+        throw new UsageError("--retire and --choice belong to team migrate");
+    if (sub !== "map" && flagList(args, "stage").length)
+        throw new UsageError("--stage belongs to team map");
+    if (!["map", "adopt", "migrate"].includes(sub) && flagString(args, "plan-hash") !== undefined)
+        throw new UsageError("--plan-hash belongs to team map, adopt, or migrate");
+    if ((sub === "check" || sub === "checklist") && flagBool(args, "yes"))
+        throw new UsageError(`team ${sub} takes no --yes`);
+    const cfg = requireConfig(ctx);
+    let { doc } = await loadContract(ctx, cfg);
+    try {
+        routes(doc);
+    }
+    catch (error) {
+        if (!(error instanceof UsageError) || !error.message.includes("team-workflow"))
+            throw error;
+        // A fresh cached contract can predate the team routes. Revalidate once before telling the
+        // person the cloud is too old; the conditional GET is cheap when the server has not changed.
+        doc = (await loadContract(ctx, cfg, { refresh: true })).doc;
+        routes(doc);
+    }
+    // API hashes detect stale server state. CLI approval additionally binds the reviewed scope,
+    // operation and signed-in tenant so consent cannot transfer to a different command or account.
+    const approvalHash = (operation, plan) => hashPlan({ baseUrl: cfg.baseUrl, account: cfg.account, actor: cfg.user?.id ?? null, team, operation, plan });
+    const createClient = deps.createClient ?? (async (options) => (await loadHttpSdk()).createTenantClient(options));
+    const client = async () => (await createClient({ key: await bearerFor(ctx, cfg), baseUrl: cfg.baseUrl, fetch: ctx.fetch })).teamWorkflow;
+    if (sub === "list") {
+        const reply = fromSdk(await (await client()).teams());
+        if (isRefusal(reply))
+            return refusal(ctx, args, reply);
+        if (!Array.isArray(reply.body.teams))
+            return refusal(ctx, args, { status: 502, body: { error: "bad-response", reason: "team list was missing" } });
+        const teams = reply.body.teams;
+        emit(ctx, args, { teams, liveTeamRead: reply.body.liveTeamRead }, teams.map((t) => `${String(t.teamKey ?? t.teamId ?? t.key ?? "unknown")}: ${String(t.name ?? t.teamName ?? "")}`));
+        return 0;
+    }
+    if (sub === "check") {
+        const teamList = flagBool(args, "all") ? fromSdk(await (await client()).teams()) : null;
+        if (teamList && isRefusal(teamList))
+            return refusal(ctx, args, teamList);
+        const teamKeys = teamList ? (Array.isArray(teamList.body.teams) ? teamList.body.teams : []).map((t) => String(t.teamKey || t.teamId || t.key || "")).filter(Boolean) : [team];
+        if (teamList && !Array.isArray(teamList.body.teams))
+            return refusal(ctx, args, { status: 502, body: { error: "bad-response", reason: "team list was missing" } });
+        if (teamList && teamKeys.length === 0)
+            return refusal(ctx, args, { status: 404, body: { error: "no-teams", reason: "No Linear teams are visible to this account; connect the tenant's Linear workspace and retry." } });
+        const results = [];
+        let failed = false;
+        for (const teamKey of teamKeys) {
+            const reply = fromSdk(await (await client()).check(teamKey));
+            if (isRefusal(reply)) {
+                results.push({ team: teamKey, status: reply.status, ...reply.body });
+                failed = true;
+                break;
+            }
+            results.push({ team: teamKey, ...reply.body });
+            if (reply.body.readiness?.status !== "ready")
+                failed = true;
+        }
+        emit(ctx, args, { results }, results.flatMap((result) => [`${String(result.team)}:`, ...(result.error ? [`  refused: ${String(result.error)} — ${String(result.reason ?? result.message ?? "")}`] : readinessLines(result.readiness))]));
+        return failed ? 1 : 0;
+    }
+    if (sub === "checklist") {
+        const reply = fromSdk(await (await client()).get(team));
+        if (isRefusal(reply))
+            return refusal(ctx, args, reply);
+        const checklist = reply.body.checklist;
+        if (!Array.isArray(checklist) || !checklist.every((line) => typeof line === "string"))
+            return refusal(ctx, args, { status: 503, body: { error: "stages-unreadable", reason: "Could not read live Linear stages; retry team checklist." } });
+        emit(ctx, args, { team, checklist }, checklist);
+        return 0;
+    }
+    if (sub === "map") {
+        const reply = fromSdk(await (await client()).get(team));
+        if (isRefusal(reply))
+            return refusal(ctx, args, reply);
+        if (typeof reply.body.mappingHash !== "string")
+            return refusal(ctx, args, { status: 502, body: { error: "bad-response", reason: "team workflow read omitted the mapping hash; update Catalyst Cloud before saving" } });
+        let proposal;
+        try {
+            proposal = mapping(reply.body, assignments(flagList(args, "stage"), "stage"));
+        }
+        catch (error) {
+            return refusal(ctx, args, { status: 400, body: { error: "mapping-unresolved", reason: error instanceof Error ? error.message : String(error) } });
+        }
+        const config = reply.body.config && typeof reply.body.config === "object" ? reply.body.config : undefined;
+        const mode = config?.mode ?? "mapped-existing";
+        const gitAutomation = config?.gitAutomation ?? "off";
+        const planHash = approvalHash("map", { team, rows: proposal.rows, diff: proposal.diff, unresolved: proposal.unresolved, mappingHash: reply.body.mappingHash, mode, gitAutomation });
+        const preview = { team, rows: proposal.rows, diff: proposal.diff, unresolved: proposal.unresolved, mappingHash: reply.body.mappingHash, mode, gitAutomation, planHash, decision: "not-confirmed" };
+        if (!flagBool(args, "yes")) {
+            emit(ctx, args, preview, planLines(`Mapping plan for ${team}:`, proposal.diff, planHash));
+            return 3;
+        }
+        if (flagString(args, "plan-hash") !== planHash)
+            return refusal(ctx, args, { status: 409, body: { error: "plan-hash-mismatch", reason: `Preview again and review the updated plan hash ${planHash}.` } });
+        if (!args.json)
+            for (const line of planLines(`Mapping plan for ${team}:`, proposal.diff, planHash).slice(0, -1))
+                ctx.stdout(line);
+        const saved = fromSdk(await (await client()).save({ team, mode, gitAutomation, rows: proposal.rows, expectedMappingHash: reply.body.mappingHash }));
+        if (isRefusal(saved))
+            return refusal(ctx, args, saved);
+        emit(ctx, args, { ...preview, decision: "applied", result: saved.body }, readinessLines(saved.body.readiness));
+        return 0;
+    }
+    if (sub === "adopt") {
+        const undo = flagBool(args, "undo");
+        const previewReply = fromSdk(undo ? await (await client()).undoPreview(team) : await (await client()).adoptPreview(team));
+        if (isRefusal(previewReply))
+            return refusal(ctx, args, previewReply);
+        const hashName = undo ? "undoHash" : "planHash";
+        const hash = previewReply.body[hashName];
+        if (typeof hash !== "string" || !Array.isArray(previewReply.body[undo ? "candidates" : "stages"]))
+            return refusal(ctx, args, { status: 502, body: { error: "bad-response", reason: `adopt preview omitted ${hashName} or scope` } });
+        const planHash = approvalHash(undo ? "adopt-undo" : "adopt", {
+            serverHash: hash, teamId: previewReply.body.teamId,
+            stages: previewReply.body.stages, labels: previewReply.body.labels,
+            candidates: previewReply.body.candidates, unfilledLoadBearing: previewReply.body.unfilledLoadBearing,
+        });
+        const plan = { team, decision: "not-confirmed", preview: previewReply.body, planHash };
+        const scope = [
+            ...previewReply.body[undo ? "candidates" : "stages"],
+            ...(undo ? [] : Array.isArray(previewReply.body.labels) ? previewReply.body.labels : []),
+        ];
+        if (!flagBool(args, "yes")) {
+            emit(ctx, args, plan, planLines(`${undo ? "Undo" : "Adopt"} plan for ${team}:`, scope, planHash));
+            return 3;
+        }
+        if (flagString(args, "plan-hash") !== planHash)
+            return refusal(ctx, args, { status: 409, body: { error: "plan-hash-mismatch", reason: `Preview again and review the updated plan hash ${planHash}.` } });
+        if (!args.json)
+            for (const line of planLines(`${undo ? "Undo" : "Adopt"} plan for ${team}:`, scope, planHash).slice(0, -1))
+                ctx.stdout(line);
+        const applied = fromSdk(undo ? await (await client()).undoApply(team, hash) : await (await client()).adoptApply(team, hash));
+        if (isRefusal(applied))
+            return refusal(ctx, args, applied);
+        const outcomes = (undo ? [applied.body.archived, applied.body.kept, applied.body.failed] : [applied.body.stages, applied.body.labels, applied.body.labelsNotCreated, applied.body.provenanceGaps, applied.body.labelProvenanceGaps]).flatMap((v) => Array.isArray(v) ? v : []);
+        emit(ctx, args, { team, decision: "applied", preview: previewReply.body, result: applied.body }, [...outcomes.map((o) => `  ${JSON.stringify(o)}`), ...readinessLines(applied.body.readiness)]);
+        return 0;
+    }
+    const choices = assignments(flagList(args, "choice"), "choice").map(([sourceStateId, destinationStateId]) => ({ sourceStateId, destinationStateId }));
+    const previewReply = fromSdk(await (await client()).migratePreview(team, choices));
+    if (isRefusal(previewReply))
+        return refusal(ctx, args, previewReply);
+    const preview = previewReply.body.preview;
+    if (!preview || typeof preview.migrationHash !== "string" || !Array.isArray(preview.sources))
+        return refusal(ctx, args, { status: 502, body: { error: "bad-response", reason: "migration preview omitted hash or source rows" } });
+    if (preview.actionsAvailable === false)
+        return refusal(ctx, args, { status: 409, body: { error: "migration-approval-unavailable", reason: "Catalyst cannot verify the exact tickets in this migration preview, so moves and retirement are paused. Use Linear's bulk editor to move tickets, or retry when approved migration snapshots are available." } });
+    const step = flagBool(args, "retire") ? "retire" : "migrate";
+    const planHash = approvalHash(step, { preview, choices });
+    const plan = { team, step, decision: "not-confirmed", preview, planHash };
+    const blocked = preview.overLimit || preview.sources.some((source) => source.outcome === "needs-a-choice");
+    if (!flagBool(args, "yes")) {
+        emit(ctx, args, plan, planLines(`Migration ${plan.step} plan for ${team}:`, preview.sources, planHash));
+        return 3;
+    }
+    if (flagString(args, "plan-hash") !== planHash)
+        return refusal(ctx, args, { status: 409, body: { error: "plan-hash-mismatch", reason: `Preview again and review the updated plan hash ${planHash}.` } });
+    if (blocked)
+        return refusal(ctx, args, { status: 400, body: { error: "migration-plan-blocked", reason: "Resolve the preview's blocked sources or issue limit before applying." } });
+    if (!args.json)
+        for (const line of planLines(`Migration ${plan.step} plan for ${team}:`, preview.sources, planHash).slice(0, -1))
+            ctx.stdout(line);
+    const results = [];
+    const deadline = Date.now() + MAX_RUN_MS;
+    let hash = preview.migrationHash;
+    for (let n = 0; n < (step === "retire" ? 1 : MAX_CHUNKS); n++) {
+        if (Date.now() >= deadline)
+            return refusal(ctx, args, { status: 503, body: { error: "migration-time-budget", reason: "The bounded run ended; preview again before continuing." } });
+        const result = fromSdk(step === "retire" ? await (await client()).migrateRetire(team, hash, choices) : await (await client()).migrateChunk(team, hash, choices));
+        if (isRefusal(result))
+            return refusal(ctx, args, result);
+        results.push(result.body);
+        const partial = Array.isArray(result.body.sources) && result.body.sources.some((source) => source.outcome === "partially-moved");
+        if (!args.json) {
+            ctx.stdout(`${step} chunk ${n + 1}: moved ${String(result.body.moved ?? 0)}, remaining ${String(result.body.remaining ?? 0)}`);
+            for (const source of Array.isArray(result.body.sources) ? result.body.sources : [])
+                ctx.stdout(`  ${JSON.stringify(source)}`);
+            for (const [name, value] of Object.entries(result.body))
+                if (name === "failed" || name === "blockers" || name === "logGaps")
+                    ctx.stdout(`  ${name}: ${JSON.stringify(value)}`);
+        }
+        if (partial) {
+            emit(ctx, args, { ...plan, decision: "partial", results }, [`Migration partially completed; at least one source reported a refused or incomplete move.`, ...readinessLines(result.body.readiness)]);
+            return 1;
+        }
+        if (step === "retire" && Array.isArray(result.body.failed) && result.body.failed.length > 0) {
+            emit(ctx, args, { ...plan, decision: "partial", results }, [`Source retirement partially completed: ${JSON.stringify(result.body.failed)}`]);
+            return 1;
+        }
+        if (step === "retire" || result.body.remaining === 0) {
+            emit(ctx, args, { ...plan, decision: "applied", results }, [...readinessLines(result.body.readiness), ...(step === "migrate" ? ["Tickets moved. Retiring source stages requires a separate team migrate --retire confirmation."] : [])]);
+            return 0;
+        }
+        if (typeof result.body.migrationHash !== "string")
+            return refusal(ctx, args, { status: 502, body: { error: "bad-response", reason: "migration chunk omitted the next hash" } });
+        hash = result.body.migrationHash;
+    }
+    return refusal(ctx, args, { status: 503, body: { error: "migration-chunk-limit", reason: "The bounded run ended; preview again before continuing." } });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.9.4",
+  "version": "0.13.0",
   "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 tenant with one command. The skills directory is the roster; this line never counts it.",
   "license": "MIT",
   "type": "module",
@@ -48,13 +48,13 @@
     "paths:check": "node scripts/vendor-paths.mjs --check"
   },
   "dependencies": {
-    "@catalyst-cloud/sdk": "^0.12.0"
+    "@catalyst-cloud/sdk": "^0.13.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/node": "^26.3.0",
     "@vitest/coverage-v8": "^4.1.11",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.11",
-    "yaml": "^2.9.0"
+    "vitest": "^4.1.11"
   }
 }

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-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.4 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.0 — written in this repository for customer tenants -->
 
 # Catalyst's GitHub
 

package/skills/catalyst-linear/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 disable-model-invocation: true
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.4 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.0 — written in this repository for customer tenants -->
 
 # Catalyst Linear
 

package/skills/catalyst-onboard/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: catalyst-onboard
 description: >-
-  Walk a person from nothing to their first Catalyst Cloud ticket running, one step at a time, hand-held. Use when someone says "set me up", "onboard me", "I just signed up", "get me started", "what do I do first", or when they have the Catalyst Cloud skills installed and nothing else. Starts with the coding account, then the project, the integrations and the person's connected accounts, each repository's settings file, and ends with one real ticket moving. Reads each part of the setup with the instrument that owns it, does every step a key can do through the catalyst-skills CLI, and for the steps only a browser can do hands over the exact page and says what to come back with. Never claims a step it did not watch succeed.
+  Walk a person from nothing to their first Catalyst Cloud ticket running, one step at a time, hand-held. Use when someone says "set me up", "onboard me", "I just signed up", "get me started", "what do I do first", or when they have the Catalyst Cloud skills installed and nothing else. Starts with the coding account, then the project, the integrations and the person's connected accounts, each repository's settings file, and ends with one real ticket moving. Reads each part of the setup with the instrument that owns it, does every step a key can do through the catalyst CLI, and for the steps only a browser can do hands over the exact page and says what to come back with. Never claims a step it did not watch succeed.
 disable-model-invocation: true
-allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
+allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.4 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.0 — written in this repository for customer tenants -->
 
 # Onboard me
 
@@ -17,9 +17,9 @@ The path has five stops, in this order: a **coding account** the work will run o
 
 1. Run `node scripts/where-am-i.mjs --next` and read the one line it prints. If a `note:` line follows it, say the note in one clause in the same turn (a cancelled account is kept for reporting, not used, never re-tokened); it is information, not a task.
 2. Say, in one or two sentences, what that step is for. The person should always know why they are doing it.
-3. Ask one question, or do one thing. If it is a command a key can run, run it and show the lines it printed. If it needs a browser, hand over one link, one action named the way the page names it, and say what you will check when they are back.
+3. Ask one question, or do one thing. If it is a command a key can run (the script's `do:` line), run it now without asking whether to, and show the lines it printed. If it needs a browser, hand over one link, one action named the way the page names it, and say what you will check when they are back.
 4. Stop. Wait for their answer.
-5. When they answer, run the script again and read them the part that should have changed. If it changed, say so and move on. If it did not, refresh the contract once (`catalyst-skills contract --refresh`) and read it again; if it still did not, say what the page told them and what the instrument says, and ask what they saw.
+5. When they answer, run the script again and read them the part that should have changed. If it changed, say so and move on. If it did not, refresh the contract once (`catalyst contract --refresh`) and read it again; if it still did not, say what the page told them and what the instrument says, and ask what they saw.
 
 Two or three short sentences per turn is the right size. A turn that lists every part's verdict is a wall of status, not help. The full report exists for you to read, not to paste.
 
@@ -67,8 +67,8 @@ Use the product's words, and name the page label Settings shows today when it di
 - **Not ready is a question about who.** Name which check, who can fix it, and where. If the owner is not the person in front of you, say so and stop.
 - **Never invent a count or a list.** Every number and every name comes from what a command printed.
 - **Provider consent belongs to the person in a browser.** Login approval, the workspace's Linear connection and GitHub App install, and the person's own connected accounts. Give the printed URL, then check `status`. Never claim a grant succeeded because a browser opened.
-- **Some steps a key cannot do yet.** Listing every project, saving a stage mapping, adopting the workflow, registering a repository and approving one repository's settings file are settings-page work today. Route those through the browser and say plainly that it is a gap, not the design. Never guess at a route.
-- **The workspace-wide environment declaration is the one setup write you can perform.** `catalyst-skills environment` reads it, proposes it and approves it.
+- **Team setup is CLI work now; two steps still are not.** `team list`, `team check`, `team map`, `team adopt`, `team migrate` and `team checklist` run with the person's own login: show each preview, and pass `--yes --plan-hash` only after they approve that exact plan. `catalyst capabilities` says what this CLI can do on this cloud, and the script consults it and the person's role before it names a command or a page. Registering a repository and approving one repository's settings file are settings-page work today; route those through the browser and say plainly that it is a gap, not the design. Never guess at a route.
+- **The workspace-wide environment declaration is the one setup write you can perform.** `catalyst environment` reads it, proposes it and approves it.
 - **Local sync is opt-in.** API-backed skills work without it. Ask before running `local-sync.mjs --start`; a detached process starting is not evidence of freshness. See `references/local-sync.md`.
 - **A cancelled or ended coding account is kept, not retired.** It stays for reporting, is not used, and is never given a new token; a token minted from a live login must never land on it. Reactivating it is the person's call if the subscription comes back. Never tell anyone to retire or delete it.
 - **Their workspace, as them.** Everything goes through the CLI and the person's own login. You never name another workspace, never ask for a key you could avoid, and never see a credential or a secret's value.

package/skills/catalyst-onboard/references/choosing-a-coding-account.md

@@ -29,13 +29,13 @@ Enrolling is a browser step, by construction: the person pastes a credential int
 
 1. Hand over the page the script printed for the part (Settings → AI accounts). Say: "Choose the provider, give the account a label you will recognise, and paste the credential the page asks for. Nothing on this side sees it."
 2. Wait. Do not run anything while they are on the page.
-3. When they say it is saved, run `node scripts/where-am-i.mjs` and read them the `coding accounts` part. An enrolled and active account, named by its label, is proof. If the part still says none is enrolled, refresh the contract once (`catalyst-skills contract --refresh`) and read it again.
+3. When they say it is saved, run `node scripts/where-am-i.mjs` and read them the `coding accounts` part. An enrolled and active account, named by its label, is proof. If the part still says none is enrolled, refresh the contract once (`catalyst contract --refresh`) and read it again.
 
 Only a workspace owner or admin can enrol one (the page still says "tenant" in places). If the person is neither, say who can, and stop this step there.
 
 ## Naming accounts
 
-Call an account what the page calls it: its label, else its email, else its slot. `catalyst-skills accounts --json` carries this as `displayName`. Never call one "the first account" or "account 2", and never read out a credential.
+Call an account what the page calls it: its label, else its email, else its slot. `catalyst accounts --json` carries this as `displayName`. Never call one "the first account" or "account 2", and never read out a credential.
 
 ## An account that already exists
 

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

@@ -43,4 +43,4 @@ run = ["npm", "ci"]
 
 ## After the merge
 
-`catalyst-skills ready` reports `environment_declared` for the team's default repository and names the next step: commit the file, fix it, or approve it. The `catalyst-setup` check table has each reason. The workspace-wide declaration is separate; `catalyst-skills environment` handles it (also step 8 of `references/the-one-path.md`).
+`catalyst ready` reports `environment_declared` for the team's default repository and names the next step: commit the file, fix it, or approve it. The `catalyst-setup` check table has each reason. The workspace-wide declaration is separate; `catalyst environment` handles it (also step 8 of `references/the-one-path.md`).

package/skills/catalyst-onboard/references/local-sync.md

@@ -2,14 +2,14 @@
 
 **For:** a person who wants an on-machine event file and searchable replica. The normal API-backed skills work without this, so ask before starting a background writer.
 
-**You run:** `node scripts/local-sync.mjs` to show the current local state. Only if the person opts in, run `node scripts/local-sync.mjs --start`. The script uses `catalyst-skills replica start --detach`, whose writer also starts the local event cache. It waits up to 90 seconds; `--wait <seconds>` sets a bounded wait from 0 to 300.
+**You run:** `node scripts/local-sync.mjs` to show the current local state. Only if the person opts in, run `node scripts/local-sync.mjs --start`. The script uses `catalyst replica start --detach`, whose writer also starts the local event cache. It waits up to 90 seconds; `--wait <seconds>` sets a bounded wait from 0 to 300.
 
-**Read back:** `Local sync current` only when both the replica and event cache have live writer heartbeats and each cursor equals its own cloud head. A detached process starting, one fresh heartbeat alone, or replica freshness alone does not prove event freshness. `catalyst-skills replica status --probe --json` checks the replica cursor; `catalyst-skills events status --probe --json` checks the separate event cursor. Either command can report stale or unknown; unknown means the cloud comparison could not be proved, not that the cache is stale. Exit 0 means current, 1 stale, 2 unknown or not connected, and 3 absent. Do not tell the person local data is current unless the combined check says so.
+**Read back:** `Local sync current` only when both the replica and event cache have live writer heartbeats and each cursor equals its own cloud head. A detached process starting, one fresh heartbeat alone, or replica freshness alone does not prove event freshness. `catalyst replica status --probe --json` checks the replica cursor; `catalyst events status --probe --json` checks the separate event cursor. Either command can report stale or unknown; unknown means the cloud comparison could not be proved, not that the cache is stale. Exit 0 means current, 1 stale, 2 unknown or not connected, and 3 absent. Do not tell the person local data is current unless the combined check says so.
 
 **Owner:** you check and, with the person's opt-in, start. The local writer is optional. A reboot recovery service is separate work; if this machine restarts, recheck status before relying on local data.
 
 ## First ticket event
 
-Ask before starting the local writer. Before the person moves a card, run `node scripts/local-sync.mjs --start` after they opt in and wait until it reports current. Then run `catalyst-skills events status --probe --json` and record its `cursor` as `<cursor-before-move>`. Move the card only after this baseline is captured. Once the card is moved, run `catalyst-skills events wait-for --ticket <ticket-identifier> --after <cursor-before-move> --timeout 300` with the identifier `explain` printed. Do not guess an event type. The explicit cursor lets `wait-for` find the event if it reached the local cache before the command began.
+Ask before starting the local writer. Before the person moves a card, run `node scripts/local-sync.mjs --start` after they opt in and wait until it reports current. Then run `catalyst events status --probe --json` and record its `cursor` as `<cursor-before-move>`. Move the card only after this baseline is captured. Once the card is moved, run `catalyst events wait-for --ticket <ticket-identifier> --after <cursor-before-move> --timeout 300` with the identifier `explain` printed. Do not guess an event type. The explicit cursor lets `wait-for` find the event if it reached the local cache before the command began.
 
 Exit 0 prints a matching event after the recorded baseline and proves it reached this machine's cache. Exit 1 means no matching cached event arrived within five minutes; recheck `node scripts/local-sync.mjs` and report stale or unknown evidence without inferring a cloud or webhook failure. Exit 3 means the event cache is absent; ask before starting it. Other errors are unknown. `explain` remains the API-backed source for why a ticket can or cannot run.

package/skills/catalyst-onboard/references/skill-sources.md

@@ -23,7 +23,7 @@ The `npx skills add --all` command replaces existing same-named directories and
 
 ## Is each pack there
 
-`catalyst-skills ready` checks the Cloud pack only. Check `catalyst-onboard/SKILL.md` (Cloud pack) and `research-codebase/SKILL.md` (development pack) in the intended directory. If both are there, have the person type `/catalyst-onboard` (`$catalyst-onboard` in Codex).
+`catalyst ready` checks the Cloud pack only. Check `catalyst-onboard/SKILL.md` (Cloud pack) and `research-codebase/SKILL.md` (development pack) in the intended directory. If both are there, have the person type `/catalyst-onboard` (`$catalyst-onboard` in Codex).
 
 ## Migrate an existing installation
 

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

@@ -18,7 +18,7 @@ Each step states: what it is for, what you ask or run or hand over, **what you r
 
 **For:** giving this machine a credential, so every later read is the person's own. The installer normally did this; you are here only when the script says the machine is not connected.
 
-**You ask:** "Shall I start the login now?" On a yes, run `catalyst-skills login`. It prints a short code and a URL. The person approves it in a browser, from a phone if this machine has none. Do not offer the key form; it exists for a person who already holds a personal key and says so.
+**You ask:** "Shall I start the login now?" On a yes, run `catalyst login`. It prints a short code and a URL. The person approves it in a browser, from a phone if this machine has none. Do not offer the key form; it exists for a person who already holds a personal key and says so.
 
 **Read back:** the `Connected to …` and `Connected as …` lines, then the script again so the machine part flips.
 
@@ -40,7 +40,7 @@ Each step states: what it is for, what you ask or run or hand over, **what you r
 
 **You hand over:** `<their cloud>/settings/connections` (the Integrations page; Settings labels it Connections today), and say: connect Linear. It sends them to Linear to authorise and brings them back.
 
-**Read back:** after they say it is done, re-run the script and read them the `account` line. A resolved workspace is proof. If it still reads unresolved, run `catalyst-skills contract --refresh` and read it again.
+**Read back:** after they say it is done, re-run the script and read them the `account` line. A resolved workspace is proof. If it still reads unresolved, run `catalyst contract --refresh` and read it again.
 
 **Owner:** a workspace owner or admin, in a browser. **Browser by construction**: it is an authorization grant, and no key can perform one.
 
@@ -48,11 +48,13 @@ Each step states: what it is for, what you ask or run or hand over, **what you r
 
 **For:** the project. A project is one Linear team plus the repositories registered to it. Until a project's stages are mapped, a card moved into it does nothing at all; this is the single most common reason a new workspace sees no activity.
 
-**You hand over:** `<their cloud>/settings/linear-teams`. They pick one team and press **Map my stages**, or **Adopt the Catalyst workflow** if they want Catalyst's stages created for them.
+**You run:** `catalyst team list` to see the teams without checking readiness. Have the person choose one team key. Then `catalyst team map <KEY>`, or `catalyst team adopt <KEY>` if they want Catalyst's stages created for them: each prints a preview; show it, and pass `--yes --plan-hash <hash>` only after they approve that exact plan. Run `catalyst team check <KEY>` only for the selected team when you need its verdict. The same steps exist on `<their cloud>/settings/linear-teams` (**Map my stages**, **Adopt the Catalyst workflow**) for a person who prefers the page.
 
-**Read back:** re-run the script and read the `projects` line. A project that now appears with a readiness verdict is proof it was saved. Read them the verdict and any failing checks by name.
+**Read back:** re-run the script and read the `projects` line: the verdict and any failing checks by name. A project that reads `blocked` is not set up whatever its gate says; the script names the blocking checks and their owner. Three of them are Linear's own Git automation rules (in Linear: Settings → Teams → the team → Workflow → Git automation, set the named rule to No action). No Catalyst key can change those, so say so, hand it over, and afterwards run `catalyst team check <KEY>`.
 
-**Owner:** a workspace owner or admin. ⛔ Listing the projects and saving a mapping are settings-page work today; a key cannot do either yet. Say that plainly; it is a gap in the product, not something they did wrong.
+For manual setup, `catalyst team checklist <KEY>` prints the same lines as the browser. If it cannot read the live stages, fix the Linear connection and retry. Moving tickets out of old stages is a separate decision: preview with `team migrate <KEY>`, review source and destination ids and counts, then confirm with `--yes --plan-hash <hash>` from that preview. Retiring emptied source stages requires a later `team migrate <KEY> --retire` preview and a separate approval using its preview hash. `team adopt <KEY> --undo` likewise previews the exact stages previously created by Adopt before asking for confirmation.
+
+**Owner:** a workspace owner or admin, with their own login. You run the commands; the person picks the team and approves each write after seeing its preview. A run that exits 3 stopped before applying anything.
 
 ⭐ **One project at a time is safe, and lead with this.** Mapping one project changes no other project's stages and moves no other project's tickets. Encourage a pilot: the project they care least about breaking.
 
@@ -80,9 +82,9 @@ Each step states: what it is for, what you ask or run or hand over, **what you r
 
 **For:** the person. The integrations serve the whole workspace; a connected account is this person's own Linear or GitHub login, so that what Catalyst does for them is attributed to them, and asks assigned to them can be told apart from everyone else's.
 
-**You run:** `catalyst-skills connections personal linear start`. It prints a short-lived URL and tries to open it; if the browser does not open, hand them the URL. Then `catalyst-skills connections personal linear status`. Do GitHub the same way, with `github`, only after the GitHub App is installed and the repository is registered: `catalyst-skills connections personal github start`, then `status`.
+**You run:** `catalyst connections personal linear start`. It prints a short-lived URL and tries to open it; if the browser does not open, hand them the URL. Then `catalyst connections personal linear status`. Do GitHub the same way, with `github`, only after the GitHub App is installed and the repository is registered: `catalyst connections personal github start`, then `status`.
 
-**Read back:** each `status`, and the script's `person` part: their label and role, whether their Linear identity is matched, and each grant. A URL opening is not proof a grant landed. If Linear identity stays unmatched after consent, `catalyst-skills identity linear status`, then `options`; the person picks their own listed identity and you run `catalyst-skills identity linear set <linearUserId>`. An already-resolved or claimed identity, and an inactive seat, need an owner or admin.
+**Read back:** each `status`, and the script's `person` part: their label and role, whether their Linear identity is matched, and each grant. A URL opening is not proof a grant landed. If Linear identity stays unmatched after consent, `catalyst identity linear status`, then `options`; the person picks their own listed identity and you run `catalyst identity linear set <linearUserId>`. An already-resolved or claimed identity, and an inactive seat, need an owner or admin.
 
 **Owner:** you start and check; the person approves in a browser.
 
@@ -90,7 +92,7 @@ Each step states: what it is for, what you ask or run or hand over, **what you r
 
 **For:** the repository's own settings, in `.catalyst/catalyst.toml` on its default branch: the Linear team it belongs to, the names of the variables and secrets its build needs, and its setup commands. Names leave the machine; values are entered once, by them, in the app.
 
-**You ask:** one thing at a time. First: "Shall I draft it from your repository's own build files?" On a yes, ask where the repository is checked out on this machine; if it is not, write the file here for them to add. Then `references/declaring-a-repository.md`: the inventory, the file's shape, the pull request. Say what happens after the merge as context, not as a second task for now. After the merge, an owner or admin approves the revision on the repository's Environment page (Settings → Repositories → the repository → Environment → Setup declaration → Approve this revision) and enters the values on the same page. A workspace-wide declaration, if they want one, goes through `catalyst-skills environment` (read, propose, `--approve`), the one setup write you can perform.
+**You ask:** one thing at a time. First: "Shall I draft it from your repository's own build files?" On a yes, ask where the repository is checked out on this machine; if it is not, write the file here for them to add. Then `references/declaring-a-repository.md`: the inventory, the file's shape, the pull request. Say what happens after the merge as context, not as a second task for now. After the merge, an owner or admin approves the revision on the repository's Environment page (Settings → Repositories → the repository → Environment → Setup declaration → Approve this revision) and enters the values on the same page. A workspace-wide declaration, if they want one, goes through `catalyst environment` (read, propose, `--approve`), the one setup write you can perform.
 
 **Read back:** the script's `repository declarations` part, read from each project's `environment_declared` check: no file yet, invalid, awaiting approval, or in effect, per repository. Names only, never a value.
 
@@ -100,9 +102,9 @@ Each step states: what it is for, what you ask or run or hand over, **what you r
 
 **For:** the only thing that proves setup worked.
 
-**You run:** `catalyst-skills ready`. Its READY does not cover the coding account or the host; the script does. Read them the verdict and every failing line with its own fix and owner. If it says NOT READY, go to `references/who-fixes-what.md` before you touch anything.
+**You run:** `catalyst team check <KEY>` first when the script's next step names it (an owner or admin whose CLI has the verb), then `catalyst ready`. Its READY does not cover the coding account or the host; the script does. Read them the verdict and every failing line with its own fix and owner. If it says NOT READY, go to `references/who-fixes-what.md` before you touch anything.
 
-**Then:** ask them to move one card into the project's start stage (usually Todo) and tell you which ticket it was. That is the whole question; do not offer to explain the pipeline or to search the backlog instead. Then watch. `catalyst-skills explain <ticket>` says why it is or is not about to run. If they opted into local sync, use the optional first-event check in `references/local-sync.md`.
+**Then:** one question, worded like this: "Move one ticket into ENG's start stage (usually Todo) and tell me its id." Nothing else in that turn: no offer to explain the pipeline, to look at the board, or to pick one for them. Then watch. `catalyst explain <ticket>` says why it is or is not about to run. If they opted into local sync, use the optional first-event check in `references/local-sync.md`.
 
 **Read back:** what `explain` actually said, and the first comment the agent leaves on the ticket. If `explain` says the ticket cannot start, the reason it names is the answer; use the `how-catalyst-works` skill for what it means, then `unstick` if something is holding it.
 

package/skills/catalyst-onboard/references/what-a-phase-needs.md

@@ -6,7 +6,7 @@ A person can finish every other step and still see nothing run. A phase needs tw
 
 **For:** a phase runs on one of the tenant's own enrolled coding accounts. With none active, no phase can start.
 
-**Instrument:** `codingAccounts` in `catalyst-skills contract`. It carries a `state`, a printable `line`, who enrolls an account (`enrolledByLine`) and the `page`. The script prints all of them. It never shows a credential or an email. When the state is `enrolled`, the script also reads `catalyst-skills accounts` to check each account's credential.
+**Instrument:** `codingAccounts` in `catalyst contract`. It carries a `state`, a printable `line`, who enrolls an account (`enrolledByLine`) and the `page`. The script prints all of them. It never shows a credential or an email. When the state is `enrolled`, the script also reads `catalyst accounts` to check each account's credential.
 
 **What each state means:**
 
@@ -19,13 +19,13 @@ A person can finish every other step and still see nothing run. A phase needs tw
 
 **Owner:** the one the contract names. The person does it in the browser. Never ask for the credential, and never handle it. A key cannot enrol one. Which kinds of account exist, what each asks for, and what to do with an ended or cancelled one are in `references/choosing-a-coding-account.md`; it is step 2 of the path, the first thing asked.
 
-**Older cloud:** if the contract has no `codingAccounts`, the script says the cloud is older and reads `catalyst-skills accounts` instead. That list counts the accounts enrolled and the ones able to take work. An expired, revoked or quarantined account does not count. The owner is then a tenant owner or admin, at `<their cloud>/settings/coding-accounts`.
+**Older cloud:** if the contract has no `codingAccounts`, the script says the cloud is older and reads `catalyst accounts` instead. That list counts the accounts enrolled and the ones able to take work. An expired, revoked or quarantined account does not count. The owner is then a tenant owner or admin, at `<their cloud>/settings/coding-accounts`.
 
 ## Host
 
 **For:** the contract carries this as the `hosts_current` readiness check on each project. It reads the same on every project, because it is about the whole account.
 
-**Instrument:** the `hosts_current` check in `catalyst-skills contract --path teams`, and its owner in `catalyst-skills contract --path readinessChecks`.
+**Instrument:** the `hosts_current` check in `catalyst contract --path teams`, and its owner in `catalyst contract --path readinessChecks`.
 
 **What each reading means:**
 
@@ -35,11 +35,11 @@ A person can finish every other step and still see nothing run. A phase needs tw
 | `unknown`, `no_host_connected` | no Catalyst host is connected | name the owner and stop |
 | `unknown`, `hosts_unreported` | a host is connected but has not said which mapping it loaded | name the owner; it clears when the host reconnects |
 | `fail`, `hosts_behind` | a connected host runs an older mapping | name the owner |
-| the part reads `unreadable` | no project has been checked yet | press Re-check on the projects page, then read it again |
+| the part reads `unreadable` | no project has been checked yet | run `catalyst team check <KEY>` when the script names it (it does when the CLI has the verb and the person is an owner or admin); otherwise press Re-check on the projects page; then read it again |
 
 **Owner:** the contract names the owner of `hosts_current`, and where they act in its `fixedWhere`. When `fixedWhere` has a page, the script prints it, and the command too when there is one. When it is null, which it is today, the script prints the owner sentence alone. Then there is no page, so do not invent one. Say who owns it and that they connect it.
 
-⛔ `catalyst-skills ready` treats this check as a note, so it can print READY while no host is connected. READY there is not proof a phase can run. The `host` part is.
+⛔ `catalyst ready` treats this check as a note, so it can print READY while no host is connected. READY there is not proof a phase can run. The `host` part is.
 
 ## Saying it is ready