@catalyst-cloud/cli 0.9.4 → 0.13.0

package/dist/env/scan-wrangler.js

@@ -0,0 +1,120 @@
+const BINDING_KEY_BY_TABLE = {
+    kv_namespaces: "binding",
+    d1_databases: "binding",
+    r2_buckets: "binding",
+    "durable_objects.bindings": "name",
+    "queues.producers": "binding",
+    "queues.consumers": "binding",
+};
+// ⛔ TABLE_RE AND QUOTED_RE ARE END-ANCHORED, SO AN INLINE `#` COMMENT MUST BE STRIPPED FIRST
+// (validate attempt 29, CR-1 / CR-4). `[vars] # public settings` never matched TABLE_RE, so
+// `currentTable` stayed null and the scanner returned NOTHING for the whole file — zero bindings,
+// zero vars, zero notes: a silent, total failure in a tool whose entire value is completeness. And
+// `binding = "SESSIONS" # the session store` never matched QUOTED_RE, so the `: value` fallback
+// below made the raw remainder — quotes, comment and all — the binding NAME the customer is asked to
+// keep, drop or move. `stripInlineComment` is quote-aware, so a `#` inside a value (`id = "ab#cd"`)
+// is still value material and is left alone.
+const QUOTED_RE = /^"(.*)"$|^'(.*)'$/;
+const KEY_VALUE_RE = /^([A-Za-z_][A-Za-z0-9_-]*)\s*=\s*(.*)$/;
+const TABLE_RE = /^\[\[?([^\]]+)\]\]?$/;
+const ENV_TABLE_RE = /^env\.([^.]+)\.(.+)$/;
+export function scanWrangler(file, text) {
+    const sightings = [];
+    const lines = text.split("\n");
+    let currentTable = null;
+    let currentEnvironment;
+    // Tracks an open triple-quoted string, so a line INSIDE one (e.g. `a = not_a_name`) is never
+    // mined for a key — the key that opened the string (e.g. `MULTI = """`) already was.
+    let insideMultiline = null;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (insideMultiline) {
+            if (trimmed.includes(insideMultiline))
+                insideMultiline = null;
+            continue;
+        }
+        if (trimmed === "" || trimmed.startsWith("#"))
+            continue;
+        const uncommented = stripInlineComment(trimmed).trim();
+        if (uncommented === "")
+            continue;
+        const tableMatch = TABLE_RE.exec(uncommented);
+        if (tableMatch) {
+            let name = tableMatch[1].trim();
+            currentEnvironment = undefined;
+            const envMatch = ENV_TABLE_RE.exec(name);
+            if (envMatch) {
+                currentEnvironment = envMatch[1];
+                name = envMatch[2];
+            }
+            currentTable = name;
+            continue;
+        }
+        if (currentTable === null)
+            continue;
+        const kv = KEY_VALUE_RE.exec(uncommented);
+        if (!kv)
+            continue;
+        const key = kv[1];
+        const value = kv[2].trim();
+        if (isOpeningMultiline(value, '"""'))
+            insideMultiline = '"""';
+        else if (isOpeningMultiline(value, "'''"))
+            insideMultiline = "'''";
+        if (currentTable === "vars" || currentTable.endsWith(".vars")) {
+            sightings.push({
+                name: key,
+                finding: { file, line: i + 1, consumer: "wrangler.toml vars", consumerKind: "vars" },
+                isWranglerVar: true,
+                wranglerEnvironment: currentEnvironment,
+                localSource: "value committed in wrangler.toml — nothing to declare",
+            });
+            continue;
+        }
+        const bindingKey = BINDING_KEY_BY_TABLE[currentTable];
+        if (bindingKey && key === bindingKey) {
+            const qm = QUOTED_RE.exec(value);
+            const bindingName = qm ? (qm[1] ?? qm[2] ?? "") : value;
+            if (bindingName) {
+                sightings.push({
+                    name: bindingName,
+                    finding: { file, line: i + 1, consumer: `${currentTable} binding`, consumerKind: currentTable },
+                    isBinding: true,
+                    wranglerEnvironment: currentEnvironment,
+                    localSource: "Cloudflare binding",
+                });
+            }
+        }
+    }
+    return sightings;
+}
+/**
+ * The line with any TOML inline comment removed. A `#` only starts a comment outside a string, so
+ * the scan tracks the quote it is inside. A line whose quotes do not balance — a `"""` opener, most
+ * importantly — is returned untouched rather than guessed at.
+ */
+function stripInlineComment(line) {
+    let quote = null;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (quote !== null) {
+            if (ch === "\\")
+                i++;
+            else if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (ch === "#")
+            return line.slice(0, i);
+    }
+    return line;
+}
+function isOpeningMultiline(value, marker) {
+    if (!value.startsWith(marker))
+        return false;
+    return !(value.length > marker.length && value.endsWith(marker));
+}

