@catalyst-cloud/cli 0.14.6 → 0.14.8

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/repository-id.js

@@ -0,0 +1,5 @@
+/** Repository row IDs are opaque cloud identifiers, including tenant-prefixed legacy names.
+ * Syntax validation never establishes tenant ownership; callers must join fresh ACL and contract reads. */
+export function isRepositoryId(value) {
+    return typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/.test(value);
+}

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.8",
   "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.8 — 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
 
@@ -23,6 +23,8 @@ Both read through `catalyst query`, `contract` and, when fresh, `replica`; the f
 | -- | -- |
 | the person asks what Catalyst did to the branch or PR, why the title changed, why history was rewritten, what a label means, or what happens on merge | `references/what-a-pr-accumulates.md` |
 | the person asks why a PR has not merged, what the queue needs, what a clean review pass looks like, or what a policy requires | `references/is-it-mergeable.md` |
+| which command answers a PR question from the cloud, and what the cloud detail cannot see | `references/reading-from-the-cloud.md` |
+| local SQL or `--local-threads`, only when `catalyst replica status --json` reports `configured: true` | `references/local-replica.md` |
 
 ## Rules
 

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/local-replica.md

@@ -0,0 +1,78 @@
+# Reading pull requests from the local replica (opt-in)
+
+Load this only when `catalyst replica status --json` reports `configured: true`. On any other machine, read from the cloud (`references/reading-from-the-cloud.md`) and do not mention the replica.
+
+The replica is an on-machine SQLite copy of the account. It exists only when the person opted in to local sync. It adds ad hoc SQL over mirrored pull requests and one leg the cloud PR detail lacks: review-thread rows. It is never required.
+
+## Check it is caught up first
+
+Run `catalyst replica status --probe --json` before every local read. Read locally only when `verdict` is `fresh` and `cursor` equals `head`. `stale` or `absent` with `configured: true` means the person opted in and the writer is down. Answer from the cloud and say the local copy is behind.
+
+Quote the cursor with any local answer, for example "from the local replica at cursor 4810".
+
+## Threads: the one leg only the replica adds
+
+**Zero thread rows does not mean zero open threads.** The thread table is filled only by resolve and unresolve events, and nothing seeds it from GitHub. A thread opened and never touched leaves no row. So zero rows can mean every thread is still open. A local "all resolved" answers only "of the threads seen resolving, which are resolved now". It never replaces the cloud's merge evaluator, which also judges a resolution against force-pushes.
+
+`node scripts/is-it-mergeable.mjs <ticket> --local-threads` reads the thread leg from the replica. It does so only after a probe proves the replica is caught up with the cloud head. Without the flag, the thread leg is inconclusive and the cloud's evaluator decides.
+
+The query the script runs, for one pull request:
+
+```sql
+select resolved, count(*) as n from pr_review_threads
+where repo_id = 'acme/widgets' and pr_number = 42
+group by resolved
+```
+
+`resolved` is 1 for resolved, 0 for unresolved, and null when no flag was mirrored.
+
+## Running SQL yourself
+
+`catalyst replica sql "<one SELECT>" --json` runs one read-only `SELECT` and prints rows. `catalyst replica schema <table>` prints a table's columns; read them before querying a table this page does not cover. Timestamps are milliseconds since the epoch.
+
+| table | one row is | key |
+| -- | -- | -- |
+| `pull_requests` | a pull request: `state`, `draft`, `merged`, `merged_at`, `head_sha`, `head_ref`, `base_ref`, `mergeable`, `mergeable_state`, `auto_merge`, `linear_issue_identifier` | `repo_id`, `number`; also `node_id` |
+| `check_runs` | one check at one commit: `name`, `status`, `conclusion` | `repo_id`, `head_sha` |
+| `commit_statuses` | a legacy commit status: `context`, `state` | `repo_id`, `sha` |
+| `reviews` | a submitted review: `user_id`, `state`, `submitted_at` | `repo_id`, `pr_number` |
+| `pr_review_threads` | a review thread seen resolving: `resolved`, `resolved_at` | `repo_id`, `pr_number` |
+| `pr_review_comments`, `pr_conversation_comments` | an inline comment, and a PR conversation comment | `repo_id`, `pr_number` |
+
+Replace `acme/widgets`, `42` and `ENG-123` with real values.
+
+Every pull request that names a ticket:
+
+```sql
+select repo_id, number, state, draft, merged, head_sha, mergeable_state
+from pull_requests where linear_issue_identifier = 'ENG-123'
+```
+
+The checks at a pull request's current head:
+
+```sql
+select c.name, c.status, c.conclusion
+from check_runs c join pull_requests p
+  on p.repo_id = c.repo_id and p.head_sha = c.head_sha
+where p.repo_id = 'acme/widgets' and p.number = 42
+order by c.name
+```
+
+The reviews on a pull request, newest first:
+
+```sql
+select user_id, state, submitted_at from reviews
+where repo_id = 'acme/widgets' and pr_number = 42
+order by submitted_at desc
+```
+
+Open pull requests that GitHub reports in conflict:
+
+```sql
+select repo_id, number, linear_issue_identifier from pull_requests
+where state = 'open' and mergeable_state = 'dirty'
+```
+
+## What the replica does not answer
+
+Reactions, PR labels and the commit each review was submitted against are not mirrored anywhere a read can reach. The cloud's evaluator holds them. `references/is-it-mergeable.md` explains what that leaves inconclusive.

package/skills/catalyst-github/references/reading-from-the-cloud.md

@@ -0,0 +1,24 @@
+# Reading pull request facts from the cloud
+
+Cloud reads are the default on every machine. They need no local writer and no local database. Every command below reads the cloud through the `catalyst` CLI.
+
+| question | command |
+| -- | -- |
+| Which pull requests name this ticket? | `catalyst query pulls --ticket <KEY-123>` |
+| What state is the PR in: draft, merged, conflict, auto-merge? | `node scripts/read-pr.mjs <KEY-123>` |
+| Which checks are red or still running at the head? | `node scripts/read-pr.mjs <KEY-123>` |
+| Is it mergeable under this repository's policy? | `node scripts/is-it-mergeable.mjs <KEY-123>`, which also reads `catalyst contract --path merge` |
+| Which stage is the linked ticket in? | `catalyst query issue <KEY-123>` |
+| What did the last pr or merge phase do? | `catalyst history <KEY-123>` |
+
+The first stderr line names the source: `source: api (...)`. Quote it when freshness matters.
+
+## What the cloud PR detail does not carry
+
+The detail has no review-thread count. So the thread leg of `is-it-mergeable.mjs` is inconclusive from a cloud read, and the cloud's own merge evaluator decides. A queue-ready label on the PR means it already said yes. Reactions, PR labels and the commit each review was submitted against are not in the detail either.
+
+A smaller ticket read is coming: the cloud will answer with only the status fields and the linked pull requests. No CLI flag selects it yet, so read the full record.
+
+## The local replica
+
+Only on a machine where `catalyst replica status --json` reports `configured: true`, `references/local-replica.md` adds local SQL and the opt-in `--local-threads` read. Everywhere else, these cloud reads are the whole answer.

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.