@catalyst-cloud/catalyst-skills 0.2.0 → 0.3.0

package/dist/execution.js

@@ -4,7 +4,7 @@
 import { flagBool, flagString, positionals } from "./args.js";
 import { normalizeBaseUrl, requireConfig } from "./config.js";
 import { loadContract } from "./contract.js";
-import { UsageError } from "./errors.js";
+import { CliError, UsageError } from "./errors.js";
 import { apiClient } from "./http.js";
 /** Every exclusion reason the eligibility evaluator names, in plain English. */
 export const EXCLUSION_REASONS = {
@@ -101,10 +101,9 @@ export async function cmdExplain(args, ctx) {
     if (!ticket)
         throw new UsageError("explain needs a ticket: explain <ticket>");
     const cfg = requireConfig(ctx);
-    if (flagBool(args, "history")) {
-        ctx.stdout(`${ticket}: per-ticket execution history is not visible to an account key yet — read it at ${normalizeBaseUrl(cfg.baseUrl)}/settings`);
-        return 0;
-    }
+    // `explain --history` is the same read as `history <ticket>`; both go to CTC-1954's route.
+    if (flagBool(args, "history"))
+        return await cmdHistory(args, ctx, ticket);
     const { doc } = await loadContract(ctx, cfg);
     const dash = ticket.indexOf("-");
     if (dash <= 0)
@@ -124,33 +123,186 @@ export async function cmdExplain(args, ctx) {
     }
     return 0;
 }
+/**
+ * `running` — the fleet-wide "what is Catalyst doing right now?".
+ *
+ * ⛔ `/api/v1/lease/attributions` IS NOT A FLEET-WIDE ROUTE. It answers "who wrote this transition,
+ * holding which lease?" for ONE (ticket, phase) pair and 400s `invalid_field` without both — 0.2.0
+ * called it bare on every `running`, so the headline verb (and `whats-running.mjs`, and
+ * `snapshot.mjs`) failed for every tenant. The tenant-wide question is answered by
+ * `/fleet-activity/current` (what is executing) and `/agent-roster/current` (who is coordinating),
+ * neither of which takes coordinates. Lease attributions stay available, behind the coordinates the
+ * route requires.
+ */
 export async function cmdRunning(args, ctx) {
     const cfg = requireConfig(ctx);
+    const ticket = flagString(args, "ticket");
+    const phase = flagString(args, "phase");
+    if ((ticket === undefined) !== (phase === undefined)) {
+        throw new UsageError("running: --ticket and --phase go together — lease attributions are recorded per (ticket, phase), and the route refuses either one alone");
+    }
     const api = apiClient(cfg, ctx);
-    const [activity, roster, leases] = await Promise.all([
+    const [activity, roster] = await Promise.all([
         api.getJson("/api/v1/fleet-activity/current"),
         api.getJson("/api/v1/agent-roster/current"),
-        api.getJson("/api/v1/lease/attributions"),
     ]);
-    const out = { fleetActivity: activity.body, agentRoster: roster.body, leaseAttributions: leases.body };
+    const out = { fleetActivity: activity.body, agentRoster: roster.body };
+    if (ticket !== undefined && phase !== undefined) {
+        const leases = await api.getJson("/api/v1/lease/attributions", { query: { ticket, phase } });
+        out.leaseAttributions = leases.body;
+    }
     if (args.json) {
         ctx.stdout(JSON.stringify(out));
         return 0;
     }
     ctx.stdout(`fleet activity: ${JSON.stringify(out.fleetActivity)}`);
     ctx.stdout(`agent roster: ${JSON.stringify(out.agentRoster)}`);
-    ctx.stdout(`lease attributions: ${JSON.stringify(out.leaseAttributions)}`);
+    if (out.leaseAttributions !== undefined) {
+        ctx.stdout(`lease attributions (${ticket} ${phase}): ${JSON.stringify(out.leaseAttributions)}`);
+    }
     return 0;
 }
+/**
+ * `queue` — the dispatch order. The route is per-team and REQUIRES `?team=` ("bad team", 400), but
+ * a customer asking "what is next?" rarely means one team, so an omitted `--team` reads every team
+ * the tenant contract names rather than sending a call the route will refuse.
+ */
 export async function cmdQueue(args, ctx) {
     const cfg = requireConfig(ctx);
     const api = apiClient(cfg, ctx);
-    const res = await api.getJson("/api/v1/dispatch-queue/current", { query: { team: flagString(args, "team") } });
-    ctx.stdout(args.json ? JSON.stringify(res.body) : JSON.stringify(res.body, null, 2));
+    const named = flagString(args, "team");
+    let teams;
+    if (named !== undefined) {
+        teams = [named];
+    }
+    else {
+        const { doc } = await loadContract(ctx, cfg);
+        teams = doc.teams.map((t) => t.key).filter((k) => typeof k === "string" && k !== "");
+        if (teams.length === 0) {
+            throw new UsageError("queue needs --team: the tenant contract names no team to read a queue for");
+        }
+    }
+    const bodies = await Promise.all(teams.map(async (team) => [team, (await api.getJson("/api/v1/dispatch-queue/current", { query: { team } })).body]));
+    // One team asked for → its envelope, unwrapped, exactly as before. Several → keyed by team, so a
+    // caller can tell whose queue a row belongs to.
+    const out = bodies.length === 1 && named !== undefined ? bodies[0][1] : Object.fromEntries(bodies);
+    ctx.stdout(args.json ? JSON.stringify(out) : JSON.stringify(out, null, 2));
     return 0;
 }
-export function cmdAccounts(ctx) {
+/** The five status words `/api/v1/coding-accounts` reports, in the words a customer reads. */
+export const ACCOUNT_STATUS = {
+    "expired-or-revoked": "expired or revoked — re-enrol it before it can take work",
+    walled: "walled — the provider's usage limit is spent for now",
+    active: "active — observed working",
+    attested: "attested — healthy at last check, no work observed since",
+    unobserved: "unobserved — enrolled, but nothing has been seen from it yet",
+};
+/** One slot as a line a human reads: who it is, what state it is in, and what it is spending on. */
+export function renderAccount(a) {
+    const name = a.label ? `${a.accountSlot ?? "?"} (${a.label})` : (a.accountSlot ?? "?");
+    const harness = a.harness ? `/${a.harness}` : "";
+    const status = a.status ? (ACCOUNT_STATUS[a.status] ?? a.status) : "status unknown";
+    const bits = [`${name}  ${a.provider ?? "?"}${harness}  ${status}`];
+    if (typeof a.bindingUsedPercent === "number") {
+        const resets = typeof a.bindingResetsAtMs === "number" ? `, resets ${new Date(a.bindingResetsAtMs).toISOString()}` : "";
+        bits.push(`usage ${a.bindingUsedPercent}% of the ${a.bindingWindow ?? "binding"} window${resets}`);
+    }
+    if (a.quarantined)
+        bits.push(`quarantined${a.quarantineReason ? `: ${a.quarantineReason}` : ""}`);
+    const holds = a.liveHolds ?? [];
+    if (holds.length > 0)
+        bits.push(`holding ${holds.map((h) => `${h.ticket}/${h.phase}`).join(", ")}`);
+    else if (a.liveHoldsCount)
+        bits.push(`${a.liveHoldsCount} live hold(s)`);
+    return bits.join("  ·  ");
+}
+/**
+ * ⛔ A ROUTE THIS TENANT'S CLOUD DOES NOT SERVE IS SAID OUT LOUD, never rendered as an empty success.
+ * `GET /api/v1/coding-accounts` (CTC-1953) and `GET /api/v1/issues/:id/execution` (CTC-1954) ship
+ * ahead of some tenants' deployed mirror; a 404 there means "your cloud is older than this bundle",
+ * which is a different fact from "you have no coding accounts" and must never print as the latter.
+ */
+function needsNewerCloud(what, cfg) {
+    return new CliError(`${what} needs a newer Catalyst Cloud than ${normalizeBaseUrl(cfg.baseUrl)} is running — the route answered 404. Nothing is wrong with your tenant; ask your operator when the mirror last deployed.`, "route-not-deployed", 3, 404);
+}
+export async function cmdAccounts(args, ctx) {
     const cfg = requireConfig(ctx);
-    ctx.stdout(`coding-account status is not visible to an account key yet — read it at ${normalizeBaseUrl(cfg.baseUrl)}/settings/coding-accounts`);
+    const api = apiClient(cfg, ctx);
+    const res = await api.getJson("/api/v1/coding-accounts", {
+        accept: [404],
+    });
+    if (res.status === 404)
+        throw needsNewerCloud("coding-account status", cfg);
+    const accounts = Array.isArray(res.body) ? res.body : (res.body?.accounts ?? []);
+    if (args.json) {
+        ctx.stdout(JSON.stringify(res.body));
+        return 0;
+    }
+    if (accounts.length === 0) {
+        ctx.stdout(`No coding accounts are enrolled on this tenant — enrol one at ${normalizeBaseUrl(cfg.baseUrl)}/settings/coding-accounts`);
+        return 0;
+    }
+    for (const a of accounts)
+        ctx.stdout(renderAccount(a));
     return 0;
 }
+/**
+ * `history <ticket>` (and `explain --history`) — the ticket's execution history: per-phase attempts
+ * and outcomes, remediate rounds against the cap, the park sentinel and what releases it, the live
+ * lease, the last advance. Reads `GET /api/v1/issues/:identifier/execution` (CTC-1954).
+ */
+export async function cmdHistory(args, ctx, ticketArg) {
+    const ticket = ticketArg ?? positionals(args)[0];
+    if (!ticket)
+        throw new UsageError("history needs a ticket: history <ticket>");
+    const cfg = requireConfig(ctx);
+    const api = apiClient(cfg, ctx);
+    const res = await api.getJson(`/api/v1/issues/${encodeURIComponent(ticket)}/execution`, {
+        accept: [404],
+    });
+    if (res.status === 404)
+        throw needsNewerCloud(`execution history for ${ticket}`, cfg);
+    if (args.json) {
+        ctx.stdout(JSON.stringify(res.body));
+        return 0;
+    }
+    for (const line of renderHistory(ticket, res.body))
+        ctx.stdout(line);
+    return 0;
+}
+/** ⛔ `null` is UNREADABLE, never "nothing happened" — the report's own contract, kept in the prose. */
+export function renderHistory(ticket, doc) {
+    const lines = [];
+    if (doc.hasLadderHistory === false) {
+        lines.push(`${ticket}: no ladder history recorded${doc.note ? ` — ${doc.note}` : ""}.`);
+    }
+    const phases = doc.phases;
+    if (phases === null || phases === undefined) {
+        lines.push(`${ticket}: the per-phase table could not be read (unreadable, not empty).`);
+    }
+    else {
+        lines.push(`${ticket} phases (${doc.attemptHistory ?? "latest-per-phase"}):`);
+        for (const p of phases) {
+            const fail = p.lastFailureClass ? `, last failure ${p.lastFailureClass}${p.consecutiveFailures ? ` ×${p.consecutiveFailures}` : ""}` : "";
+            lines.push(`  ${p.phase}: ${p.status ?? "?"} (attempt ${p.attempt ?? "?"})${fail}`);
+        }
+    }
+    if (doc.failure) {
+        const f = doc.failure;
+        lines.push(`Last failure: ${f.phase} — ${f.failureMode}${f.failureDetail ? ` (${f.failureDetail})` : ""}${f.summary ? `: ${f.summary}` : ""}`);
+    }
+    if (doc.remediate && typeof doc.remediate.roundsDispatched === "number") {
+        lines.push(`Remediate rounds dispatched: ${doc.remediate.roundsDispatched}${typeof doc.remediate.cap === "number" ? ` (cap ${doc.remediate.cap})` : ""}`);
+    }
+    if (doc.park) {
+        lines.push(`Parked at ${doc.park.phase ?? "?"} (${doc.park.sentinel}): ${doc.park.selfReleases ? "releases itself" : "needs an operator"} — ${doc.park.releasedBy}`);
+    }
+    for (const l of doc.lease ?? [])
+        lines.push(`Live lease: ${l.phase} held by ${l.holder ?? "?"} until ${new Date(l.deadlineMs).toISOString()}`);
+    if (doc.lastAdvance) {
+        lines.push(`Last advance: ${doc.lastAdvance.phase} → ${doc.lastAdvance.toSlot ?? "?"} (${doc.lastAdvance.landed ? "landed" : "not landed"})`);
+    }
+    for (const u of doc.unreadable ?? [])
+        lines.push(`Unreadable: ${u.table} (${u.error}) — absent from this report, not absent from the ticket.`);
+    return lines;
+}

package/dist/http.js

@@ -31,6 +31,39 @@ export class ApiClient {
         await this.refuseIfNotOk(res, `GET ${path}`);
         return { status: res.status, body: await this.parseBody(res, `GET ${path}`), headers: res.headers };
     }
+    /**
+     * A GET whose success body is NDJSON — one JSON object per line, the shape `streamNdjson` sends.
+     *
+     * ⛔ `/changes` and `/snapshot` ANSWER NDJSON ON 200 AND JSON ON A REFUSAL, so a caller that only
+     * has `getJson` reads every real success as "returned a non-JSON body" while its refusals parse
+     * perfectly. That asymmetry is why `query changes` looked like it worked: nothing reached a 200.
+     * `accept` behaves as it does on `getJson` — those statuses come back with `rows: []` for the
+     * caller to branch on, and their (JSON) body is deliberately not parsed here.
+     */
+    async getNdjson(path, opts = {}) {
+        const url = this.url(path, opts.query);
+        const res = await this.send(url, {
+            method: "GET",
+            headers: { authorization: `Bearer ${this.cfg.key}`, accept: "application/x-ndjson, application/json" },
+        });
+        if (opts.accept?.includes(res.status))
+            return { status: res.status, body: [], headers: res.headers };
+        await this.refuseIfNotOk(res, `GET ${path}`);
+        const text = await res.text();
+        const rows = [];
+        for (const line of text.split("\n")) {
+            const trimmed = line.trim();
+            if (trimmed === "")
+                continue;
+            try {
+                rows.push(JSON.parse(trimmed));
+            }
+            catch {
+                throw new MeError(`GET ${path} returned a line that is not JSON: ${trimmed.slice(0, 120)}`, "shape");
+            }
+        }
+        return { status: res.status, body: rows, headers: res.headers };
+    }
     async postJson(path, body) {
         const url = this.url(path);
         const res = await this.send(url, {
@@ -75,10 +108,10 @@ export class ApiClient {
             reason = raw.slice(0, 200);
         }
         if (res.status === 401) {
-            throw new CliError(`${what} failed (401): credential not accepted — ask your tenant admin for a valid account key`, "unauthorized", 2, 401);
+            throw new CliError(`${what} failed (401): credential not accepted — mint a personal key at Settings → API keys and log in again`, "unauthorized", 2, 401);
         }
         if (res.status === 403) {
-            throw new CliError(`${what} failed (403): this key may not reach that route${reason ? ` (${reason})` : ""} — a machine-gated route needs an account key (ctc_acct_…), not a workstation key`, "forbidden", 2, 403);
+            throw new CliError(`${what} failed (403): this key may not reach that route${reason ? ` (${reason})` : ""} — a route that acts as a host (claiming work, publishing artifacts) needs the tenant's account key; every read and write a person makes takes your personal key`, "forbidden", 2, 403);
         }
         if (res.status === 429) {
             const retryAfter = res.headers.get("retry-after");
@@ -114,7 +147,7 @@ export async function fetchMe(baseUrl, key, fetchImpl, timeoutMs = REQUEST_TIMEO
             reason = "";
         }
         const detail = res.status === 401
-            ? "credential not accepted — ask your tenant admin for a valid account key"
+            ? "credential not accepted — mint a personal key at Settings → API keys and log in again"
             : reason || `HTTP ${res.status}`;
         throw new MeError(`GET /me failed (${res.status}): ${detail}`, "http", res.status);
     }
@@ -132,11 +165,30 @@ export async function fetchMe(baseUrl, key, fetchImpl, timeoutMs = REQUEST_TIMEO
         (body.principal !== "service" && body.principal !== "session")) {
         throw new MeError("GET /me returned an unexpected shape", "shape");
     }
+    const user = parseMeUser(body.user);
     return {
         account: body.account,
         slug: body.slug,
         name: body.name,
         permissions: body.permissions,
         principal: body.principal,
+        ...(user ? { user } : {}),
     };
 }
+/** The `user` block a personal key gets from /me. Absent (undefined) is "a host key, no person";
+ *  present-but-malformed is a shape error like any other field, never silently dropped. */
+function parseMeUser(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== "object" || raw === null)
+        throw new MeError("GET /me returned an unexpected user shape", "shape");
+    const u = raw;
+    if (typeof u.id !== "string" ||
+        typeof u.label !== "string" ||
+        (u.email !== null && typeof u.email !== "string") ||
+        (u.role !== "owner" && u.role !== "admin" && u.role !== "member") ||
+        (u.linearUserId !== null && typeof u.linearUserId !== "string")) {
+        throw new MeError("GET /me returned an unexpected user shape", "shape");
+    }
+    return { id: u.id, label: u.label, email: u.email, role: u.role, linearUserId: u.linearUserId };
+}

package/dist/prompt.js

@@ -1,4 +1,4 @@
-// prompt.ts — the one interactive read in the CLI: asking for the account key on a terminal without
+// prompt.ts — the one interactive read in the CLI: asking for the personal key on a terminal without
 // echoing it. The streams are parameters so the tests can drive it without a real TTY.
 import { createInterface } from "node:readline";
 /** True when there is a terminal to prompt on. Both ends matter: the question needs somewhere to go. */

package/dist/query.js

@@ -4,7 +4,7 @@
 // them and the read-model package is not a declared dependency of this bundle).
 import { flagInt, flagString, positionals } from "./args.js";
 import { requireConfig, replicaDbPath } from "./config.js";
-import { UsageError } from "./errors.js";
+import { CliError, UsageError } from "./errors.js";
 import { apiClient } from "./http.js";
 import { engineFor, replicaStatus } from "./replica.js";
 import { loadSdk } from "./sdk.js";
@@ -125,14 +125,52 @@ async function fromApi(ctx, cfg, sub, rest, f, args) {
         case "changes": {
             const since = flagString(args, "since");
             if (since === undefined)
-                throw new UsageError("changes needs --since <cursor>");
-            const res = await api.getJson("/api/v1/changes", { query: { since, limit: f.limit } });
-            return res.body;
+                throw new UsageError("changes needs --since <cursor>, or --since head to start from now");
+            return await readChanges(api, since, f.limit);
         }
         default:
             throw new UsageError(`unknown query subcommand: ${sub}`);
     }
 }
+/** CTC-137 stamps the live head seq on EVERY `/changes` response — the 200 stream and both 409s. */
+const HEAD_SEQ_HEADER = "x-catalyst-head-seq";
+/**
+ * `query changes --since <cursor|head>`.
+ *
+ * ⛔ THE CHANGEFEED EVICTS, so a refusal must name a cursor that works. `buildChanges` answers a
+ * `since` below the oldest retained seq with 409 `cursor_underflow`, and one past the head with 409
+ * `cursor_ahead_of_head` — both `{resync: true}`. `--since 0`, the form the docs show, is therefore
+ * a 409 on any tenant whose log has rotated, and 0.2.0 surfaced it as a bare "GET /api/v1/changes
+ * failed (409)" that left the customer with no way to learn a usable cursor. The head is stamped on
+ * the refusal itself, so there is always something actionable to say.
+ */
+async function readChanges(api, since, limit) {
+    const resolved = since === "head" ? String(await headCursor(api)) : since;
+    // ⛔ NDJSON ON 200, JSON ON A REFUSAL — see `getNdjson`. Reading this with `getJson` turned every
+    // real success into "returned a non-JSON body" while every refusal parsed, which is why the verb
+    // looked fine: `--since 0` 409s on a rotated feed, so no 200 was ever reached to fail on.
+    const res = await api.getNdjson("/api/v1/changes", {
+        query: { since: resolved, limit },
+        accept: [409],
+    });
+    const head = res.headers.get(HEAD_SEQ_HEADER);
+    if (res.status !== 409) {
+        return { since: Number(resolved), head: head === null ? null : Number(head), changes: res.body };
+    }
+    const where = head === null ? "" : ` The feed's live cursor is ${head}.`;
+    throw new CliError(`cursor ${resolved} is not usable: it is either past the feed's head or no longer in the change log, which keeps only recent changes.${where} Re-run with \`--since head\` to start from now, or with a cursor the feed still holds.`, "changefeed-resync", 1, 409);
+}
+/** The live head, read off any `/changes` response's own header — a 409 carries it too, which is
+ *  what makes this work on a tenant whose log has rotated past every cursor the caller could guess. */
+async function headCursor(api) {
+    const probe = await api.getNdjson("/api/v1/changes", { query: { since: "0", limit: 1 }, accept: [409] });
+    const raw = probe.headers.get(HEAD_SEQ_HEADER);
+    const head = raw === null ? Number.NaN : Number(raw);
+    if (!Number.isFinite(head)) {
+        throw new CliError(`--since head needs the feed's live cursor, and this cloud did not send one (no ${HEAD_SEQ_HEADER} header). Pass an explicit --since <cursor>.`, "changefeed-head-unknown", 1);
+    }
+    return head;
+}
 function needArg(rest, usage) {
     const v = rest[0];
     if (!v)

package/dist/ready.js

@@ -23,7 +23,7 @@ export async function readyReport(ctx, deps) {
         cfg = loadConfig(ctx.home);
         checks.push(cfg
             ? { id: "config", ok: true, line: `config: joined ${cfg.name} (${cfg.slug}) as ${cfg.principal}` }
-            : { id: "config", ok: false, line: "config: not connected", fix: "CATALYST_CLOUD_TOKEN=<account key> npx @catalyst-cloud/catalyst-skills login", who: "you (the key comes from your tenant admin)" });
+            : { id: "config", ok: false, line: "config: not connected", fix: "CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login", who: "you (mint the key at Settings → API keys)" });
     }
     catch (err) {
         checks.push({ id: "config", ok: false, line: `config: ${err instanceof CliError ? err.message : String(err)}`, fix: "re-run login to rewrite it", who: "you" });
@@ -31,7 +31,7 @@ export async function readyReport(ctx, deps) {
     const cache = readContractCache(ctx.home);
     const range = readManifest().tenantContractRange;
     if (!cache) {
-        checks.push({ id: "contract", ok: false, line: "contract: not cached", fix: "catalyst-skills contract --refresh (needs an account key, not a workstation key)", who: "you" });
+        checks.push({ id: "contract", ok: false, line: "contract: not cached", fix: "catalyst-skills contract --refresh", who: "you" });
     }
     else if (contractVersionInRange(cache.contractVersion, range) !== true) {
         checks.push({ id: "contract", ok: false, line: `contract: version ${cache.contractVersion} is outside this bundle's range ${range}`, fix: "npm update -g @catalyst-cloud/catalyst-skills", who: "you" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/catalyst-skills",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Customer skill bundle for Catalyst Cloud: eight skills named from the executive's seat (whats-happening, what-needs-me, run-this-project, catalyst-setup, catalyst-linear, catalyst-github, how-catalyst-works, connect-me) plus the catalyst-skills CLI that reads through the Catalyst Cloud SDK, writes through the agent proxy, and connects your machine to your tenant with one command.",
   "license": "MIT",
   "type": "module",
@@ -35,7 +35,7 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "tsc -p tsconfig.build.json",
-    "prepack": "tsc -p tsconfig.build.json",
+    "prepare": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "version:sync": "node scripts/sync-plugin-version.mjs"
@@ -47,6 +47,7 @@
     "@types/node": "^26.3.0",
     "@vitest/coverage-v8": "^4.1.11",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^4.1.11",
+    "yaml": "^2.9.0"
   }
 }

package/skills/catalyst-github/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: catalyst-github
-description:
+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:*)
 ---

package/skills/catalyst-github/references/what-a-pr-accumulates.md

@@ -42,7 +42,7 @@ Four labels matter, all named on `merge.prLabels`, all matched exactly (a queue'
 | `handStepsHold` | the cloud, automatically | the PR touches a path the queue configuration excludes (schema or migration paths, typically), so a person has to merge it by hand. |
 | `preview` | a human | "deploy me a preview and hold the merge until I have looked". Removing the label is the approval. |
 
-The mirror does not carry PR labels or reactions, so an account key cannot read which holds a PR carries or whether the reviewer reacted; the scripts say so by name. GitHub's own page, or the tenant's settings, is where those live.
+The mirror does not carry PR labels or reactions, so your key cannot read which holds a PR carries or whether the reviewer reacted; the scripts say so by name. GitHub's own page, or the tenant's settings, is where those live.
 
 ## The queue is optional and opt-out
 

package/skills/catalyst-github/scripts/lib/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // lib/cli.mjs — the one way a skill script reaches the Catalyst Cloud SDK and API: by spawning the
 // catalyst-skills CLI this bundle installed. It reads customer.json to find that CLI and nothing
-// else; it never holds the account key itself. This file is a library — run a sibling script with
+// else; it never holds the key itself. This file is a library — run a sibling script with
 // --help for usage. Identical in every skill of this bundle on purpose (skills install one directory
 // at a time, so nothing shared outside the skill would ever be installed).
 import { spawnSync } from "node:child_process";
@@ -10,7 +10,7 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 export const PACKAGE = "@catalyst-cloud/catalyst-skills";
-export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: CATALYST_CLOUD_TOKEN=<account key> npx ${PACKAGE} login`;
+export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE} login`;
 
 /** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME before HOME. */
 export function configPath() {

package/skills/catalyst-github/scripts/read-pr.mjs

@@ -93,5 +93,5 @@ console.log(`reviews (${reviews.length}):`);
 if (reviews.length === 0) console.log("  none mirrored; a reviewer's clean pass is a reaction, which this read does not carry");
 for (const r of reviews) console.log(`  ${fmt(r.state)}  ${fmt(r.reviewer_name, fmt(r.reviewer_id))}  ${when(r.submitted_at)}`);
 
-console.log("not visible to an account key here: PR labels (holds, queue attestation) and the reviewer's reaction — see references/what-a-pr-accumulates.md");
+console.log("not mirrored here: PR labels (holds, queue attestation) and the reviewer's reaction — see references/what-a-pr-accumulates.md");
 process.exit(0);

package/skills/catalyst-linear/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: catalyst-linear
-description:
+description: >-
   Catalyst's view of Linear on the customer's own tenant. 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 tenant's agent proxy as the app actor, with every route, stage id, label id and marker read from the tenant 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-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 disable-model-invocation: true

package/skills/catalyst-linear/references/reading-a-ticket.md

@@ -34,9 +34,9 @@ The comment shapes in `references/what-a-ticket-accumulates.md` tell you which c
 
 A phase's transcript (the full session log) exists in the cloud per ticket, but this bundle has no verb for it yet. Read the artifact document first; it is the phase's own account of what it did. Reach for the transcript only when the document leaves the question open, and say that the bundle cannot fetch it so the human opens it from the ticket's attachments.
 
-## What an account key cannot read
+## What the ledger adds to the comments
 
-Per-ticket execution history beyond the comments (the attempt ledger, the remediation round count against the cap, park state and what releases it) is not readable with an account key yet; `catalyst-skills explain --history <ticket>` prints that by name and where to read it. Do not reconstruct a round count from comments and present it as the cap's count.
+Per-ticket execution history beyond the comments (the attempt ledger, the remediation round count against the cap, park state and what releases it) is `catalyst-skills explain --history <ticket>`, read from the cloud's own relay ledger. Do not reconstruct a round count from comments and present it as the cap's count; read it.
 
 ## How to cite
 

package/skills/catalyst-linear/references/writing-to-linear.md

@@ -12,7 +12,7 @@ This reference restates the write mechanism. The live values it depends on — t
 | a new ticket | `node scripts/create-ticket.mjs --team <key> --title <text>` |
 | a decision for a human | not here: the `what-needs-me` skill raises an ask with options, a default and what it blocks |
 
-Each script wraps one `catalyst-skills write` verb, which posts to the route the contract names, as the tenant's app actor, with the account key this machine connected with. No script composes a URL, and none needs a Linear credential of its own.
+Each script wraps one `catalyst-skills write` verb, which posts to the route the contract names, as the tenant's app actor, with the personal key this machine connected with — so the write carries the person's identity for attribution, and an ask names them. No script composes a URL, and none needs a Linear credential of its own.
 
 ## App actor versus personal identity
 

package/skills/catalyst-linear/scripts/lib/cli.mjs

@@ -8,7 +8,7 @@ import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 
 export const PACKAGE = "@catalyst-cloud/catalyst-skills";
-export const CONNECT_HINT = `CATALYST_CLOUD_TOKEN=<account key> npx ${PACKAGE} login`;
+export const CONNECT_HINT = `CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE} login`;
 
 /** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME (used by tests) over HOME. */
 export function configPath() {

package/skills/catalyst-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: catalyst-setup
-description:
+description: >-
   Am I set up? Machine readiness (Node, the tenant connection, the cached contract, the CLI path, the skills, the SDK, the optional replica) plus tenant readiness from the contract's ten per-team checks, in one verdict: what passes, what is blocked, what is merely waiting, and who can click what. Use when someone asks "am I set up", "what is missing", "why does nothing happen", "is the replica running", or right after connecting a new machine. Reports; never repairs.
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
@@ -23,10 +23,10 @@ You answer one question with one verdict and one list. The verdict is READY or N
 
 ## Rules
 
-- Report, never repair. No tenant-reachable repair verb exists for an account key yet; the settings page is where a tenant owner or admin fixes a mapping, a connection or a label, and you say which one.
+- Report, never repair. No tenant-reachable repair verb exists for a key yet; the settings page is where a tenant owner or admin fixes a mapping, a connection or a label, and you say which one.
 - End every answer with the verdict and the who-can-click-what list, in that order.
 - A stale or absent replica is a note, never a failure: every skill reads the API meanwhile and says so. Do not tell the person to start it unless they want local SQL or cheaper repeated reads.
-- Not connected (exit 2) means the connect step, not a retry: `CATALYST_CLOUD_TOKEN=<account key> npx @catalyst-cloud/catalyst-skills login`, with the key from their tenant admin. Never guess a tenant; the key is the only selector.
+- Not connected (exit 2) means the connect step, not a retry: `CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login`, with the person's own key from Settings → API keys. Never guess a tenant; the key is the only selector.
 - Waiting is not failing. "No write observed", "no delivery observed" and "no host connected" clear themselves the first time the thing happens; say that instead of raising them.
 - Unknown is not a pass. A check the engine could not run is reported as such, never rounded up.
 - Never run a check in a loop. If the person wants to know when a waiting check clears, that is the project-running skill's watch.

package/skills/catalyst-setup/references/what-each-check-means.md

@@ -4,9 +4,9 @@ This page restates invariants: the ten per-team readiness checks the cloud runs,
 
 ## How a team's readiness is scored
 
-A team's status is one of `ready`, `degraded`, `blocked` or `unchecked`. The engine always reports all ten checks; a check it could not run is `unknown`, never `pass`. Any failing check the contract marks as blocking makes the team blocked; any unknown, and any failing check marked degrading, makes it degraded. Unchecked means no readiness pass has run for that team yet, which is a note, not a failure. Readiness is stamped with the account-wide mapping revision it was computed against, so a stale verdict is visible as such.
+A team's status is one of `ready`, `degraded`, `blocked` or `unchecked`. The engine always reports all eleven checks; a check it could not run is `unknown`, never `pass`. Any failing check the contract marks as blocking makes the team blocked; any unknown, and any failing check marked degrading, makes it degraded. Unchecked means no readiness pass has run for that team yet, which is a note, not a failure. Readiness is stamped with the account-wide mapping revision it was computed against, so a stale verdict is visible as such.
 
-## The ten checks
+## The eleven checks
 
 | check id | proves | when it fails, the fix | who clicks |
 | -- | -- | -- | -- |
@@ -20,6 +20,7 @@ A team's status is one of `ready`, `degraded`, `blocked` or `unchecked`. The eng
 | `writes_land` | Catalyst has written to this team successfully | "no write observed" is waiting, not failing: it clears the first time Catalyst moves a ticket. "Write refused" means Linear rejected the last write: check the connection and the team's permissions | owner or admin when refused; otherwise nobody |
 | `webhook_covers_team` | events for this team are arriving | confirmed once a repository is registered and events flow; "no delivery observed" is waiting | owner or admin, by registering the repository |
 | `hosts_current` | no connected host runs an older mapping revision | a host that is behind re-loads the mapping on its next connect; a host that did not report its revision is flagged rather than assumed current; "no host connected" is waiting | whoever runs that host |
+| `environment_declared` | a committed environment declaration for the team's default repository is in effect (`.catalyst/environment.json` was ingested, is valid, and its latest proposal is approved) | `no_team_repo_default`: register a repository and make it the team's default; `no_environment_declaration`: commit the declaration file to that repository; `declaration_invalid` / `declaration_read_failed`: fix the file (the ingest names the error); `declaration_awaiting_approval`: an owner or admin approves the proposal in Settings → Environment |
 
 Three checks are informational by design (labels, event delivery, host currency): they degrade a team but never block it. Which are which is served on `readinessChecks[].severity`; do not memorise the split.
 
@@ -36,8 +37,8 @@ Three checks are informational by design (labels, event delivery, host currency)
 | id | proves | fix |
 | -- | -- | -- |
 | `node` | Node 22 or newer, which the SDK's built-in SQLite engine needs | install Node 22+ |
-| `config` | this machine is connected: `customer.json` exists and loads | `CATALYST_CLOUD_TOKEN=<account key> npx @catalyst-cloud/catalyst-skills login`; the key comes from the tenant admin |
-| `contract` | the tenant contract is cached and its major version is one this bundle accepts | `catalyst-skills contract --refresh`; a version outside the range means update the bundle. A refresh needs an account key, not a workstation key |
+| `config` | this machine is connected: `customer.json` exists and loads | `CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login`; the person mints the key at Settings → API keys |
+| `contract` | the tenant contract is cached and its major version is one this bundle accepts | `catalyst-skills contract --refresh`; a version outside the range means update the bundle. A 403 naming an older cloud means the cloud has not yet deployed personal-key access |
 | `cliPath` | the CLI path recorded at login still exists, so skill scripts can spawn it | re-run login |
 | `skills` | every skill of this bundle is present where the CLI installed them | `catalyst-skills install` |
 | `sdk` | the SDK loads, so the replica and the watch are available | run under Node 22.15 or newer; every read still works through the API meanwhile |
@@ -58,4 +59,4 @@ Three checks are informational by design (labels, event delivery, host currency)
 
 ## Who can click what
 
-The last block `check.mjs` prints groups every failure by the person it needs. Machine fixes name "you", the person at the keyboard. Tenant fixes name the owner or admin roles the contract lists (as Linear user ids, since that is how the cloud knows them), because the settings page that repairs a mapping, a connection or a label is theirs. A check the contract marks as not needing an answer names nobody: it is informational or self-clearing. This skill reports; it never repairs, because no tenant-reachable repair verb exists for an account key yet.
+The last block `check.mjs` prints groups every failure by the person it needs. Machine fixes name "you", the person at the keyboard. Tenant fixes name the owner or admin roles the contract lists (as Linear user ids, since that is how the cloud knows them), because the settings page that repairs a mapping, a connection or a label is theirs. A check the contract marks as not needing an answer names nobody: it is informational or self-clearing. This skill reports; it never repairs, because no key-reachable repair verb exists yet.

package/skills/catalyst-setup/scripts/lib/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // lib/cli.mjs — the one way a skill script reaches the Catalyst Cloud SDK and API: by spawning the
 // catalyst-skills CLI this bundle installed. It reads customer.json to find that CLI and nothing
-// else; it never holds the account key itself. This file is a library — run a sibling script with
+// else; it never holds the key itself. This file is a library — run a sibling script with
 // --help for usage. Identical in every skill of this bundle on purpose (skills install one directory
 // at a time, so nothing shared outside the skill would ever be installed).
 import { spawnSync } from "node:child_process";
@@ -10,7 +10,7 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 export const PACKAGE = "@catalyst-cloud/catalyst-skills";
-export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: CATALYST_CLOUD_TOKEN=<account key> npx ${PACKAGE} login`;
+export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE} login`;
 
 /** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME before HOME. */
 export function configPath() {

package/skills/catalyst-setup/scripts/replica-status.mjs

@@ -14,7 +14,7 @@ const HELP = `Usage: node scripts/replica-status.mjs [--probe] [--json]
 Exit codes, passed through from catalyst-skills replica status:
   0  fresh: a live writer, a young heartbeat, a cursor — skills read the replica
   1  stale: the file exists but the writer is gone or behind — skills read the API and say so
-  2  not connected to a tenant — run: CATALYST_CLOUD_TOKEN=<account key> npx @catalyst-cloud/catalyst-skills login
+  2  not connected to a tenant — run: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login
   3  absent: no replica file — optional; start one with: catalyst-skills replica start --detach`;
 
 const args = process.argv.slice(2);