package/dist/env/types.js

@@ -0,0 +1 @@
+export {};

package/dist/env/walk.js

@@ -0,0 +1,87 @@
+// walk.ts — the one definition of "the files this repository is made of", shared by every scanner
+// that needs to enumerate a tree. Skips the directories no scan should ever descend into.
+//
+// ⛔ A SYMLINK IS REPOSITORY CONTENT, AND REPOSITORY CONTENT IS UNTRUSTED (validate attempt 29,
+// M-2 / CR-5). `statSync` FOLLOWS a link, so the previous walk had no way to tell a real directory
+// from a link out of the tree, and no visited set to stop a cycle. Measured: a single `pkg/up -> ..`
+// link reported one name 41 times with absurd file:line pairs, and a committed `elsewhere -> /tmp/x`
+// walked a directory outside the repository entirely. So every entry is classified with a DIRENT
+// (never a followed stat), and a link is followed only when its real path is inside the repository
+// root and has not been walked before.
+import { readdirSync, realpathSync, statSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+export const SKIP_DIRS = new Set(["node_modules", "dist", "coverage", ".git"]);
+/** Every file under `root`, relative paths, POSIX-separated, skipping SKIP_DIRS. */
+export function walkRepo(root) {
+    const out = [];
+    let realRoot;
+    try {
+        realRoot = realpathSync(root);
+    }
+    catch {
+        return out;
+    }
+    // Real paths already descended into. Seeded with the root so a link back to it is a cycle.
+    const walked = new Set([realRoot]);
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const name = entry.name;
+            const full = join(dir, name);
+            let isDirectory = entry.isDirectory();
+            if (entry.isSymbolicLink()) {
+                let real;
+                try {
+                    real = realpathSync(full);
+                }
+                catch {
+                    continue;
+                }
+                if (!contains(realRoot, real))
+                    continue; // points out of the repository
+                try {
+                    isDirectory = statSync(full).isDirectory();
+                }
+                catch {
+                    continue;
+                }
+            }
+            if (isDirectory) {
+                if (SKIP_DIRS.has(name))
+                    continue;
+                // Every directory is keyed by its REAL path, link or not: `pkg/up -> pkg` is a cycle only
+                // because the link and the directory resolve to the same place, and checking the link alone
+                // would still walk the tree one extra time under its second name.
+                let real;
+                try {
+                    real = realpathSync(full);
+                }
+                catch {
+                    continue;
+                }
+                if (walked.has(real))
+                    continue; // a cycle, or a second route to the same tree
+                walked.add(real);
+                stack.push(full);
+            }
+            else {
+                out.push(relative(root, full).split("\\").join("/"));
+            }
+        }
+    }
+    return out.sort();
+}
+/** True when `child` is `root` itself or lies beneath it. Both must already be real paths. */
+export function contains(root, child) {
+    const a = resolve(root);
+    const b = resolve(child);
+    return b === a || b.startsWith(a.endsWith(sep) ? a : a + sep);
+}

package/dist/env.js

