@catalyst-cloud/cli 0.14.6 → 0.14.7

package/dist/ready.js

@@ -1,19 +1,19 @@
 // ready.ts — `ready`: the machine checks plus the tenant's own readiness vector from the contract,
 // one verdict, and per failure the fix and who can apply it. The replica is optional, so its absence
-// is a note, never a failure; the SDK loading IS a check, because the replica and watch need it.
-import { accessSync, constants, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+// is a note, never a failure; the HTTP SDK loading is a check for cloud reads.
+import { accessSync, constants, existsSync, readFileSync, realpathSync, statSync, } from "node:fs";
 import { basename, delimiter, dirname, join } from "node:path";
-import { LEGACY_PACKAGE_NAME, PACKAGE_NAME, defaultSkillsDirFor, loadConfig, normalizeBaseUrl, readManifest, upgradeCommand } from "./config.js";
+import { LEGACY_PACKAGE_NAME, PACKAGE_NAME, defaultSkillsDirFor, loadConfig, normalizeBaseUrl, readManifest, upgradeCommand, } from "./config.js";
 import { contractVersionInRange, readContractCache } from "./contract.js";
 import { CliError } from "./errors.js";
 import { latestPublishedVersion } from "./published.js";
-import { replicaStatus, writerIsRunning } from "./replica.js";
-import { loadSdk } from "./sdk.js";
-import { FIX_COMMAND, detectRuntime, runtimeVerdict, supportedRangeText } from "./runtime.js";
+import { replicaStatus, writerIsRunning, } from "./replica.js";
+import { loadHttpSdk } from "./sdk.js";
+import { FIX_COMMAND, detectRuntime, runtimeVerdict, supportedRangeText, } from "./runtime.js";
 import { semverOlder } from "./semver.js";
 import { FIRST_STAMPED_VERSION } from "./skill-shape.js";
 import { installedBundleVersion } from "./skills.js";
-import { onboardingReadyReport, observeCloudOnboarding } from "./onboard-ready.js";
+import { onboardingReadyReport, observeCloudOnboarding, } from "./onboard-ready.js";
 import { selectedOnboardTeam } from "./onboard-existing.js";
 import { onboardStatePath, readOnboardJournal } from "./onboard.js";
 export { semverOlder };
@@ -98,7 +98,11 @@ export function catalystCommandCheck(env, platform = process.platform) {
     if (found === null)
         return null;
     if (isThisCliLauncher(found))
-        return { id: "command", ok: true, line: `command: catalyst on PATH is this CLI (${found})` };
+        return {
+            id: "command",
+            ok: true,
+            line: `command: catalyst on PATH is this CLI (${found})`,
+        };
     return {
         id: "command",
         ok: false,
@@ -108,7 +112,9 @@ export function catalystCommandCheck(env, platform = process.platform) {
     };
 }
 function nameList(v) {
-    return Array.isArray(v) ? v.filter((n) => typeof n === "string" && n.length > 0) : [];
+    return Array.isArray(v)
+        ? v.filter((n) => typeof n === "string" && n.length > 0)
+        : [];
 }
 /** Entries whose name and references are both present; anything malformed is dropped, not guessed. */
 function unresolvedList(v) {
@@ -119,7 +125,9 @@ function unresolvedList(v) {
             return [];
         const { name, references } = u;
         const refs = nameList(references);
-        return typeof name === "string" && name.length > 0 && refs.length > 0 ? [{ name, references: refs }] : [];
+        return typeof name === "string" && name.length > 0 && refs.length > 0
+            ? [{ name, references: refs }]
+            : [];
     });
 }
 function unresolvedLine(u) {
@@ -155,7 +163,10 @@ function teamCheckFix(label, c) {
     for (const u of unresolved)
         parts.push(unresolvedLine(u));
     for (const note of Array.isArray(c.repos) ? c.repos : []) {
-        if (typeof note !== "object" || note === null || typeof note.repo !== "string" || note.repo.length === 0)
+        if (typeof note !== "object" ||
+            note === null ||
+            typeof note.repo !== "string" ||
+            note.repo.length === 0)
             continue;
         const repoUnresolved = unresolvedList(note.unresolved);
         const skip = new Set(repoUnresolved.map((u) => u.name));
@@ -171,7 +182,9 @@ function teamCheckFix(label, c) {
 }
 function whoCanAnswer(doc) {
     const roles = doc.humans.map((h) => `${h.role} ${h.linearUserId}`);
-    return roles.length ? roles.join(", ") : "a tenant owner or admin (none resolved on the contract)";
+    return roles.length
+        ? roles.join(", ")
+        : "a tenant owner or admin (none resolved on the contract)";
 }
 export async function readyReport(ctx, deps) {
     const checks = [];
@@ -197,21 +210,49 @@ 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 -p @catalyst-cloud/cli catalyst 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" });
+        checks.push({
+            id: "config",
+            ok: false,
+            line: `config: ${err instanceof CliError ? err.message : String(err)}`,
+            fix: "re-run login to rewrite it",
+            who: "you",
+        });
     }
     const cache = readContractCache(ctx.home);
     const range = readManifest().tenantContractRange;
     if (!cache) {
-        checks.push({ id: "contract", ok: false, line: "contract: not cached", fix: "catalyst 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" });
+        checks.push({
+            id: "contract",
+            ok: false,
+            line: `contract: version ${cache.contractVersion} is outside this bundle's range ${range}`,
+            fix: upgradeCommand(),
+            who: "you",
+        });
     }
     else {
-        checks.push({ id: "contract", ok: true, line: `contract: ${cache.contractVersion} cached ${cache.fetchedAt} (range ${range})` });
+        checks.push({
+            id: "contract",
+            ok: true,
+            line: `contract: ${cache.contractVersion} cached ${cache.fetchedAt} (range ${range})`,
+        });
     }
     // The cloud MAY publish the bundle it expects (catalyst-cloud#3746). Read it defensively: warn (never
     // refuse) when this installed bundle is older than the minimum, and emit nothing when the field is
@@ -265,7 +306,8 @@ export async function readyReport(ctx, deps) {
             // names are always printed rather than hidden behind whichever branch happened to win.
             const found = installedBundleVersion(skillsDir, deps.skillNames);
             const stampBehind = found.version !== null && semverOlder(found.version, pub.latest);
-            const unstampedBehind = found.unstamped.length > 0 && !semverOlder(pub.latest, FIRST_STAMPED_VERSION);
+            const unstampedBehind = found.unstamped.length > 0 &&
+                !semverOlder(pub.latest, FIRST_STAMPED_VERSION);
             if (stampBehind || unstampedBehind) {
                 const facts = [];
                 if (stampBehind)
@@ -286,7 +328,13 @@ export async function readyReport(ctx, deps) {
     if (cfg) {
         checks.push(cfg.cliPath && existsSync(cfg.cliPath)
             ? { id: "cliPath", ok: true, line: `cliPath: ${cfg.cliPath}` }
-            : { id: "cliPath", ok: false, line: `cliPath: ${cfg.cliPath ? `${cfg.cliPath} does not exist` : "not recorded"}`, fix: "re-run login so the skill scripts can find this CLI", who: "you" });
+            : {
+                id: "cliPath",
+                ok: false,
+                line: `cliPath: ${cfg.cliPath ? `${cfg.cliPath} does not exist` : "not recorded"}`,
+                fix: "re-run login so the skill scripts can find this CLI",
+                who: "you",
+            });
     }
     const command = catalystCommandCheck(ctx.env);
     if (command)
@@ -297,17 +345,36 @@ export async function readyReport(ctx, deps) {
     const present = deps.skillNames.filter((n) => existsSync(join(skillsDir, n, "SKILL.md")));
     const missing = deps.skillNames.filter((n) => !present.includes(n));
     if (present.length === 0) {
-        checks.push({ id: "skills", ok: true, note: true, line: `skills: none copied to ${skillsDir} — you are reading one, so your agent installed them its own way` });
+        checks.push({
+            id: "skills",
+            ok: true,
+            note: true,
+            line: `skills: none copied to ${skillsDir} — you are reading one, so your agent installed them its own way`,
+        });
     }
     else if (missing.length === 0) {
-        checks.push({ id: "skills", ok: true, line: `skills: all ${deps.skillNames.length} present in ${skillsDir}` });
+        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 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)();
-        checks.push({ id: "sdk", ok: true, line: "sdk: loads (replica and watch are available)" });
+        await (deps.loadSdk ?? loadHttpSdk)();
+        checks.push({
+            id: "sdk",
+            ok: true,
+            line: "sdk: loads (cloud HTTP reads are available)",
+        });
     }
     catch (err) {
         checks.push({
@@ -319,7 +386,12 @@ export async function readyReport(ctx, deps) {
         });
     }
     const replica = replicaStatus(ctx, cfg);
-    checks.push({ id: "replica", ok: replica.verdict === "fresh", note: true, line: readyReplicaLine(replica) });
+    checks.push({
+        id: "replica",
+        ok: replica.verdict === "fresh",
+        note: true,
+        line: readyReplicaLine(replica),
+    });
     if (cache) {
         const doc = cache.doc;
         const who = whoCanAnswer(doc);
@@ -334,22 +406,36 @@ export async function readyReport(ctx, deps) {
             if (dg && typeof dg.status === "string") {
                 const slots = (dg.missingSlots ?? []).join(", ");
                 checks.push(dg.status === "open"
-                    ? { id: `team:${label}:dispatchGate`, ok: true, line: `team ${label}: dispatch gate open` }
+                    ? {
+                        id: `team:${label}:dispatchGate`,
+                        ok: true,
+                        line: `team ${label}: dispatch gate open`,
+                    }
                     : {
                         id: `team:${label}:dispatchGate`,
                         ok: false,
                         line: `team ${label}: dispatch gate ${dg.status}${slots ? ` (${slots})` : ""}, blocking`,
-                        fix: dg.remedy ?? `open settings for team ${label} and map its stages`,
+                        fix: dg.remedy ??
+                            `open settings for team ${label} and map its stages`,
                         who,
                     });
             }
             if (team.readiness.status === "unchecked") {
-                checks.push({ id: `team:${label}`, ok: true, note: true, line: `team ${label}: readiness not checked yet` });
+                checks.push({
+                    id: `team:${label}`,
+                    ok: true,
+                    note: true,
+                    line: `team ${label}: readiness not checked yet`,
+                });
                 continue;
             }
             const bad = team.readiness.checks.filter((c) => c.state !== "pass");
             if (bad.length === 0 && team.readiness.status === "ready") {
-                checks.push({ id: `team:${label}`, ok: true, line: `team ${label}: ready` });
+                checks.push({
+                    id: `team:${label}`,
+                    ok: true,
+                    line: `team ${label}: ready`,
+                });
                 continue;
             }
             for (const c of bad) {
@@ -365,7 +451,14 @@ export async function readyReport(ctx, deps) {
                 });
             }
             if (bad.length === 0 && team.readiness.status !== "ready") {
-                checks.push({ id: `team:${label}`, ok: team.readiness.status !== "blocked", note: team.readiness.status === "degraded", line: `team ${label}: ${team.readiness.status}`, fix: `open settings for team ${label}`, who });
+                checks.push({
+                    id: `team:${label}`,
+                    ok: team.readiness.status !== "blocked",
+                    note: team.readiness.status === "degraded",
+                    line: `team ${label}: ${team.readiness.status}`,
+                    fix: `open settings for team ${label}`,
+                    who,
+                });
             }
         }
     }
@@ -378,10 +471,19 @@ export async function cmdReady(args, ctx, deps) {
         if (!onboarding) {
             const cfg = loadConfig(ctx.home);
             const journal = readOnboardJournal(onboardStatePath(ctx.home, ctx.env), readManifest().version, ctx.now());
-            const bound = cfg?.user && journal && (journal.account ?? journal.tenant) === cfg.account &&
-                journal.membershipId === cfg.user.id && typeof journal.baseUrl === "string" && normalizeBaseUrl(journal.baseUrl) === normalizeBaseUrl(cfg.baseUrl);
+            const bound = cfg?.user &&
+                journal &&
+                (journal.account ?? journal.tenant) === cfg.account &&
+                journal.membershipId === cfg.user.id &&
+                typeof journal.baseUrl === "string" &&
+                normalizeBaseUrl(journal.baseUrl) === normalizeBaseUrl(cfg.baseUrl);
             const team = bound ? selectedOnboardTeam(journal) : undefined;
-            onboarding = { teamIds: team ? [team] : undefined, localSync: args.flags["local-sync"] === true || Boolean(bound && journal.localSync), observe: observeCloudOnboarding };
+            onboarding = {
+                teamIds: team ? [team] : undefined,
+                localSync: args.flags["local-sync"] === true ||
+                    Boolean(bound && journal.localSync),
+                observe: observeCloudOnboarding,
+            };
         }
         const report = await onboardingReadyReport(ctx, onboarding);
         if (args.json)
@@ -393,9 +495,15 @@ export async function cmdReady(args, ctx, deps) {
                 ctx.stdout(`Work observed${report.work.ticket ? ` on ${report.work.ticket}` : ""}.`);
             else
                 ctx.stdout("Fresh project work has not been verified by this check.");
-            ctx.stdout(report.state === "complete" ? "Onboarding complete." : "Setup still needs checks. Resume: catalyst onboard");
+            ctx.stdout(report.state === "complete"
+                ? "Onboarding complete."
+                : "Setup still needs checks. Resume: catalyst onboard");
         }
-        return report.state === "complete" ? 0 : report.checks.some(check => check.required && check.state === "fail") ? 10 : 11;
+        return report.state === "complete"
+            ? 0
+            : report.checks.some((check) => check.required && check.state === "fail")
+                ? 10
+                : 11;
     }
     const report = await readyReport(ctx, deps);
     if (args.json) {

package/dist/replica.js

@@ -6,7 +6,7 @@
 import { existsSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { flagBool, flagInt, flagString, positionals } from "./args.js";
-import { apiBase, loadConfig, replicaDbPath } from "./config.js";
+import { apiBase, loadConfig, replicaDbPath, replicaOptedIn } from "./config.js";
 import { detachSelf } from "./detach.js";
 import { CliError, UsageError } from "./errors.js";
 import { apiClient } from "./transport.js";
@@ -133,11 +133,14 @@ export function readCursor(dbPath) {
         db?.close();
     }
 }
+const NOT_CONNECTED = "not connected";
+const CLOUD_READS_LINE = "replica: not configured (cloud reads; local sync is opt-in)";
 /** The in-process status logic `query` and `ready` reuse. */
 export function replicaStatus(ctx, cfg, opts = {}) {
     const base = {
         verdict: "not-configured",
         exitCode: 2,
+        configured: false,
         dbPath: null,
         cursor: null,
         heartbeatAgeMs: null,
@@ -148,7 +151,7 @@ export function replicaStatus(ctx, cfg, opts = {}) {
         writer: null,
     };
     if (!cfg)
-        return { ...base, reasons: ["not connected"] };
+        return { ...base, reasons: [NOT_CONNECTED] };
     let dbPath;
     try {
         dbPath = opts.dbPath ?? replicaDbPath(cfg, ctx.home, ctx.env);
@@ -158,9 +161,10 @@ export function replicaStatus(ctx, cfg, opts = {}) {
             return { ...base, reasons: [error.message] };
         throw error;
     }
+    const configured = replicaOptedIn(ctx.home, ctx.env);
     const writer = readWriterState(dbPath);
     if (!existsSync(dbPath))
-        return { ...base, verdict: "absent", exitCode: 3, dbPath, reasons: ["no replica file"], writer };
+        return { ...base, verdict: "absent", exitCode: 3, configured, dbPath, reasons: ["no replica file"], writer };
     const staleMs = opts.staleMs ?? DEFAULT_STALE_MS;
     const nowMs = opts.nowMs ?? ctx.now().getTime();
     const lock = readLock(dbPath);
@@ -181,6 +185,7 @@ export function replicaStatus(ctx, cfg, opts = {}) {
     return {
         verdict: fresh ? "fresh" : "stale",
         exitCode: fresh ? 0 : 1,
+        configured,
         dbPath,
         cursor,
         heartbeatAgeMs,
@@ -194,8 +199,10 @@ export function replicaStatus(ctx, cfg, opts = {}) {
 function baseStatusLine(s) {
     switch (s.verdict) {
         case "not-configured":
-            return `replica: not configured (${s.reasons.join("; ")})`;
+            return s.reasons[0] === NOT_CONNECTED ? `replica: not configured (${s.reasons.join("; ")})` : CLOUD_READS_LINE;
         case "absent":
+            if (!s.configured)
+                return CLOUD_READS_LINE;
             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}` : ""})`;

package/dist/sdk.js

@@ -4,8 +4,13 @@ import { readManifest } from "./config.js";
 import { FIX_COMMAND, supportedRangeText } from "./runtime.js";
 let cached = null;
 let cachedHttp = null;
+let cachedLive = null;
+let cachedEvents = null;
 const realImport = () => import("@catalyst-cloud/sdk/node");
 const realHttpImport = () => import("@catalyst-cloud/sdk");
+// SDK 0.13 has no `./live` entry; its root entry carries LiveSyncClient and no replica code. Point
+// this at `@catalyst-cloud/sdk/live` once the pin reaches 0.14.
+const realLiveImport = () => import("@catalyst-cloud/sdk");
 /** The isomorphic typed HTTP client; keeps the SDK import in this module. */
 export function loadHttpSdk(importer = realHttpImport) {
     if (!cachedHttp) {
@@ -16,6 +21,16 @@ export function loadHttpSdk(importer = realHttpImport) {
     }
     return cachedHttp;
 }
+/** The live push client for `watch`, loaded without the replica-bearing node entry (CTC-4508). */
+export function loadLiveSdk(importer = realLiveImport) {
+    if (!cachedLive) {
+        cachedLive = importer().catch((err) => {
+            cachedLive = null;
+            throw new CliError(`the Catalyst Cloud SDK live client could not be loaded: ${err instanceof Error ? err.message : String(err)}`, "sdk-unavailable");
+        });
+    }
+    return cachedLive;
+}
 /** Import the SDK's node entry, installing the type-stripping loader first. Cached per process. */
 export function loadSdk(importer = realImport) {
     if (!cached) {
@@ -35,10 +50,28 @@ export function loadSdk(importer = realImport) {
     }
     return cached;
 }
+/** Events use the same supported dependency loader; capability markers are checked by the caller. */
+export function loadEventsSdk(importer = () => import("@catalyst-cloud/sdk/events")) {
+    if (!cachedEvents) {
+        cachedEvents = (async () => {
+            installTsDepsLoader();
+            try {
+                return await importer();
+            }
+            catch {
+                cachedEvents = null;
+                throw new CliError("the Catalyst Cloud event SDK could not be loaded; reinstall the skills bundle", "sdk-unavailable");
+            }
+        })();
+    }
+    return cachedEvents;
+}
 /** Test seam: forget the cached import. */
 export function resetSdkCache() {
     cached = null;
     cachedHttp = null;
+    cachedLive = null;
+    cachedEvents = null;
 }
 /** HTTP tenant methods live on the SDK's root entry, separate from replica/node exports. */
 export async function loadTenantSdk() {

package/dist/watch.js

@@ -9,7 +9,7 @@ import { loadContract } from "./contract.js";
 import { CliError, UsageError } from "./errors.js";
 import { apiClient } from "./transport.js";
 import { authStrategyFor, bearerFor } from "./oauth.js";
-import { loadSdk } from "./sdk.js";
+import { loadLiveSdk } from "./sdk.js";
 import { createLiveEventsClient } from "./watch/consumer.js";
 import { CursorFileError } from "./watch/cursor-file.js";
 const ROW_ISSUE_REFS = ["identifier", "linear_issue_identifier", "issue_identifier", "issue_id", "linear_issue_id"];
@@ -109,7 +109,7 @@ export function execReaction(cmd, env) {
     });
 }
 export async function runWatch(ctx, cfg, opts, deps = {}) {
-    const sdk = deps.sdk ?? (await loadSdk());
+    const sdk = deps.sdk ?? (await loadLiveSdk());
     const resolve = deps.resolver ?? apiIssueResolver(cfg, ctx);
     const react = opts.exec ? execReaction(opts.exec, ctx.env) : undefined;
     let handle;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.14.6",
+  "version": "0.14.7",
   "description": "Customer skill bundle for Catalyst Cloud, named from the executive's seat \u2014 get set up, see what is happening, see what needs you, run a project, unstick what is stuck \u2014 plus the catalyst CLI that reads through the Catalyst Cloud SDK, writes through the agent proxy, and connects your machine to your cloud account with one command. The skills directory is the roster; this line never counts it.",
   "license": "MIT",
   "type": "module",
@@ -46,7 +46,8 @@
     "skills:scan": "node scripts/scan-skills.mjs",
     "evals": "node scripts/run-evals.mjs",
     "paths:check": "node scripts/vendor-paths.mjs --check",
-    "prose:check": "node scripts/check-public-prose.mjs"
+    "prose:check": "node scripts/check-public-prose.mjs",
+    "settings:check": "node scripts/vendor-settings.mjs --check"
   },
   "dependencies": {
     "@catalyst-cloud/sdk": "^0.13.1",

package/skills/catalyst-github/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Catalyst's GitHub: show a ticket's pull request with its checks, reviews and review threads, say whether it is mergeable under this repository's policy, and explain what a PR accumulates as the ticket moves (the branch, the draft, the rewrite, the force-pushes, the labels, the queue). Use when someone asks "show me the PR", "what are the checks saying", "why hasn't it merged", "what does the queue need", "what does that label mean", or wants the branch and merge conventions Catalyst follows.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.14.7 — written in this repository for customer accounts -->
 
 # Catalyst's GitHub
 
@@ -15,7 +15,7 @@ You answer for the pull requests Catalyst opens and moves. The person asking wan
 - `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 query`, `contract` and, when fresh, `replica`; the first stderr line names the source, and your answer repeats it.
+Both read through `catalyst query` and `contract` from the cloud by default; the first stderr line names the source, and your answer repeats it.
 
 ## Load on demand
 

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

@@ -42,7 +42,7 @@ The mirrored PR detail carries checks, legacy commit statuses, review objects wi
 
 - checks: judged fully from the detail.
 - reviewer: reported as inconclusive unless the policy waives it. The script says whether the reviewer left review objects, but whether a clean-pass reaction followed, and whether those reviews stand at the current head or an earlier one, is not mirrored.
-- threads: read from the local replica's review-thread rows when the replica is fresh (resolved flag per thread); inconclusive otherwise, with the command that starts the replica. Thread ancestry against force-pushes is judged by the cloud, not here.
+- threads: inconclusive when cloud PR detail carries no thread count. The optional `--local-threads` reads local review-thread rows only after the replica proves it is caught up to a probed cloud head. Thread ancestry against force-pushes is judged by the cloud, not here.
 
 The exit code is 1 only for a proven-red leg or prerequisite. An inconclusive leg leaves exit 0 and a verdict that says "not proven mergeable from this read". The cloud's own evaluator, which holds the reaction and the ancestry, is the authority; a queue-ready label on the PR means it already said yes.
 

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

@@ -58,4 +58,4 @@ The ticket moves to Done when the real merge webhook arrives, keyed to the pull
 
 ## Reading a PR through this skill
 
-`node scripts/read-pr.mjs <ticket>` follows the ticket's own record to the pull requests that name it, picks the open one (else the merged one, else the newest), and prints the mirrored detail: state, draft and merged flags, branch and base, head commit, the linked ticket and its stage, GitHub's own mergeable state and auto-merge flag, every check with status and conclusion, legacy commit statuses, and every mirrored review with its state. `--all` lists every PR for the ticket; `--json` prints the raw document. The first stderr line names the source, a fresh replica or the API, and the answer should repeat it.
+`node scripts/read-pr.mjs <ticket>` follows the ticket's own record to the pull requests that name it, picks the open one (else the merged one, else the newest), and prints the mirrored detail: state, draft and merged flags, branch and base, head commit, the linked ticket and its stage, GitHub's own mergeable state and auto-merge flag, every check with status and conclusion, legacy commit statuses, and every mirrored review with its state. `--all` lists every PR for the ticket; `--json` prints the raw document. Reads use the cloud by default. Repeat the source from the first stderr line.