@catalyst-cloud/cli 0.13.0 → 0.14.0

package/dist/skill-shape.js

@@ -85,7 +85,7 @@ export function validateSkillDir(dir) {
     if (lines.length > MAX_SKILL_LINES)
         problems.push(`${name}: SKILL.md is ${lines.length} lines (max ${MAX_SKILL_LINES})`);
     const fm = parseFrontmatter(lines);
-    let mutatingFrontmatter = false;
+    let manualOnlyFrontmatter = false;
     if (!fm)
         problems.push(`${name}: SKILL.md must start with YAML frontmatter (---)`);
     else {
@@ -99,7 +99,7 @@ export function validateSkillDir(dir) {
             problems.push(`${name}: frontmatter is missing "description"`);
         else if (fm.fields.description.length > MAX_DESCRIPTION_CHARS)
             problems.push(`${name}: description is ${fm.fields.description.length} characters (max ${MAX_DESCRIPTION_CHARS})`);
-        mutatingFrontmatter = fm.fields["disable-model-invocation"] === "true";
+        manualOnlyFrontmatter = fm.fields["disable-model-invocation"] === "true";
         if (fm.closeIndex !== -1) {
             const after = lines[fm.closeIndex + 1] ?? "";
             if (!(after.startsWith("<!--") && after.includes(PROVENANCE_MARKER))) {
@@ -142,10 +142,14 @@ export function validateSkillDir(dir) {
             }
         }
     }
+    // Invocation is one choice written in three places: SKILL.md's `disable-model-invocation`, the
+    // OpenAI sidecar's `allow_implicit_invocation`, and portability's `invocation`. They must agree.
+    // Whether a skill writes (`mutating`) is a separate fact: a skill that writes can still be picked
+    // by the model, and its own scoped controls (a write budget, a preview) govern the write.
     const portability = join(dir, "agents", "portability.yaml");
     const openai = join(dir, "agents", "openai.yaml");
-    let mutating = false;
-    let implicitFalse = false;
+    let explicitPortability = null;
+    let implicitFalse = null;
     if (!existsSync(portability))
         problems.push(`${name}: agents/portability.yaml is missing`);
     else {
@@ -154,7 +158,14 @@ export function validateSkillDir(dir) {
             problems.push(`${name}: agents/portability.yaml does not declare "effects"`);
         if (!/^exposure:\s*\[\s*"?catalog"?\s*\]\s*$/m.test(y))
             problems.push(`${name}: agents/portability.yaml must declare exposure: [catalog]`);
-        mutating = /^mutating:\s*true\s*$/m.test(y);
+        const mutating = /^mutating:\s*true\s*$/m.test(y);
+        const effectsEmpty = /^effects:\s*\[\s*\]\s*$/m.test(y);
+        if (mutating && effectsEmpty)
+            problems.push(`${name}: agents/portability.yaml says mutating: true but lists no effects`);
+        if (!mutating && /^effects:\s*\[\s*[^\]\s]/m.test(y))
+            problems.push(`${name}: agents/portability.yaml lists effects but lacks mutating: true`);
+        const inv = /^invocation:\s*(\w+)\s*$/m.exec(y)?.[1];
+        explicitPortability = inv === undefined ? null : inv === "explicit";
     }
     if (!existsSync(openai))
         problems.push(`${name}: agents/openai.yaml is missing`);
@@ -164,15 +175,12 @@ export function validateSkillDir(dir) {
             problems.push(`${name}: agents/openai.yaml has no "policy:" block`);
         if (!/allow_implicit_invocation:\s*(true|false)/.test(y))
             problems.push(`${name}: agents/openai.yaml does not set policy.allow_implicit_invocation`);
-        implicitFalse = /allow_implicit_invocation:\s*false/.test(y);
+        else
+            implicitFalse = /allow_implicit_invocation:\s*false/.test(y);
     }
-    if (mutating || mutatingFrontmatter || implicitFalse) {
-        if (!mutating)
-            problems.push(`${name}: disable-model-invocation / allow_implicit_invocation: false are set but agents/portability.yaml lacks mutating: true`);
-        if (!mutatingFrontmatter)
-            problems.push(`${name}: is mutating but SKILL.md does not set disable-model-invocation: true`);
-        if (!implicitFalse)
-            problems.push(`${name}: is mutating but agents/openai.yaml does not set policy.allow_implicit_invocation: false`);
+    const manualFlags = [manualOnlyFrontmatter, implicitFalse, explicitPortability].filter((v) => v !== null);
+    if (new Set(manualFlags).size > 1) {
+        problems.push(`${name}: the invocation fields disagree about whether the model may pick this skill (SKILL.md disable-model-invocation: ${manualOnlyFrontmatter}, agents/openai.yaml allow_implicit_invocation: ${implicitFalse === null ? "unset" : !implicitFalse}, agents/portability.yaml invocation: ${explicitPortability === null ? "unset" : explicitPortability ? "explicit" : "implicit"})`);
     }
     for (const p of walk(dir)) {
         const rel = relative(dir, p);

package/dist/skills.js

@@ -1,9 +1,9 @@
 // skills.ts — copying the bundled skills into the user's skills directory, and the one-line update
 // notice a new version prints on its next session.
-import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { defaultSkillsDirFor, upgradeCommand } from "./config.js";
+import { defaultSkillsDirFor, readManifest, upgradeCommand } from "./config.js";
 import { semverOlder } from "./semver.js";
 import { PROVENANCE_MARKER, parseFrontmatter, parseProvenanceVersion } from "./skill-shape.js";
 export function skillsSourceDir() {
@@ -16,9 +16,14 @@ export function skillsSourceDir() {
  * `onlyExisting` is the update path: it refreshes copies this package already made and creates
  * none. That is what keeps the update notice from planting a second copy of every skill beside a
  * set the customer's agent installed as a plugin.
+ *
+ * Both paths then remove a retired skill: a folder in the target that carries this bundle's
+ * provenance stamp but whose name this bundle no longer ships. Left in place, it keeps routing
+ * requests to a skill that was merged away. A folder without the stamp (a person's own skill), a
+ * symlink, and a folder stamped by a NEWER bundle than this one are never removed.
  */
-export function installSkills(targetDir, opts, sourceDir = skillsSourceDir()) {
-    const result = { installed: [], skipped: [] };
+export function installSkills(targetDir, opts, sourceDir = skillsSourceDir(), bundleVersion = readManifest().version) {
+    const result = { installed: [], skipped: [], removed: [] };
     if (existsSync(targetDir) && !statSync(targetDir).isDirectory()) {
         throw new Error(`${targetDir} is not a directory`);
     }
@@ -49,8 +54,43 @@ export function installSkills(targetDir, opts, sourceDir = skillsSourceDir()) {
         cpSync(src, dst, { recursive: true });
         result.installed.push(name);
     }
+    result.removed = removeRetiredSkills(targetDir, new Set(names.filter((n) => existsSync(join(sourceDir, n, "SKILL.md")))), bundleVersion);
     return result;
 }
+/** Remove every stamped folder in `targetDir` whose name `shipped` no longer carries. */
+function removeRetiredSkills(targetDir, shipped, bundleVersion) {
+    if (!existsSync(targetDir))
+        return [];
+    const removed = [];
+    for (const e of readdirSync(targetDir, { withFileTypes: true })) {
+        if (shipped.has(e.name))
+            continue;
+        const dir = join(targetDir, e.name);
+        // lstat, not the dirent alone: a symlink belongs to whoever linked it and is never followed.
+        if (isSymlink(dir) || !e.isDirectory())
+            continue;
+        const skillMd = join(dir, "SKILL.md");
+        if (!existsSync(skillMd))
+            continue;
+        let text;
+        try {
+            text = readFileSync(skillMd, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const line = provenanceLine(text);
+        if (line === undefined)
+            continue;
+        const stamp = parseProvenanceVersion(line);
+        // A newer bundle may ship a skill this one does not know yet; an older CLI must not delete it.
+        if (stamp !== null && semverOlder(bundleVersion, stamp))
+            continue;
+        rmSync(dir, { recursive: true, force: true });
+        removed.push(e.name);
+    }
+    return removed.sort();
+}
 function isSymlink(path) {
     try {
         return lstatSync(path).isSymbolicLink();

package/dist/transport.js

@@ -32,7 +32,16 @@ export class ApiClient {
         const url = this.url(path, opts.query);
         const res = await this.send(url, { method: "GET", headers });
         if (opts.accept?.includes(res.status)) {
-            return { status: res.status, body: undefined, headers: res.headers };
+            let body = undefined;
+            if (opts.parseAccepted) {
+                try {
+                    body = (await res.json());
+                }
+                catch {
+                    body = undefined;
+                }
+            }
+            return { status: res.status, body, headers: res.headers };
         }
         await this.refuseIfNotOk(res, `GET ${path}`);
         return { status: res.status, body: await this.parseBody(res, `GET ${path}`), headers: res.headers };
@@ -87,6 +96,22 @@ export class ApiClient {
             await this.refuseIfNotOk(res, `POST ${path}`);
         return { status: res.status, body: await this.parseBody(res, `POST ${path}`), headers: res.headers };
     }
+    /** PUT a JSON body. Same contract as {@link postJson}: `accept` lists statuses returned as replies. */
+    async putJson(path, body, opts = {}) {
+        const url = this.url(path);
+        const res = await this.send(url, {
+            method: "PUT",
+            headers: {
+                authorization: `Bearer ${await this.credential()}`,
+                accept: "application/json",
+                "content-type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+        if (!opts.accept?.includes(res.status))
+            await this.refuseIfNotOk(res, `PUT ${path}`);
+        return { status: res.status, body: await this.parseBody(res, `PUT ${path}`), headers: res.headers };
+    }
     async send(url, init) {
         try {
             return await this.fetchImpl(url, { ...init, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });

package/dist/var.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.13.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.",
+  "version": "0.14.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 cloud account with one command. The skills directory is the roster; this line never counts it.",
   "license": "MIT",
   "type": "module",
   "publishConfig": {
@@ -45,10 +45,12 @@
     "skill-lib:sync": "node scripts/sync-skill-lib.mjs",
     "skills:scan": "node scripts/scan-skills.mjs",
     "evals": "node scripts/run-evals.mjs",
-    "paths:check": "node scripts/vendor-paths.mjs --check"
+    "paths:check": "node scripts/vendor-paths.mjs --check",
+    "prose:check": "node scripts/check-public-prose.mjs"
   },
   "dependencies": {
-    "@catalyst-cloud/sdk": "^0.13.0",
+    "@catalyst-cloud/sdk": "^0.13.1",
+    "smol-toml": "^1.7.1",
     "yaml": "^2.9.0"
   },
   "devDependencies": {

package/skills/catalyst-github/SKILL.md

@@ -2,20 +2,20 @@
 name: catalyst-github
 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:*)
+allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.0 — written in this repository for customer accounts -->
 
 # Catalyst's GitHub
 
-You answer for the pull requests Catalyst opens and moves. The person asking wants to see one PR, know what is red, and know whether it will merge. Everything tenant-specific (the reviewer's login, the merge policy per repository, the four PR label names, the required checks) comes from the contract at run time and is printed by the scripts; you never restate it from memory.
+You answer for the pull requests Catalyst opens and moves. The person asking wants to see one PR, know what is red, and know whether it will merge. Everything account-specific (the reviewer's login, the merge policy per repository, the four PR label names, the required checks) comes from the contract at run time and is printed by the scripts; you never restate it from memory.
 
 ## Run first
 
-- `node scripts/read-pr.mjs --help` — a ticket's PR (or a PR by node id): state, branch, head, linked ticket, GitHub's mergeable state, every check, status and review. `--all` lists every PR for a ticket.
-- `node scripts/is-it-mergeable.mjs --help` — the three legs (checks, reviewer signal, unresolved threads) judged under the repository's policy, plus the prerequisites; exit 1 when a leg is red.
+- `node scripts/read-pr.mjs --help`: a ticket's PR (or a PR by node id): state, branch, head, linked ticket, GitHub's mergeable state, every check, status and review. `--all` lists every PR for a ticket.
+- `node scripts/is-it-mergeable.mjs --help`: the three legs (checks, reviewer signal, unresolved threads) judged under the repository's policy, plus the prerequisites; exit 1 when a leg is red.
 
-Both read through `catalyst-skills query`, `contract` and, when fresh, `replica`; the first stderr line names the source, and your answer repeats it.
+Both read through `catalyst query`, `contract` and, when fresh, `replica`; the first stderr line names the source, and your answer repeats it.
 
 ## Load on demand
 
@@ -26,7 +26,7 @@ Both read through `catalyst-skills query`, `contract` and, when fresh, `replica`
 
 ## Rules
 
-- Never compose a URL or call the API yourself. Every read is a `catalyst-skills` verb behind a script; run the script, do not read it.
+- Never compose a URL or call the API yourself. Every read is a `catalyst` verb behind a script; run the script, do not read it.
 - A queue-ready label is the cloud's attestation, never a lever you apply; "merged by the queue" is the terminal signal.
 - Hold labels are the human's lever. Describe them; do not apply or remove them.
 - Say what a key cannot see by name (PR labels, the reviewer's reaction, the queue's own state); never guess it.

package/skills/catalyst-github/references/is-it-mergeable.md

@@ -1,6 +1,6 @@
 # Is it mergeable?
 
-The rule is invariant; the policy that applies to a repository is not. The policy names, the default, each repository's resolved policy and its source (repository setting, tenant setting, or the default), the reviewer login and the required check names all come from the contract's `merge` block at run time. `node scripts/is-it-mergeable.mjs <ticket>` reads them and prints one line per leg; the text below explains what those lines mean.
+The rule is invariant; the policy that applies to a repository is not. The policy names, the default, each repository's resolved policy and its source (repository setting, account setting, or the default), the reviewer login and the required check names all come from the contract's `merge` block at run time. `node scripts/is-it-mergeable.mjs <ticket>` reads them and prints one line per leg; the text below explains what those lines mean.
 
 ## Prerequisites before any leg counts
 
@@ -28,7 +28,13 @@ Three policy names are served on `merge.policies`; the default is `merge.default
 | the strict variant | a clean pass at the current head, always. Findings on an earlier head keep blocking until the reviewer looks again. |
 | checks and threads only | the reviewer requirement is dropped entirely; the two unconditional legs decide. |
 
-A clean pass is a reaction: a thumbs-up from the reviewer login posted at or after the head commit's own timestamp. The comment-shaped clean pass ("no major issues" in place of threads) is honoured only if `cleanPassShapes[]` says so for that kind; the script does not judge it either way.
+A clean pass is one of three signals from the reviewer login, most reliable first:
+
+1. **A GitHub review on the exact head commit.** A review names the commit it was submitted against, so it cannot be mistaken for an earlier head.
+2. **A 👍 reaction**, which counts only if it was given after the current head commit was made. The reaction carries no commit, so the cloud compares its time with the head commit's date, and that date is set by whoever made the commit. A push of a commit made before the 👍 (a force-push back to an older commit, a commit prepared earlier) can read as covered. A normal rebase or amend stamps a fresh date, so the everyday path works.
+3. **A clean-pass comment** ("no major issues" in place of threads), honoured only if `cleanPassShapes[]` says so for that kind, with the same timing rule as the 👍.
+
+A new push needs a fresh signal at the new head. The script judges none of these three itself.
 
 ## What the script can and cannot see
 

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

@@ -1,6 +1,6 @@
 # What a pull request accumulates as Catalyst moves a ticket
 
-Most of this page restates invariants: how Catalyst names branches, opens and rewrites pull requests, and what it pushes when. The parts that vary per tenant are read live from the contract's `merge` block and never restated here: the reviewer's login (`merge.reviewerLogin`), which clean-pass shapes are honoured (`merge.cleanPassShapes[]`), the four PR label names (`merge.prLabels`), the checks the cloud waits on (`merge.cloudRemediateRequiredChecks`, on a 1.x contract only), and the policy per repository (`merge.repositories[]`, else `merge.defaultPolicy`). `catalyst-skills contract --path merge` prints them.
+How Catalyst names branches, opens and rewrites pull requests, and what it pushes when, is the same for every account. The parts that vary are read live from the contract's `merge` block and never restated here: the reviewer's login (`merge.reviewerLogin`), which clean-pass shapes are honoured (`merge.cleanPassShapes[]`), the four PR label names (`merge.prLabels`), the checks the cloud waits on (`merge.cloudRemediateRequiredChecks`, on a 1.x contract only), and the policy per repository (`merge.repositories[]`, else `merge.defaultPolicy`). `catalyst contract --path merge` prints them.
 
 ## The branch
 
@@ -29,7 +29,7 @@ Three phases rewrite history on the ticket branch: implement pushes fresh with f
 
 ## The reviewer signal
 
-An automated reviewer (login from the contract) reviews every PR. Its signal is one of four: clean, findings at the current head, findings at an earlier head, no review. A clean pass is a reaction, not a review object: a thumbs-up from the reviewer posted at or after the head commit's own timestamp. A second shape, a terse "no major issues" comment in place of review threads, exists as a documented convention; whether it is honoured is served on `cleanPassShapes[].honoured` and must be read there, never assumed. What counts under each policy is on `references/is-it-mergeable.md`.
+An automated reviewer (login from the contract) reviews every PR. Its signal is one of four: clean, findings at the current head, findings at an earlier head, no review. A clean pass is usually a 👍 reaction from the reviewer, which counts only if it was given after the current head commit was made; a GitHub review on that exact commit is the most reliable signal. A terse "no major issues" comment in place of review threads is a documented convention; whether it is honoured is served on `cleanPassShapes[].honoured` and must be read there, never assumed. What counts under each policy is on `references/is-it-mergeable.md`.
 
 ## Labels on the PR
 
@@ -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 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 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 account's settings, is where those live.
 
 ## The queue is optional and opt-out
 

package/skills/catalyst-github/scripts/is-it-mergeable.mjs

@@ -2,7 +2,7 @@
 // is-it-mergeable.mjs — the three legs of merge evidence for one PR (checks, reviewer signal,
 // unresolved threads) judged under the policy the tenant contract resolves for its repository, plus
 // the prerequisites a queue applies before any leg counts (open, not a draft, no conflict). Every
-// input comes from `catalyst-skills query`, `contract` and, when fresh, `replica sql`.
+// input comes from `catalyst query`, `contract` and, when fresh, `replica sql`.
 // Exit 0 no leg is red, 1 a leg or prerequisite is red, 2 this machine is not connected.
 import { parseJson, runCli, runCliOrExit } from "./lib/cli.mjs";
 import { resolvePull, truthy } from "./lib/pull.mjs";
@@ -34,7 +34,7 @@ if (!target) {
 const { ticket, detail } = resolvePull(target);
 const merge = parseJson(runCliOrExit(["contract", "--path", "merge", "--json"]).stdout);
 if (!merge || !Array.isArray(merge.policies)) {
-  console.error("the contract's merge block did not parse; run: catalyst-skills contract --refresh");
+  console.error("the contract's merge block did not parse; run: catalyst contract --refresh");
   process.exit(1);
 }
 
@@ -103,7 +103,7 @@ if (replica && replica.verdict === "fresh") {
   else if (unknown > 0) add("threads", "inconclusive", `${unknown} thread(s) with no resolved flag mirrored`);
   else add("threads", "pass", `${count(1)} thread(s), all resolved (ancestry against force-pushes is judged by the cloud, not here)`);
 } else {
-  add("threads", "inconclusive", `the PR detail carries no thread count and the replica is ${replica?.verdict ?? "unavailable"}; start it (catalyst-skills replica start --detach) for a local read`);
+  add("threads", "inconclusive", `the PR detail carries no thread count and the replica is ${replica?.verdict ?? "unavailable"}; start it (catalyst replica start --detach) for a local read`);
 }
 
 const failed = legs.filter((l) => l.state === "fail");

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

@@ -1,6 +1,6 @@
 #!/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
+// catalyst CLI this bundle installed. It reads customer.json to find that CLI and nothing
 // 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).
@@ -10,7 +10,9 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
-export const PACKAGE = "@catalyst-cloud/catalyst-skills";
+export const PACKAGE = "@catalyst-cloud/cli";
+/** The package ships two commands, so npx needs the one to run named: `npx -p <package> catalyst`. */
+export const NPX_ARGS = ["-p", PACKAGE, "catalyst"];
 export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: ${CONNECT_COMMAND}`;
 
 /** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME before HOME. */
@@ -41,15 +43,15 @@ export function requireCustomerConfig() {
 }
 
 /**
- * Run one catalyst-skills verb and return {code, stdout, stderr}. Spawns the CLI whose path the
- * connect step recorded in customer.json; falls back to `npx @catalyst-cloud/catalyst-skills` when
+ * Run one catalyst verb and return {code, stdout, stderr}. Spawns the CLI whose path the
+ * connect step recorded in customer.json; falls back to `npx -p @catalyst-cloud/cli catalyst` when
  * no path is recorded or it no longer exists. Exits 2 when the machine is not connected.
  */
 export function runCli(args, opts = {}) {
   const cfg = requireCustomerConfig();
   const recorded = typeof cfg.cliPath === "string" && existsSync(cfg.cliPath);
   const command = recorded ? process.execPath : process.platform === "win32" ? "npx.cmd" : "npx";
-  const argv = recorded ? [cfg.cliPath, ...args] : [PACKAGE, ...args];
+  const argv = recorded ? [cfg.cliPath, ...args] : [...NPX_ARGS, ...args];
   const res = spawnSync(command, argv, {
     encoding: "utf8",
     input: opts.stdin,
@@ -58,7 +60,7 @@ export function runCli(args, opts = {}) {
     shell: !recorded && process.platform === "win32",
   });
   if (res.error) {
-    console.error(`could not run ${recorded ? cfg.cliPath : `npx ${PACKAGE}`}: ${res.error.message}`);
+    console.error(`could not run ${recorded ? cfg.cliPath : `npx -p ${PACKAGE} catalyst`}: ${res.error.message}`);
     process.exit(2);
   }
   return { code: res.status ?? 1, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
@@ -72,7 +74,7 @@ export function runCli(args, opts = {}) {
 export function runCliOrExit(args, opts = {}) {
   const res = runCli(args, opts);
   if (res.code === 0) return res;
-  const why = res.stderr.trim() || res.stdout.trim() || `catalyst-skills ${args.join(" ")} exited ${res.code}`;
+  const why = res.stderr.trim() || res.stdout.trim() || `catalyst ${args.join(" ")} exited ${res.code}`;
   console.error(why);
   process.exit(res.code === 2 ? 2 : 1);
 }

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

@@ -6,12 +6,12 @@
 //
 // customer.json carries exactly one credential: a personal key (`key`), or the keyless login's
 // session (`auth`, the recommended rail). A script never reads either for its value: it spawns the
-// catalyst-skills CLI, which authenticates with whichever is present and refreshes a login's token
+// catalyst CLI, which authenticates with whichever is present and refreshes a login's token
 // itself. A new credential kind lands here, once.
 
 /** The command that connects this machine, as every not-connected line names it. */
 export const CONNECT_COMMAND =
-  "npx @catalyst-cloud/catalyst-skills login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login)";
+  "npx -p @catalyst-cloud/cli catalyst login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx -p @catalyst-cloud/cli catalyst login)";
 
 /** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
 export function hasCredential(cfg) {

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

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 // read-pr.mjs — one ticket's pull request (or one PR by node id) as the mirror holds it: state,
 // branch, head, base, linked ticket and its stage, GitHub's own mergeable verdict, every check,
-// review and commit status. Reads through `catalyst-skills query`; composes no URL.
+// review and commit status. Reads through `catalyst query`; composes no URL.
 import { linkedPulls, resolvePull, truthy } from "./lib/pull.mjs";
 
 const HELP = `Usage: node scripts/read-pr.mjs <ticket | pr-node-id> [--all] [--json]
 
   <ticket>       a ticket identifier such as ABC-123: its open PR is shown (else the merged one, else the newest)
-  <pr-node-id>   a GitHub pull-request node id, as printed by "catalyst-skills query pulls"
+  <pr-node-id>   a GitHub pull-request node id, as printed by "catalyst query pulls"
   --all          for a ticket: list every PR that names it instead of one detail
   --json         print the raw detail document instead of the summary
 

package/skills/catalyst-linear/SKILL.md

@@ -1,26 +1,25 @@
 ---
 name: catalyst-linear
 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
+  Catalyst's view of Linear on the customer's own cloud account. Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the local replica when it is fresh and the origin-fresh API otherwise, always naming the source; searches tickets, PRs, projects and initiatives; writes comments, card moves, labels and new tickets through the account's agent proxy as the app actor, with every route, stage id, label id and marker read from the account's contract. Knows what a ticket accumulates as Catalyst works it (phase-outcome comments, the document per phase, the agent session, the labels, the single blocks relation, the bookkeeping marker, the eyes acknowledgement). Use when a person says "show me the ticket", "what did Catalyst write on it", "comment on it", "move it", "label it" or "file a ticket". Not for raising a decision for a human (what-needs-me) and not for pull requests (catalyst-github).
+allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.0 — written in this repository for customer accounts -->
 
 # Catalyst Linear
 
-You read tickets and write to them on the customer's tenant, as Catalyst. Reads come from the replica when it is fresh, else from the API, and every read names its source. Writes go through the tenant's agent proxy as the app actor, with routes, stage ids, label ids and the bookkeeping marker resolved from the tenant contract by the `catalyst-skills` CLI. You never compose a URL, never name a stage by its display name, and never quote a label id or marker from memory.
+You read tickets and write to them in the person's cloud account, as Catalyst. Reads come from the replica when it is fresh, else the API, and name their source. Writes go out as the app actor, with routes, stage ids, label ids and the bookkeeping marker resolved from the contract by the `catalyst` CLI.
 
 ## Run first
 
-Run each with `--help` first; scripts are executed, never read.
+Scripts are run, never read; each prints `--help`.
 
-- `node scripts/read-ticket.mjs <ticket> [--comments]` — one ticket, everything inline, source line on stderr.
-- `node scripts/search.mjs <terms>` — tickets, PRs, projects, initiatives matching the terms.
-- `node scripts/comment.mjs <ticket> --body <text> [--parent <id>] [--bookkeeping]` — a comment as the app actor; a machine record takes `--bookkeeping`.
-- `node scripts/move.mjs <ticket> --slot <slot>` — a card move by slot (`--state-type backlog` parks).
-- `node scripts/label.mjs <ticket> --add <name> --remove <name>` — labels, resolved through the contract.
-- `node scripts/create-ticket.mjs --team <key> --title <text> [--description <text> | --stdin]` — a new ticket; cite its identifier only after it prints.
+- `node scripts/read-ticket.mjs <ticket> [--comments]`: one ticket, everything inline, source line on stderr.
+- `node scripts/search.mjs <terms>`: tickets, PRs, projects, initiatives matching the terms.
+- `node scripts/comment.mjs <ticket> --body <text> [--parent <id>] [--bookkeeping]`: a comment as the app actor.
+- `node scripts/move.mjs <ticket> --slot <slot>`: a card move by slot (`--state-type backlog` parks).
+- `node scripts/label.mjs <ticket> --add <name> --remove <name>`: labels, resolved through the contract.
+- `node scripts/create-ticket.mjs --team <key> --title <text> [--description <text> | --stdin]`: a new ticket; cite its identifier only after it prints.
 
 Exit codes: 0 done, 1 not found or a usage error, 2 this machine is not connected or the write was refused (budget spent, slot unmapped, label absent; the one line printed says which).
 
@@ -34,10 +33,9 @@ Exit codes: 0 done, 1 not found or a usage error, 2 this machine is not connecte
 
 ## Rules
 
-- **Read before acting.** Never summarise a ticket from its title; read the description and the thread. Cite identifiers and comment ids only after a script printed them.
-- **Name the source.** Quote the source line when freshness matters; a stale replica is never read silently, because the CLI falls back to the API and says so.
-- **Reply where it arrived, as Catalyst.** Thread under the comment you answer (`--parent`); never post as the human.
-- **Records carry the marker.** A merge note, a state-move log, a chain summary: `--bookkeeping`, so it never reads as a human turn. A real question is not bookkeeping.
-- **Move by slot, label by contract.** A stage name is display; the id is the authority, and the CLI resolves both. Moving to `dispatch` dispatches; the backlog-type state parks.
-- **A decision is an ask, not a ticket.** Raise it through `what-needs-me` with options, a default and what it blocks; a question filed as a ticket is held out of dispatch by shape.
-- **One write per need, no loops.** Writes spend a daily budget the contract names; batch, and report a refusal rather than retrying.
+- **Read before acting.** Read the description and the thread, never just the title. Cite identifiers and comment ids only after a script printed them, and quote the source line when freshness matters.
+- **Reply where it arrived, as Catalyst.** Thread under the comment you answer (`--parent`); the human speaks for themselves.
+- **Records carry the marker.** A merge note, a state-move log, a chain summary: `--bookkeeping`. A real question is not bookkeeping.
+- **Move by slot, label by contract.** Moving to `dispatch` dispatches; the backlog-type state parks.
+- **A decision is an ask, not a ticket.** Raise it through `what-needs-me`; a question filed as a ticket is held out of dispatch by shape.
+- **One write per need.** Every write is visible in the person's Linear and spends the contract's daily budget; batch, and report a refusal once. A move into dispatch starts paid work on a coding account.

package/skills/catalyst-linear/agents/openai.yaml

@@ -3,4 +3,4 @@ interface:
   short_description: "Read a ticket and what Catalyst wrote on it; comment, move, label and file tickets as the app actor"
   default_prompt: "Use $catalyst-linear to show me the ticket, its history, and what Catalyst wrote on it."
 policy:
-  allow_implicit_invocation: false
+  allow_implicit_invocation: true

package/skills/catalyst-linear/agents/portability.yaml

@@ -1,5 +1,5 @@
 identity: { pack: catalyst-cloud-skills, skill: catalyst-linear }
 effects: [external-write]
 mutating: true
-invocation: explicit
+invocation: implicit
 exposure: [catalog]