@@ -0,0 +1,76 @@
+// env.ts — `catalyst env inventory` / `env check`: a LOCAL, OFFLINE, repo-scoped reporter and
+// validator. Unlike every other verb in this file's siblings, `cmdEnv` never calls `requireConfig` or
+// `apiClient` — it needs neither a login nor a network call, which is the whole point of the feature:
+// a person reviews what a repository declares without connecting anything first.
+import { readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import { positionals } from "./args.js";
+import { validateDeclaration } from "./env/declaration-rules.js";
+import { inventoryRepo } from "./env/inventory.js";
+import { inventoryToJson, renderCheck, renderInventory } from "./env/render.js";
+import { UsageError } from "./errors.js";
+export async function cmdEnv(args, ctx, deps = {}) {
+    const [sub, ...rest] = positionals(args);
+    if (sub === undefined)
+        throw new UsageError("env needs a subcommand: inventory | check");
+    if (sub === "inventory") {
+        if (rest.length > 1)
+            throw new UsageError(`env inventory takes at most one path (got an extra "${rest[1]}")`);
+        const root = resolve(rest[0] ?? ".");
+        // C-3: walkRepo swallows a readdir failure and returns [], so without this an unreadable or
+        // mistyped path printed three empty groups and exited 0 — a typo that reads as "declares nothing".
+        let stat;
+        try {
+            stat = statSync(root);
+        }
+        catch {
+            ctx.stderr(`${root} does not exist — env inventory takes a path to a repository`);
+            return 1;
+        }
+        if (!stat.isDirectory()) {
+            ctx.stderr(`${root} is not a directory — env inventory takes a path to a repository`);
+            return 1;
+        }
+        const inv = inventoryRepo(root, deps);
+        if (args.json)
+            ctx.stdout(JSON.stringify(inventoryToJson(inv)));
+        else
+            for (const line of renderInventory(inv))
+                ctx.stdout(line);
+        return 0;
+    }
+    if (sub === "check") {
+        const file = rest[0];
+        if (!file)
+            throw new UsageError("env check needs a file: catalyst env check <path to catalyst.env.json>");
+        if (rest.length > 1)
+            throw new UsageError(`env check takes exactly one file (got an extra "${rest[1]}")`);
+        let text;
+        try {
+            text = readFileSync(file, "utf8");
+        }
+        catch (err) {
+            ctx.stderr(`could not read ${file}: ${err instanceof Error ? err.message : String(err)}`);
+            return 1;
+        }
+        let doc;
+        try {
+            doc = JSON.parse(text);
+        }
+        catch {
+            // C-4/S-2: JSON.parse's own message embeds the first ten characters of the input, so
+            // forwarding it prints content from the file — on a verb documented as never printing a value.
+            ctx.stderr(`${file} is not valid JSON`);
+            return 1;
+        }
+        const errors = validateDeclaration(doc);
+        const state = errors.length === 0 ? "valid" : "invalid";
+        if (args.json)
+            ctx.stdout(JSON.stringify({ state, errors }));
+        else
+            for (const line of renderCheck({ state, errors }, file))
+                ctx.stdout(line);
+        return state === "valid" ? 0 : 1;
+    }
+    throw new UsageError(`unknown env subcommand "${sub}": inventory | check`);
+}

package/dist/environment.js

@@ -131,7 +131,7 @@ export async function cmdEnvironment(args, ctx, deps = {}) {
                 if (body.reason)
                     ctx.stdout(`  reason: ${body.reason}`);
                 if (body.currentRevision !== undefined) {
-                    ctx.stdout(`  the declaration is now at revision ${body.currentRevision} — run \`catalyst-skills environment read\` and propose again from that`);
+                    ctx.stdout(`  the declaration is now at revision ${body.currentRevision} — run \`catalyst environment read\` and propose again from that`);
                 }
             }
             return 1;
@@ -144,14 +144,14 @@ export async function cmdEnvironment(args, ctx, deps = {}) {
             if (args.json)
                 ctx.stdout(JSON.stringify(body));
             else if (body.status !== "unchanged")
-                ctx.stdout("not delivered until it is approved: catalyst-skills environment approve");
+                ctx.stdout("not delivered until it is approved: catalyst environment approve");
             return 0;
         }
         // ⭐ Approve exactly what propose just returned. The whole point of the CAS is that the approver
         // saw the revision they are approving, and nothing here has to be copied by a human or a model.
         const state = body.state;
         if (!state) {
-            ctx.stderr("the cloud returned no state to approve — run: catalyst-skills environment read");
+            ctx.stderr("the cloud returned no state to approve — run: catalyst environment read");
             return 1;
         }
         const approved = await approveExact(api, routes, state.revision, state.canonicalHash);
@@ -172,7 +172,7 @@ export async function cmdEnvironment(args, ctx, deps = {}) {
     if (revision === undefined || hash === undefined) {
         const current = (await readState(api, routes)).current;
         if (current === null || current === undefined) {
-            ctx.stdout("there is no declaration to approve — propose one first: catalyst-skills environment propose --file <path>");
+            ctx.stdout("there is no declaration to approve — propose one first: catalyst environment propose --file <path>");
             return 1;
         }
         revision = current.revision;

package/dist/events.js

@@ -71,7 +71,7 @@ export async function cmdEvents(args, ctx, deps = {}) {
         if (controller.signal.aborted)
             return sub === "wait-for" ? 1 : 0;
         if (error.code === "ENOENT")
-            throw new CliError(`event cache is absent at ${directory} — start it with: catalyst-skills replica start --detach`, "events-absent", 3);
+            throw new CliError(`event cache is absent at ${directory} — start it with: catalyst replica start --detach`, "events-absent", 3);
         throw error;
     }
     finally {

package/dist/execution.js

@@ -37,14 +37,15 @@ export const EXCLUSION_REASONS = {
     retry_backoff: "the failed phase is retrying in place and waiting out its backoff",
     routing_unavailable: "the unit was claimed and refused at kickoff (no route, no eligible coding-account slot, or the provider is unavailable)",
     repo_paused: "an operator paused the repository",
-    remediate_parked: "the remediate phase is parked, so the failing phase has nowhere to be repaired; `catalyst-skills release <ticket>` releases the park once its cause is fixed",
-    phase_parked: "the offered phase is parked after repeated failures or the repair-round cap; `catalyst-skills release <ticket>` releases it once its cause is fixed",
+    remediate_parked: "the remediate phase is parked, so the failing phase has nowhere to be repaired; `catalyst release <ticket>` releases the park once its cause is fixed",
+    phase_parked: "the offered phase is parked after repeated failures or the repair-round cap; `catalyst release <ticket>` releases it once its cause is fixed",
     later_phase_lease_held: "an earlier phase is offered while a live container still holds a later phase of this ticket",
     human_owned_pr: "a person's own pull request holds this ticket; it releases itself when that PR closes or merges",
     review_not_converging: "review and repair kept finding new problems without converging; a person reads the findings and comments on the ticket to resume",
     round_threshold: "the ticket spent its lifetime repair budget; answering its ask or pushing a fix buys one more cycle",
     claim_storm: "this unit was claimed too many times in the last hour, so it waits out the hour; nothing to release",
     repo_at_capacity: "the repository's runner seats are all in use; it starts when one frees",
+    wip_limit: "the project is at its WIP limit (tickets in progress, counting blocked, parked and waiting ones); this new start waits until one of them finishes, and the tickets in progress keep running",
 };
 /** Every fail-closed unknown the evaluator names. */
 export const UNKNOWN_REASONS = {

package/dist/identity.js

@@ -14,7 +14,7 @@ function render(result, choices) {
         return `${summary}\nNo choices were offered. An automatic match cannot be replaced; an unmatched roster may need a retry.`;
     if (result.options.length === 0)
         return `${summary}\nThe workspace roster has no eligible people.`;
-    return [summary, ...result.options.map((o) => `${o.id}\t${o.displayName ?? o.name ?? "(unnamed)"}`), "Select your own identity explicitly: catalyst-skills identity linear set <linearUserId>"].join("\n");
+    return [summary, ...result.options.map((o) => `${o.id}\t${o.displayName ?? o.name ?? "(unnamed)"}`), "Select your own identity explicitly: catalyst identity linear set <linearUserId>"].join("\n");
 }
 export async function cmdIdentity(args, ctx, deps = {}) {
     const parts = positionals(args);
@@ -25,11 +25,11 @@ export async function cmdIdentity(args, ctx, deps = {}) {
     }
     const cfg = requireConfig(ctx);
     if (!cfg.user)
-        throw new CliError("this machine uses a tenant account key; run catalyst-skills login as yourself", "member-required");
+        throw new CliError("this machine uses a tenant account key; run catalyst login as yourself", "member-required");
     const createClient = deps.createClient ?? (async (options) => (await loadHttpSdk()).createTenantClient(options));
     const client = await createClient({ key: await bearerFor(ctx, cfg), baseUrl: cfg.baseUrl, fetch: ctx.fetch });
     if (!client.linearIdentity)
-        throw new CliError("the installed SDK lacks identity recovery; upgrade catalyst-skills after the SDK release", "sdk-upgrade-required");
+        throw new CliError("the installed SDK lacks identity recovery; upgrade the catalyst CLI after the SDK release", "sdk-upgrade-required");
     if (action === "set") {
         // The arity check above requires a selection; never choose the first roster entry for a person.
         if (selected === undefined)

package/dist/oauth.js

@@ -152,7 +152,7 @@ async function pollDeviceCode(ctx, discovery, auth, sleep) {
             continue;
         }
         if (err === "access_denied")
-            throw new CliError("login was denied — run: catalyst-skills login to try again", "login-denied");
+            throw new CliError("login was denied — run: catalyst login to try again", "login-denied");
         if (err === "expired_token")
             return "expired";
         // A transient HTTP failure (request timeout, rate limit, server error) is retried, honouring
@@ -220,7 +220,7 @@ export async function bearerFor(ctx, cfg, deps = {}) {
     if (typeof cfg.key === "string" && cfg.key !== "")
         return cfg.key;
     if (!cfg.auth)
-        throw new CliError("this machine is not connected — run: catalyst-skills login", "not-configured");
+        throw new CliError("this machine is not connected — run: catalyst login", "not-configured");
     const msToExpiry = Date.parse(cfg.auth.expiresAt) - ctx.now().getTime();
     if (Number.isFinite(msToExpiry) && msToExpiry > REFRESH_SKEW_MS)
         return cfg.auth.accessToken;
@@ -256,7 +256,7 @@ async function refreshAndPersist(ctx, cfg, deps) {
         const err = await oauthError(res, discovery.tokenUrl);
         if (err === "invalid_grant") {
             // revocation or > inactivity window — the ONLY session-expired case; NOT routine expiry.
-            throw new CliError("your login expired or was revoked — run: catalyst-skills login", "session-expired");
+            throw new CliError("your login expired or was revoked — run: catalyst login", "session-expired");
         }
         const transient = res.status === 429 || res.status >= 500;
         if (!transient)

package/dist/query.js

@@ -156,7 +156,7 @@ async function fromApi(ctx, cfg, sub, rest, f, args) {
             if (!q)
                 throw new UsageError("search needs terms: query search <terms>");
             const res = await api.getJson("/api/v1/search", { query: { q, limit: f.limit } });
-            return rowsOf(res.body);
+            return searchRows(res.body);
         }
         case "changes": {
             const since = flagString(args, "since");
@@ -224,6 +224,21 @@ export function applyFilters(rows, f) {
         return true;
     });
 }
+/** The hub answers search in four groups (`issues`, `pulls`, `projects`, `initiatives`, the read
+ *  model's SearchView). `rowsOf` returns only the first array it finds, so it dropped every match that
+ *  was not a ticket. Every group comes back here, flattened, each row tagged with its `kind`. */
+const SEARCH_GROUPS = [["issues", "issue"], ["pulls", "pull"], ["projects", "project"], ["initiatives", "initiative"]];
+export function searchRows(body) {
+    if (Array.isArray(body))
+        return body;
+    if (!body || typeof body !== "object")
+        return [];
+    const b = body;
+    if (SEARCH_GROUPS.some(([group]) => Array.isArray(b[group]))) {
+        return SEARCH_GROUPS.flatMap(([group, kind]) => Array.isArray(b[group]) ? b[group].map((row) => ({ kind, ...row })) : []);
+    }
+    return rowsOf(body);
+}
 function printResult(ctx, args, sub, result) {
     if (args.json || !Array.isArray(result)) {
         ctx.stdout(JSON.stringify(result, null, args.json ? 0 : 2));
@@ -242,6 +257,17 @@ export function summaryLine(sub, r) {
             return `${r.id}  ${r.state ?? "?"}  ${r.name ?? ""}`;
         case "cycles":
             return `cycle ${r.number ?? r.id}  ${r.name ?? ""}  ${r.starts_at ?? ""} → ${r.ends_at ?? ""}`;
+        case "search":
+            switch (r.kind) {
+                case "pull":
+                    return `pull        #${r.number ?? "?"}  ${r.title ?? ""}${r.repo_id ? `  (${r.repo_id})` : ""}`;
+                case "project":
+                    return `project     ${r.name ?? r.id}`;
+                case "initiative":
+                    return `initiative  ${r.name ?? r.id}`;
+                default:
+                    return `issue       ${r.identifier ?? r.id}  ${r.title ?? ""}`;
+            }
         default:
             return JSON.stringify(r);
     }

package/dist/ready.js

@@ -184,7 +184,7 @@ export async function readyReport(ctx, deps) {
                     ? `config: joined ${cfg.name} as ${cfg.user.label} (${cfg.user.role})`
                     : `config: joined ${cfg.name} (${cfg.slug}) as ${cfg.principal}`,
             }
-            : { id: "config", ok: false, line: "config: not connected", fix: "npx @catalyst-cloud/catalyst-skills login (keyless; or pass --key / set CATALYST_CLOUD_TOKEN)", who: "you (approve the login in your browser)" });
+            : { id: "config", ok: false, line: "config: not connected", fix: "npx -p @catalyst-cloud/cli catalyst login (keyless; or pass --key / set CATALYST_CLOUD_TOKEN)", who: "you (approve the login in your browser)" });
     }
     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" });
@@ -192,7 +192,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", who: "you" });
+        checks.push({ id: "contract", ok: false, line: "contract: not cached", fix: "catalyst 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: upgradeCommand(), who: "you" });
@@ -290,7 +290,7 @@ export async function readyReport(ctx, deps) {
         checks.push({ id: "skills", ok: true, line: `skills: all ${deps.skillNames.length} present in ${skillsDir}` });
     }
     else {
-        checks.push({ id: "skills", ok: false, line: `skills: ${present.length} of ${deps.skillNames.length} in ${skillsDir}, missing ${missing.join(", ")}`, fix: "catalyst-skills install", who: "you" });
+        checks.push({ id: "skills", ok: false, line: `skills: ${present.length} of ${deps.skillNames.length} in ${skillsDir}, missing ${missing.join(", ")}`, fix: "catalyst install", who: "you" });
     }
     try {
         await (deps.loadSdk ?? loadSdk)();

package/dist/release.js

@@ -37,7 +37,7 @@ export function renderTicketRelease(ticket, r) {
     const lines = [];
     const dry = r.dryRun === true;
     if (r.outcome === "nothing-held") {
-        lines.push(`${ticket}: nothing holds this ticket — run \`catalyst-skills explain ${ticket}\` for why it is not running`);
+        lines.push(`${ticket}: nothing holds this ticket — run \`catalyst explain ${ticket}\` for why it is not running`);
     }
     else if (r.outcome === "refused") {
         lines.push(dry ? `${ticket} (dry run): would be refused — nothing would be released:` : `${ticket}: refused — nothing was released:`);

package/dist/replica.js

@@ -196,7 +196,7 @@ function baseStatusLine(s) {
         case "not-configured":
             return `replica: not configured (${s.reasons.join("; ")})`;
         case "absent":
-            return `replica: absent at ${s.dbPath} — start it with: catalyst-skills replica start --detach`;
+            return `replica: absent at ${s.dbPath} — start it with: catalyst replica start --detach`;
         case "fresh":
             return `replica: fresh at ${s.dbPath} (cursor ${s.cursor}, heartbeat ${s.heartbeatAgeMs}ms ago${s.lag !== undefined ? `, ${s.lag} behind head ${s.head}` : ""})`;
         case "stale":
@@ -240,7 +240,9 @@ export async function engineFor(sdk, dbPath, ctx, deps = {}) {
     }
     catch (err) {
         const why = err instanceof Error ? err.message.split("\n")[0] : String(err);
-        ctx.stderr(`[catalyst-skills] better-sqlite3 unavailable (${why}); using node:sqlite`);
+        // node:sqlite is the supported path (CTC-4272): say nothing when it works, except under CATALYST_DEBUG.
+        if (ctx.env?.CATALYST_DEBUG === "1")
+            ctx.stderr(`[catalyst] better-sqlite3 unavailable (${why}); using node:sqlite`);
         return deps.readonly ? sdk.nodeSqliteReadonlyEngine(dbPath) : sdk.nodeSqliteEngine(dbPath);
     }
 }
@@ -252,7 +254,7 @@ export const SNAPSHOT_MAX_FAILURES = 5;
  *  count on; staying live is that signal. The failing warm loop never reaches it — its resync demand
  *  fails and tears the attempt down first (CTC-2499). */
 export const SNAPSHOT_LIVE_STABLE_MS = 60_000;
-export const REPLICA_RESTART_COMMAND = "catalyst-skills replica start --detach";
+export const REPLICA_RESTART_COMMAND = "catalyst replica start --detach";
 const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 function defaultWaitForStop() {
     return new Promise((resolve) => {
@@ -342,7 +344,7 @@ async function cmdStart(args, ctx, cfg, dbPath, deps) {
         const argv = (deps.argv ?? process.argv.slice(1)).filter((a) => a !== "--detach");
         const { pid } = (deps.detach ?? detachSelf)(argv, ctx.env);
         writeFileSync(pidfilePath(dbPath), `${pid}\n`);
-        ctx.stdout(`replica writer started in the background (pid ${pid}, db ${dbPath}); check with: catalyst-skills replica status`);
+        ctx.stdout(`replica writer started in the background (pid ${pid}, db ${dbPath}); check with: catalyst replica status`);
         return 0;
     }
     const sdk = await loadSdk();
@@ -503,7 +505,7 @@ async function cmdStart(args, ctx, cfg, dbPath, deps) {
         const lastError = attemptError ?? "the snapshot pull failed";
         const nowMs = ctx.now().getTime();
         const stopped = failures >= maxFailures
-            ? { at: nowMs, reason: `${failures} consecutive snapshot failures`, restartWith: "catalyst-skills replica start --detach" }
+            ? { at: nowMs, reason: `${failures} consecutive snapshot failures`, restartWith: "catalyst replica start --detach" }
             : null;
         writeWriterState(dbPath, { pid: process.pid, consecutiveFailures: failures, lastError, lastFailureAt: nowMs, stopped }, nowMs);
         if (stopped) {
@@ -562,7 +564,7 @@ export function assertSingleSelect(sql) {
 async function cmdSql(args, ctx, dbPath, sql, deps) {
     const query = assertSingleSelect(sql);
     if (!existsSync(dbPath))
-        throw new CliError(`no replica at ${dbPath} — start it with: catalyst-skills replica start --detach`, "replica-absent", 3);
+        throw new CliError(`no replica at ${dbPath} — start it with: catalyst replica start --detach`, "replica-absent", 3);
     const sdk = await loadSdk();
     const engine = await engineFor(sdk, dbPath, ctx, { ...deps.engineDeps, readonly: true });
     const replica = await sdk.CatalystReplica.openReadOnly({ dbPath, engine, log: () => { } });
@@ -577,7 +579,7 @@ async function cmdSql(args, ctx, dbPath, sql, deps) {
 }
 async function cmdSchema(args, ctx, dbPath, table) {
     if (!existsSync(dbPath))
-        throw new CliError(`no replica at ${dbPath} — the schema is what the file holds; start it with: catalyst-skills replica start --detach`, "replica-absent", 3);
+        throw new CliError(`no replica at ${dbPath} — the schema is what the file holds; start it with: catalyst replica start --detach`, "replica-absent", 3);
     const db = new (loadSqlite().DatabaseSync)(dbPath, { readOnly: true });
     try {
         const tables = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name").all().map((r) => r.name);

package/dist/runtime-store.js

@@ -21,11 +21,11 @@ const PLATFORM_ARCH = {
  *  needs `.zip` extraction, a separate mechanism this ticket does not build (D7). */
 export function tarballFor(version, platform, arch) {
     if (platform === "win32") {
-        throw new CliError("catalyst-skills runtime install does not support Windows yet — supported: darwin (arm64, x64) and linux (x64, arm64). Use whatever Node 22.15+ or bun 1.4+ you already have on Windows.", "runtime-unsupported-platform");
+        throw new CliError("catalyst runtime install does not support Windows yet — supported: darwin (arm64, x64) and linux (x64, arm64). Use whatever Node 22.15+ or bun 1.4+ you already have on Windows.", "runtime-unsupported-platform");
     }
     const arches = PLATFORM_ARCH[platform];
     if (!arches || !arches.includes(arch)) {
-        throw new CliError(`catalyst-skills runtime install does not support ${platform}/${arch} — supported: darwin (arm64, x64) and linux (x64, arm64)`, "runtime-unsupported-platform");
+        throw new CliError(`catalyst runtime install does not support ${platform}/${arch} — supported: darwin (arm64, x64) and linux (x64, arm64)`, "runtime-unsupported-platform");
     }
     const file = `node-v${version}-${platform}-${arch}.tar.gz`;
     return { file, url: `https://nodejs.org/dist/v${version}/${file}`, shasums: `https://nodejs.org/dist/v${version}/SHASUMS256.txt` };

package/dist/runtime.js

@@ -13,7 +13,7 @@
 export const BUN_MIN = "1.4.0";
 /** The ONE copy-pasteable command. Installs a pinned Node under the CLI's own cache and pins it;
  *  it never touches the machine's default Node and needs no admin rights. See src/runtime-store.ts. */
-export const FIX_COMMAND = "npx -y @catalyst-cloud/catalyst-skills runtime install";
+export const FIX_COMMAND = "npx -y -p @catalyst-cloud/cli catalyst runtime install";
 /** Detect the runtime this process is running on. `process.versions.bun` is present only under bun. */
 export function detectRuntime(versions = process.versions) {
     if (versions.bun)

package/dist/secret.js

@@ -70,7 +70,7 @@ function requireRepo(args, verb) {
 /** The cloud's refusal, in its own words, plus what to do for the two we can explain. */
 function refusalLine(status, body, repo) {
     if (status === 401) {
-        return "refused (401): the cloud did not accept your credential here. If `catalyst-skills me` works, this cloud predates secret writes from the CLI and needs a newer release; otherwise log in again.";
+        return "refused (401): the cloud did not accept your credential here. If `catalyst me` works, this cloud predates secret writes from the CLI and needs a newer release; otherwise log in again.";
     }
     if (status === 404)
         return `refused (404): ${repo} is not a repository of this tenant (register it in the app first)`;

package/dist/skills.js

@@ -137,5 +137,5 @@ export function updateNoticeLine(previous, current, entry) {
     // minor — so it never crosses 0.2.x → 0.3.0. Pin @latest via `npm install`, THEN re-run login: the
     // install alone does not rewrite customer.json.cliPath, so the skill helpers would keep spawning the
     // stale recorded bundle and repeat this notice forever; the new global bin records its own path.
-    return `[catalyst-skills] updated ${previous} → ${current}: ${summary} · update with: ${upgradeCommand()}`;
+    return `[catalyst] updated ${previous} → ${current}: ${summary} · update with: ${upgradeCommand()}`;
 }