@catalyst-cloud/cli 0.9.5 → 0.13.0

package/dist/env/scan-workflow.js

@@ -0,0 +1,123 @@
+// scan-workflow.ts — names a GitHub Actions workflow declares or references, read with the real YAML
+// parser (`yaml`, D-2). A hand-written line scanner silently loses names written in flow style
+// (`env: { A: 1, B: 2 }`); `parseDocument` does not, and it hands back the exact file:line for every
+// key through `LineCounter`, plus the structural path (workflow env / a specific job) for free.
+import { LineCounter, isMap, isScalar, isSeq, parseDocument } from "yaml";
+const DEPLOY_JOB_ID_RE = /^(deploy|publish|release|cd)([-_].*)?$/i;
+const DEPLOY_COMMANDS = ["wrangler deploy", "wrangler versions upload", "npm publish", "pnpm publish", "bun publish", "gh release create", "flyctl deploy", "vercel deploy"];
+const SECRET_VAR_RE = /\$\{\{\s*(secrets|vars)\.([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+export function scanWorkflow(file, text) {
+    const lc = new LineCounter();
+    let doc;
+    try {
+        doc = parseDocument(text, { lineCounter: lc });
+    }
+    catch {
+        return { sightings: [], jobs: [] };
+    }
+    const lineOf = (offset) => lc.linePos(offset).line;
+    const root = doc.contents;
+    const sightings = [];
+    const jobs = [];
+    const jobRanges = [];
+    if (!isMap(root))
+        return { sightings, jobs };
+    const topEnv = root.get("env", true);
+    if (isMap(topEnv)) {
+        for (const pair of topEnv.items) {
+            if (!isScalar(pair.key))
+                continue;
+            const offset = pair.key.range?.[0] ?? 0;
+            sightings.push({
+                name: String(pair.key.value),
+                finding: { file, line: lineOf(offset), consumer: "workflow env", consumerKind: "workflow-env" },
+                localSource: ".env file or your shell",
+            });
+        }
+    }
+    const jobsNode = root.get("jobs", true);
+    if (isMap(jobsNode)) {
+        for (const jobPair of jobsNode.items) {
+            if (!isScalar(jobPair.key) || !isMap(jobPair.value))
+                continue;
+            const jobId = String(jobPair.key.value);
+            const jobMap = jobPair.value;
+            const jobKeyOffset = jobPair.key.range?.[0] ?? 0;
+            const jobRange = jobMap.range ?? [jobKeyOffset, jobKeyOffset, jobKeyOffset];
+            let deploy = jobMap.get("environment", true) !== undefined;
+            let why = deploy ? "has an environment:" : "";
+            if (!deploy && DEPLOY_JOB_ID_RE.test(jobId)) {
+                deploy = true;
+                why = "job id matches a deploy pattern";
+            }
+            const steps = jobMap.get("steps", true);
+            if (isSeq(steps)) {
+                for (const step of steps.items) {
+                    if (!isMap(step))
+                        continue;
+                    const run = step.get("run", true);
+                    if (isScalar(run) && typeof run.value === "string") {
+                        const cmd = DEPLOY_COMMANDS.find((c) => run.value.includes(c));
+                        if (cmd) {
+                            deploy = true;
+                            why = `a step runs ${cmd}`;
+                        }
+                    }
+                    const stepEnv = step.get("env", true);
+                    if (isMap(stepEnv)) {
+                        for (const pair of stepEnv.items) {
+                            if (!isScalar(pair.key))
+                                continue;
+                            const offset = pair.key.range?.[0] ?? 0;
+                            sightings.push({
+                                name: String(pair.key.value),
+                                finding: { file, line: lineOf(offset), consumer: `workflow job ${jobId}`, consumerKind: "workflow-job-env" },
+                                jobId,
+                                localSource: ".env file or your shell",
+                            });
+                        }
+                    }
+                }
+            }
+            const jobEnv = jobMap.get("env", true);
+            if (isMap(jobEnv)) {
+                for (const pair of jobEnv.items) {
+                    if (!isScalar(pair.key))
+                        continue;
+                    const offset = pair.key.range?.[0] ?? 0;
+                    sightings.push({
+                        name: String(pair.key.value),
+                        finding: { file, line: lineOf(offset), consumer: `workflow job ${jobId}`, consumerKind: "workflow-job-env" },
+                        jobId,
+                        localSource: ".env file or your shell",
+                    });
+                }
+            }
+            jobs.push({ id: jobId, file, line: lineOf(jobKeyOffset), deploy, why: why || "no deploy signal" });
+            jobRanges.push({ id: jobId, start: jobRange[0], end: jobRange[2] ?? jobRange[1], deploy });
+        }
+    }
+    // ${{ secrets.X }} / ${{ vars.X }} references, over the RAW TEXT rather than the parsed tree: GitHub
+    // Actions interpolates these anywhere, including inside a `run: |` block's shell text, and a plain
+    // shell assignment inside that same block (e.g. `NOT_A_NAME=1`) must NOT be mined as a name — the
+    // raw-text regex only ever matches the `${{ … }}` expression syntax, never bare shell.
+    SECRET_VAR_RE.lastIndex = 0;
+    let m;
+    while ((m = SECRET_VAR_RE.exec(text))) {
+        const name = m[2];
+        const offset = m.index;
+        const job = jobRanges.find((j) => offset >= j.start && offset < j.end);
+        sightings.push({
+            name,
+            finding: { file, line: lineOf(offset), consumer: job ? `workflow job ${job.id}` : "workflow", consumerKind: `${m[1]}-ref` },
+            jobId: job?.id,
+            jobDeploy: job?.deploy,
+            localSource: "CI secret",
+        });
+    }
+    for (const s of sightings) {
+        if (s.jobId !== undefined && s.jobDeploy === undefined)
+            s.jobDeploy = jobRanges.find((j) => j.id === s.jobId)?.deploy;
+    }
+    return { sightings, jobs };
+}

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/cli",
-  "version": "0.9.5",
+  "version": "0.13.0",
   "description": "Customer skill bundle for Catalyst Cloud, named from the executive's seat — get set up, see what is happening, see what needs you, run a project, unstick what is stuck — plus the catalyst CLI that reads through the Catalyst Cloud SDK, writes through the agent proxy, and connects your machine to your tenant with one command. The skills directory is the roster; this line never counts it.",
   "license": "MIT",
   "type": "module",
@@ -48,13 +48,13 @@
     "paths:check": "node scripts/vendor-paths.mjs --check"
   },
   "dependencies": {
-    "@catalyst-cloud/sdk": "^0.12.0"
+    "@catalyst-cloud/sdk": "^0.13.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/node": "^26.3.0",
     "@vitest/coverage-v8": "^4.1.11",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.11",
-    "yaml": "^2.9.0"
+    "vitest": "^4.1.11"
   }
 }

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-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.5 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.0 — written in this repository for customer tenants -->
 
 # Catalyst's GitHub
 

package/skills/catalyst-linear/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 disable-model-invocation: true
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.5 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.0 — written in this repository for customer tenants -->
 
 # Catalyst Linear
 

package/skills/catalyst-onboard/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 disable-model-invocation: true
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.5 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.0 — written in this repository for customer tenants -->
 
 # Onboard me
 

package/skills/catalyst-setup/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Am I set up? Machine readiness (Node, the tenant connection, the cached contract, the CLI path, the skills, the SDK, the optional replica) plus tenant readiness from the contract's per-team checks, in one verdict: what passes, what is blocked, what is merely waiting, and who can click what. Use when someone asks "am I set up", "what is missing", "why does nothing happen", "is the replica running", or right after connecting a new machine. Reports; never repairs.
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.5 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.0 — written in this repository for customer tenants -->
 
 # Am I set up?
 

package/skills/connect-me/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.5 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.0 — written in this repository for customer tenants -->
 
 # Connect me
 
@@ -34,7 +34,7 @@ CATALYST_CLOUD_TOKEN=<your-personal-key> catalyst-skills login
 ## What you do
 
 1. Prefer keyless: run `catalyst-skills login` with no key and have the person approve the code in their browser (or from a phone). Nothing to mint, nothing to paste, nothing to keep out of the transcript. A **personal key** is the fallback for a script or unattended shell — they mint it at Settings → API keys (every active member can; no admin is needed) and hand it to the login command via `CATALYST_CLOUD_TOKEN`; it is shown once, so never put it in a file, a ticket, or this conversation beyond that one command. Either way, do not ask an admin for the tenant's **account key** (`ctc_acct_`, Settings → Account keys): that is a host credential — runners, daemons, the host replica — and a person connected with it has no name on anything their agent writes, and "what needs me" cannot mean them. If they connect with one anyway, login says so on stderr and still works.
-2. Run the login command. Its output names the tenant (`Connected to <name> (<slug>)`), the person (`Connected as <label> (<role>)`), the config path, and the cached contract version. If the person line says their Linear identity is not matched yet, tell them: an admin matches it in Settings → Members, and until then "what needs me" shows everyone's asks.
+2. Run the login command. Its output names the tenant (`Connected to <name> (<slug>)`), the person (`Connected as <label> (<role>)`), the config path, and the cached contract version. If the person line says their Linear identity is not matched yet, tell them: an admin matches it in Settings → Members, and until then "what needs me" shows everyone's asks — connecting Linear personally does not match the identity.
 3. Verify with `node scripts/verify-connection.mjs`: one line each for the tenant, the contract version, and the replica; exit 1 when the machine is not connected.
 4. Run `catalyst-skills ready` and read the verdict to them.
 5. Do not offer the replica. It is optional and off by default for large projects while the snapshot path is made safe, and every read works through the API without it. Start it only if the person asks for local SQL, and then load `references/keeping-the-replica-running.md`.
@@ -54,7 +54,7 @@ Every skill session opens with these, in this order, before doing anything else:
 | when | read |
 | -- | -- |
 | the person wants the replica writer to survive a reboot, or asks what it stores and whether anything needs cleaning | `references/keeping-the-replica-running.md` |
-| the full readiness vector and what each check means | the `catalyst-setup` skill |
+| the full readiness vector — the check, its severity, and who can click what | the `catalyst-setup` skill |
 
 ## Rules
 

package/skills/how-catalyst-works/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: how-catalyst-works
 description: >-
-  How Catalyst Cloud runs a ticket on the customer's own tenant, as facts an agent loads on demand: the eight-phase ladder and what each phase produces, the eleven board slots and this team's live stage map, what happens when a phase fails (retry, backoff, Remediate, park), how the queue is ordered and routed and every reason a ticket is excluded, and the coding-account model. Use when a person asks "how does this work?", "why did it do that?", "why is this stuck?", "what runs next?" or "how does it prioritise?". Read-only; its scripts explain one ticket's eligibility in plain English, show what is running and queued, and print the tenant's stage map and thresholds straight from the contract.
+  How Catalyst Cloud runs a ticket on the customer's own tenant, as facts an agent loads on demand: the eight-phase ladder and what each phase produces, the eleven board slots and this team's live stage map, what happens when a phase fails (retry, backoff, Remediate, park), how the queue is ordered and routed and every reason a ticket is excluded, the coding-account model, and which settings screen governs which rule. Use when a person asks "how does this work?", "why did it do that?", "why is this stuck?", "what runs next?", "how does it prioritise?" or "what does this setting do, where is it set?". Read-only; its scripts explain one ticket's eligibility in plain English, show what is running and queued, and print the tenant's stage map and thresholds straight from the contract.
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.5 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.0 — written in this repository for customer tenants -->
 
 # How Catalyst works
 
@@ -32,10 +32,12 @@ Exit codes: 0 answered, 1 not found or a usage error, 2 this machine is not conn
 | a phase FAILED, a card went to Remediate, a ticket is parked or on hold | `references/when-a-phase-fails.md` |
 | "what runs next, why not this one, what does this exclusion reason mean?", "why does nothing start while nothing runs?" (the WIP limit) | `references/what-runs-next.md` |
 | "why is nothing running", walls, quarantine, which provider ran a phase | `references/coding-accounts.md` |
+| "what does this setting do, where is it set, who can change it?" | `references/settings-and-where-they-live.md` |
 
 ## Rules
 
 - **Print, never recall.** A stage name, label, threshold or route in your answer must have come from a script's output in this session.
+- **A setting has a page.** Name the screen, its route and the rule from `references/settings-and-where-they-live.md`; never answer a settings question from memory, and never invent a route.
 - **A reason is a layer.** Translate an exclusion reason through `references/what-runs-next.md`; name what releases it and who can do that (a clock, a comment, a push, an operator).
 - **Unknown is not absent.** An `unknown` verdict from the explainer means the cloud could not look; report it as inconclusive.
 - **System causes are one alert.** A provider outage, the runner image breaker or a paused repository holds many tickets for one reason; never escalate it ticket by ticket.

package/skills/how-catalyst-works/references/settings-and-where-they-live.md

@@ -0,0 +1,20 @@
+# Settings and where they live
+
+This reference restates rules that do not vary per tenant: what a setting does, the screen it lives on, and who can change it. Every live value — whether a connection is up, which repositories are registered, the current merge policy — comes from the contract or a script; every route below is prefixed with `<their cloud>` because the host is the tenant's own, never a literal you invent.
+
+| what | where it is set | the rule | who can set it |
+| -- | -- | -- | -- |
+| **Connecting Linear** | `<their cloud>/settings/connections` | Needs an admin or owner browser session; the tenant comes from that session, never from a URL parameter. | owner or admin |
+| **One workspace, one account** | `<their cloud>/settings/connections` | A Linear workspace binds to exactly one account and an account to exactly one workspace; a second tenant for the same workspace is refused and stores nothing. That is a decision to raise, not a retry. | owner or admin |
+| **Installing the GitHub App** | `<their cloud>/settings/connections`, but the admin's own personal GitHub grant comes first at `<their cloud>/settings/profile` | A refusal naming a missing GitHub identity, or an installation that is not yours, means "grant your personal GitHub first", never "the App is broken". | owner or admin |
+| **Uninstalling is safe either way** | `<their cloud>/settings/connections` | Removing the App on GitHub self-heals the registry; unlinking in Catalyst uninstalls upstream best-effort. Neither needs a support ticket. | owner or admin |
+| **One team, one repository** | `<their cloud>/settings/repositories` | One Linear team maps to at most one repository per account, and one GitHub repository to at most one, case-insensitively. | owner or admin |
+| **Neither half can be re-pointed** | `<their cloud>/settings/repositories` | A repository is exactly one team plus one GitHub repo; the only editable field is its name. A monorepo across two teams, or one team across two repos, cannot be modelled today — do not promise it. | owner or admin |
+| **An archived repository still holds both keys** | `<their cloud>/settings/repositories` | Re-registering the same team-plus-repo pair is refused until the archived entry is restored. | owner or admin |
+| **Merge policy** | `<their cloud>/settings/repositories/$repoId/merging` | The effective policy and where it came from are served on the contract's `merge` block; this is the page that changes it (`catalyst-github`'s mergeability read never sets it). | owner or admin |
+| **Reviewers** | `<their cloud>/settings/repositories/$repoId/code-reviews` | "Post review requests as" names one connected member; a member cannot volunteer or refuse. A strict merge policy with no reviewer configured never earns the merge label — configure a reviewer, or change the policy on the merging page. | owner or admin |
+| **The merge queue is assumed, and this bundle cannot see it** | (no settings page; the repository's own merge automation — a Mergify configuration, GitHub's native merge queue, or whatever else that repository runs) | The merge phase never merges: its one write is the ready label. Without a queue consuming that label the label is still the cloud's attestation, and the merge itself is whatever the repository's own setup does with it. Nothing here detects or repairs that, and nothing here knows which queue a tenant runs; say that by name rather than guessing, and never name a vendor the tenant has not named first. | whoever administers the GitHub repository |
+| **The runner cap** | `<their cloud>/settings/repositories` | Default 20 running phases per repository; a paused repository resolves to zero without losing the stored value. The tenant page is display-only — lowering it is an operator action. See `references/what-runs-next.md`'s concurrency section. | operator (the page only displays it) |
+| **Secrets are write-only; environment variables are readable** | `<their cloud>/settings/secrets` and `<their cloud>/settings/environment`, plus the per-repository sections under `<their cloud>/settings/repositories` | A name is a secret **or** an environment variable, never both; a repository-scoped value wins over a tenant-scoped one; an environment variable may reference a vault secret by name, expanded only when the container is built. | owner or admin |
+| **"My secrets are not in the container"** | `<their cloud>/settings/repositories` (the team the repository is registered under) | When a repository was registered without naming its team, nothing reaches a runner, and the failure is silent — the symptom is a phase whose build cannot find its environment. The fix is an admin or operator action, not a retry; raise it as an ask. Name the symptom and the page, never the registry table behind it. | owner or admin |
+| **Routing has no write route and no UI** | none — there is no settings page for this | Stage defaults are global and the per-tenant precedence table is empty, so an empty precedence always resolves to the default provider. A Codex-first pipeline is not something to promise today. See `references/coding-accounts.md` and `references/what-runs-next.md`'s routing decision. | nobody — not configurable yet |

package/skills/how-catalyst-works/references/what-runs-next.md

@@ -73,7 +73,14 @@ No survivor is `no_eligible_account_slot` when any candidate was skipped on capa
 | `routing_unavailable` | claimed then refused at kickoff: no route, no eligible slot, or the provider is unavailable; the detail names which |
 | `repo_paused` | an operator paused the repository |
 | `wip_limit` | the project is at its WIP limit (see above): its tickets in progress are waiting, and this new start waits until one of them finishes |
-| `remediate_parked` | the remediate phase is parked, so the failing phase has nowhere to be repaired |
+| `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 a spent repair-round cap; the person 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; that person closes or merges the PR themselves, and no release command clears it |
+| `review_not_converging` | review and repair kept finding new problems without converging |
+| `round_threshold` | the ticket spent its lifetime repair budget |
+| `claim_storm` | claimed too many times in the last hour; it waits the hour out, and there is nothing to release |
+| `repo_at_capacity` | the repository's runner seats are all in use; it starts when one frees |
 
 ## The unknowns (the evaluator fails closed)
 

package/skills/run-this-project/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.5 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.0 — written in this repository for customer tenants -->
 
 # Run this project
 

package/skills/unstick/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.5 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.0 — written in this repository for customer tenants -->
 
 # Unstick
 

package/skills/what-needs-me/SKILL.md

@@ -5,7 +5,7 @@ description: >-
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.5 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.0 — written in this repository for customer tenants -->
 
 # What needs me
 

package/skills/what-needs-me/references/reading-the-inbox.md

@@ -19,6 +19,10 @@ So an ask that holds nothing is real, but the person may never see it in their o
 
 `catalyst-skills ask list` reads every page of the tenant's issues, not a windowed sample, so an empty list means nothing is assigned to you rather than that the read stopped early. It reads the open tickets carrying the team's ask label (by the label ids and prefix the contract serves), follows each one's blocking relations to the tickets it holds, drops held tickets that are already terminal, and scores the rest by priority weight: urgent 4, high 3, medium 2, low 1, none 1. It filters to **the connected person** by default: `login` recorded who they are and their Linear user id, and the list keeps only asks assigned to that id. `--anyone` lists the whole tenant. The JSON answer carries a `scope` — `mine` (with the label and Linear id), `anyone`, `unmatched` (the person's Linear identity is not matched yet: an admin does that in Settings → Members, and until then the whole list is shown with a stderr line saying so), or `no-person` (the machine is connected with the tenant's account key, which names nobody: the whole list, with a line saying to log in with a personal key). Read the scope before presenting the list, and say which you got: "what needs me" is the `mine` list, "what needs anyone" is `--anyone`, and an empty `mine` list names the wider count so it never reads as "nothing needs anyone".
 
+## The identity is not the same as the personal Linear grant
+
+Two different stored facts can disagree, and when asks are not reaching someone this is the first thing to check, before the grant. The **identity** is who you are in Linear: resolved automatically by an email match, or picked by an admin at Settings → Members when it is not. The **personal Linear grant** is proven by connecting Linear yourself — a person action, not an admin one. Connecting Linear personally does **not** set the identity; the two are separate, and the identity is checked first, then the grant. An identity that resolved automatically cannot be re-pointed by the member themselves — that needs an operator; a manual pick by an admin is refused if another member already claims that Linear user. Everything that notifies or assigns a human needs a resolved identity: with no identity there is no ask and no push, and nothing is assigned to that person — even for someone who has connected Linear themselves. Do not report that as an empty queue. `what needs me` does not go quiet in that state: the scope comes back `unmatched`, the whole tenant's open asks are listed, and a line says the identity is not matched yet (*What the script reads*, above). The honest answer is "nothing is assigned to you yet, so this is everyone's list, not yours — an admin matches your identity at Settings → Members".
+
 ## Presenting the queue
 
 - Ranked by score, highest first. Never by age, never by identifier. An ask that holds a project outranks one that holds a chore, whatever their dates.