@catalyst-cloud/cli 0.13.0 → 0.14.0

package/skills/connect-me/scripts/lib/cli.mjs

@@ -1,185 +0,0 @@
-#!/usr/bin/env node
-// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: by spawning the catalyst-skills
-// CLI. The CLI holds the SDK and the key; this file holds neither. It reads
-// ~/.config/catalyst-cloud/customer.json (under CATALYST_SKILLS_HOME when set, else HOME) for the
-// CLI path that login recorded and falls back to `npx @catalyst-cloud/catalyst-skills`.
-//
-// Exit codes every script built on this file shares: 2 = this machine is not connected, 1 = the
-// script's own check failed, 0 = fine.
-import { spawn } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
-
-export const PACKAGE_NAME = "@catalyst-cloud/catalyst-skills";
-export const NOT_CONFIGURED_EXIT = 2;
-export const CHECK_FAILED_EXIT = 1;
-
-export function homeDir() {
-  return process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? process.env.USERPROFILE ?? "/";
-}
-
-export function configDir() {
-  return join(homeDir(), ".config", "catalyst-cloud");
-}
-
-export function configPath() {
-  return join(configDir(), "customer.json");
-}
-
-/** The stored config, or null when the file is absent or unreadable. Never throws. */
-export function loadCustomerConfig() {
-  const path = configPath();
-  if (!existsSync(path)) return null;
-  try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
-    if (!hasCredential(parsed) || typeof parsed.account !== "string") return null;
-    return parsed;
-  } catch {
-    return null;
-  }
-}
-
-/** Print the one not-connected line and exit 2. */
-export function requireConfigured() {
-  const cfg = loadCustomerConfig();
-  if (cfg) return cfg;
-  console.error(`not connected: ${configPath()} is missing or unreadable — run: ${CONNECT_COMMAND}`);
-  process.exit(NOT_CONFIGURED_EXIT);
-}
-
-/** The command and argument prefix that reaches the CLI on this machine. */
-export function cliCommand(cfg = loadCustomerConfig()) {
-  if (cfg && typeof cfg.cliPath === "string" && existsSync(cfg.cliPath)) {
-    return { command: process.execPath, prefix: [cfg.cliPath], via: `node ${cfg.cliPath}` };
-  }
-  const npx = process.platform === "win32" ? "npx.cmd" : "npx";
-  return { command: npx, prefix: [PACKAGE_NAME], via: `npx ${PACKAGE_NAME}` };
-}
-
-/**
- * Run one CLI verb and capture its output. Resolves `{code, stdout, stderr, notConfigured}`;
- * `notConfigured` is true when the CLI itself said the machine is not connected.
- */
-export function runCli(args, { stdin } = {}) {
-  const { command, prefix } = cliCommand();
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, [...prefix, ...args], {
-      stdio: [stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
-      env: process.env,
-      shell: process.platform === "win32",
-    });
-    let stdout = "";
-    let stderr = "";
-    child.stdout.on("data", (d) => (stdout += String(d)));
-    child.stderr.on("data", (d) => (stderr += String(d)));
-    child.on("error", reject);
-    child.on("close", (code) => {
-      resolve({ code: code ?? 1, stdout, stderr, notConfigured: /not (joined|connected)/i.test(stderr) || /not (joined|connected)/i.test(stdout) });
-    });
-    if (stdin !== undefined) child.stdin.end(stdin);
-  });
-}
-
-/**
- * Run one CLI verb with the terminal attached, so a long-running verb such as `watch` streams
- * straight through. Resolves with the exit code; SIGINT and SIGTERM are forwarded to the child.
- */
-export function execCli(args) {
-  const { command, prefix } = cliCommand();
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, [...prefix, ...args], { stdio: "inherit", env: process.env, shell: process.platform === "win32" });
-    const forward = (sig) => () => {
-      try {
-        child.kill(sig);
-      } catch {
-        // already gone
-      }
-    };
-    const onInt = forward("SIGINT");
-    const onTerm = forward("SIGTERM");
-    process.on("SIGINT", onInt);
-    process.on("SIGTERM", onTerm);
-    child.on("error", reject);
-    child.on("close", (code) => {
-      process.off("SIGINT", onInt);
-      process.off("SIGTERM", onTerm);
-      resolve(code ?? 1);
-    });
-  });
-}
-
-/** Parse the CLI's --json output; a parse failure names the first line of what came back. */
-export function parseJson(stdout) {
-  try {
-    return JSON.parse(stdout);
-  } catch {
-    throw new Error(`the CLI did not answer with JSON: ${stdout.split("\n")[0] ?? "(empty)"}`);
-  }
-}
-
-/** Exit 2 with the CLI's own not-connected line when a call reports it; otherwise return the result. */
-export function guard(result) {
-  if (result.notConfigured) {
-    process.stderr.write(result.stderr || result.stdout);
-    process.exit(NOT_CONFIGURED_EXIT);
-  }
-  return result;
-}
-
-/** A tiny flag parser: `--name value`, `--name=value`, `--flag`, repeatable names collected as arrays. */
-export function parseFlags(argv, { values = [], repeat = [], booleans = [] } = {}) {
-  const flags = {};
-  const positionals = [];
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--") {
-      positionals.push(...argv.slice(i + 1));
-      break;
-    }
-    if (!a.startsWith("--")) {
-      positionals.push(a);
-      continue;
-    }
-    let name = a.slice(2);
-    let value;
-    const eq = name.indexOf("=");
-    if (eq !== -1) {
-      value = name.slice(eq + 1);
-      name = name.slice(0, eq);
-    }
-    if (booleans.includes(name)) {
-      flags[name] = true;
-      continue;
-    }
-    if (!values.includes(name) && !repeat.includes(name)) {
-      console.error(`unknown option: --${name} (try --help)`);
-      process.exit(CHECK_FAILED_EXIT);
-    }
-    if (value === undefined) {
-      value = argv[++i];
-      if (value === undefined) {
-        console.error(`--${name} needs a value`);
-        process.exit(CHECK_FAILED_EXIT);
-      }
-    }
-    if (repeat.includes(name)) flags[name] = [...(flags[name] ?? []), value];
-    else flags[name] = value;
-  }
-  return { flags, positionals };
-}
-
-export function wantsHelp(argv) {
-  return argv.includes("--help") || argv.includes("-h");
-}
-
-const HELP = `lib/cli.mjs — shared helper; not a command.
-
-Resolves the catalyst-skills CLI (the path login recorded in ${configPath()}, else npx ${PACKAGE_NAME})
-and runs one verb for the script that imports it. Run any sibling script with --help instead.`;
-
-if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
-  console.log(HELP);
-  process.exit(0);
-}

package/skills/connect-me/scripts/lib/credential.mjs

@@ -1,29 +0,0 @@
-#!/usr/bin/env node
-// lib/credential.mjs — is this machine connected? The ONE place a skill script decides it, vendored
-// byte-identical into every skill's scripts/lib/ from skill-lib/credential.mjs at the package root
-// (`npm run skill-lib:sync`; a test fails on any drift). Skills install one directory at a time, so
-// each carries its own copy. This file is a library — run a sibling script with --help for usage.
-//
-// customer.json carries exactly one credential: a personal key (`key`), or the keyless login's
-// session (`auth`, the recommended rail). A script never reads either for its value: it spawns the
-// catalyst-skills CLI, which authenticates with whichever is present and refreshes a login's token
-// itself. A new credential kind lands here, once.
-
-/** The command that connects this machine, as every not-connected line names it. */
-export const CONNECT_COMMAND =
-  "npx @catalyst-cloud/catalyst-skills login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login)";
-
-/** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
-export function hasCredential(cfg) {
-  if (cfg === null || typeof cfg !== "object") return false;
-  const key = cfg["key"];
-  if (typeof key === "string" && key !== "") return true;
-  const login = cfg["auth"];
-  return (
-    login !== null &&
-    typeof login === "object" &&
-    login["kind"] === "oauth" &&
-    typeof login["refreshToken"] === "string" &&
-    login["refreshToken"] !== ""
-  );
-}

package/skills/connect-me/scripts/verify-connection.mjs

@@ -1,68 +0,0 @@
-#!/usr/bin/env node
-// verify-connection.mjs — did the connect step land? One line each for the tenant, the contract version and the
-// replica, from the CLI's own verbs. The machine is connected when `status` names a tenant.
-import { CHECK_FAILED_EXIT, cliCommand, loadCustomerConfig, parseFlags, runCli, wantsHelp } from "./lib/cli.mjs";
-
-const HELP = `Usage: node scripts/verify-connection.mjs [--json]
-
-Runs catalyst-skills status, contract --path contractVersion, and replica status, and prints one
-line for each: the tenant this machine is connected to, the cached contract version, and the replica
-verdict. Nothing is written.
-
-Options:
-  --json   one JSON document instead of three lines
-  --help   this text
-
-Exit codes: 1 when status reports the machine is not connected (or the CLI could not be run);
-0 otherwise, whatever the replica verdict is, because the replica is optional.`;
-
-const argv = process.argv.slice(2);
-if (wantsHelp(argv)) {
-  console.log(HELP);
-  process.exit(0);
-}
-const { flags, positionals } = parseFlags(argv, { booleans: ["json"] });
-if (positionals.length > 0) {
-  console.error(`unexpected argument: ${positionals[0]} (see --help)`);
-  process.exit(CHECK_FAILED_EXIT);
-}
-
-const cfg = loadCustomerConfig();
-const { via } = cliCommand(cfg);
-const out = { cli: via, connected: false, tenant: null, contractVersion: null, replica: null };
-
-let status;
-try {
-  status = await runCli(["status"]);
-} catch (err) {
-  console.error(`could not run the CLI (${via}): ${err instanceof Error ? err.message : String(err)}`);
-  process.exit(CHECK_FAILED_EXIT);
-}
-const tenantLine = status.stdout.split("\n").find((l) => l.startsWith("Tenant:"));
-out.connected = status.code === 0 && Boolean(tenantLine) && !status.notConfigured;
-out.tenant = tenantLine ? tenantLine.slice("Tenant:".length).trim() : null;
-
-if (out.connected) {
-  const contract = await runCli(["contract", "--path", "contractVersion"]);
-  out.contractVersion = contract.code === 0 ? contract.stdout.trim() : null;
-  out.contractError = contract.code === 0 ? undefined : (contract.stderr || contract.stdout).trim().split("\n").at(-1);
-  const replica = await runCli(["replica", "status", "--json"]);
-  try {
-    const parsed = JSON.parse(replica.stdout);
-    out.replica = { verdict: parsed.verdict, exitCode: replica.code, cursor: parsed.cursor ?? null, reasons: parsed.reasons ?? [] };
-  } catch {
-    out.replica = { verdict: "unknown", exitCode: replica.code, line: (replica.stdout || replica.stderr).trim() };
-  }
-}
-
-if (flags.json) {
-  console.log(JSON.stringify(out));
-} else if (!out.connected) {
-  console.log(`not connected (${via}): ${(status.stdout || status.stderr).trim().split("\n")[0] ?? "status printed nothing"}`);
-} else {
-  console.log(`tenant: ${out.tenant}`);
-  console.log(out.contractVersion ? `contract: version ${out.contractVersion} cached` : `contract: not cached (${out.contractError ?? "unknown reason"}) — run: catalyst-skills contract --refresh`);
-  const r = out.replica;
-  console.log(`replica: ${r.verdict}${r.cursor !== null && r.cursor !== undefined ? ` (cursor ${r.cursor})` : ""}${r.reasons && r.reasons.length ? ` — ${r.reasons.join("; ")}` : ""}${r.verdict === "absent" ? " — optional; start it with: catalyst-skills replica start --detach" : ""}`);
-}
-process.exit(out.connected ? 0 : CHECK_FAILED_EXIT);

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

@@ -1,45 +0,0 @@
----
-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, 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.13.0 — written in this repository for customer tenants -->
-
-# How Catalyst works
-
-You explain the machine. A person asks why Catalyst did something, what it will do next, or how it decides; you answer from the tenant's live contract and eligibility explainer, and from the invariants in the references below. You never guess a stage name, a label, a threshold or a route: the scripts print the live values.
-
-Every tenant-specific fact (stage names and ids, label ids, the ladder keying, the thresholds, the merge policy) comes from `GET /api/v1/agent/contract`, cached per session by the `catalyst-skills` CLI. The references restate only what does not vary per tenant.
-
-## Run first
-
-Run each with `--help` before reading anything else; the scripts are black boxes, not reading material.
-
-- `node scripts/explain-ticket.mjs <ticket>` — why one ticket is or is not about to run, as one paragraph plus the raw eligibility row.
-- `node scripts/whats-running.mjs [--queue] [--accounts] [--team <key>]` — fleet activity, the agent roster and lease attributions; with `--queue` the dispatch order; with `--accounts` the coding-account line.
-- `node scripts/show-my-map.mjs [--team <key>]` — this tenant's slot-to-stage map, ladder and live thresholds.
-
-Exit codes: 0 answered, 1 not found or a usage error, 2 this machine is not connected or the cloud refused (the one line printed says which; connect first if it names the login).
-
-## Load on demand
-
-| when | read |
-| -- | -- |
-| "what is Catalyst Cloud?", "what changes for me?" | `references/what-catalyst-is.md` |
-| "what are the phases, what does each produce, when is a ticket Done?" | `references/the-ladder.md` |
-| "which column is which, why does nothing dispatch, what is a slot?" | `references/stages-and-mapping.md` |
-| 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.
-- **Say what a key cannot see.** A few PR facts are not mirrored (labels, the reviewer's reaction) and a park is released only by an operator; the scripts say so and name the settings page. Do not fill the gap with a guess.
-- **Depth lives elsewhere.** What a ticket accumulates in Linear is `catalyst-linear`; what a PR accumulates and whether it is mergeable is `catalyst-github`; raising a decision is `what-needs-me`.

package/skills/how-catalyst-works/agents/openai.yaml

@@ -1,6 +0,0 @@
-interface:
-  display_name: "How Catalyst Works"
-  short_description: "Explain how Catalyst Cloud runs a ticket: the ladder, your stage map, failures, what runs next, coding accounts"
-  default_prompt: "Use $how-catalyst-works to explain why Catalyst did that, or what it will run next."
-policy:
-  allow_implicit_invocation: true

package/skills/how-catalyst-works/agents/portability.yaml

@@ -1,4 +0,0 @@
-identity: { pack: catalyst-cloud-skills, skill: how-catalyst-works }
-effects: []
-invocation: implicit
-exposure: [catalog]

package/skills/how-catalyst-works/references/coding-accounts.md

@@ -1,51 +0,0 @@
-# Coding accounts: slots, windows, walls, and what a key cannot read yet
-
-This reference restates the model, which does not vary per tenant. Your tenant's actual accounts — provider, harness, declared and observed state, usage windows, walls, quarantine — are readable with your key: `node scripts/whats-running.mjs --accounts` prints the live rows (`catalyst-skills accounts`). No credential or email ever rides in that read; the settings page (`/settings/coding-accounts`) is where an admin enrols, pauses or removes one.
-
-## What a slot is
-
-A slot is one enrolled coding-account credential: a subscription or token that runs phases. A tenant may enrol several accounts of the same provider under the same email, because identity is the credential, not the email; the email is a display field. A revoked slot leaves the roster.
-
-## Providers and harnesses
-
-| Provider | Harness | Credential |
-| -- | -- | -- |
-| Claude | the Claude CLI | its own subscription |
-| Codex | Codex | its own subscription |
-| GLM | the Claude CLI | its own token |
-| Qwen | the Claude CLI | its own token |
-| GLM via OpenCode | OpenCode | the same GLM enrolment |
-| Qwen via OpenCode | OpenCode | the same Qwen enrolment |
-
-The harness is a property of the catalog entry, never a routing input. Which provider a phase runs on is the routing decision in `references/what-runs-next.md`; the routing rows, not the slot, name the model.
-
-## Two state axes
-
-- **Declared**: `active` or `disabled`. The operator sets it.
-- **Observed**: `healthy`, `degraded` or `unknown`. The poller sets it from what the provider reports.
-
-Two more lifecycle facts sit beside them: **quarantined** (system-set, on a credential conflict or an authentication mismatch; Replace credential on the account's page clears it, and a tenant owner or admin can do that, so an operator is not required) and **revoked** (operator-set).
-
-## Windows, walls, headroom
-
-- Subscriptions meter usage over a **5-hour** window and a **7-day** window, each with a used percentage and a reset time.
-- A **wall** is the window limit a session can die at mid-run. Before a slot is granted, a fit gate projects the phase's expected burn against the remaining headroom with a safety margin; a slot that would hit the wall is not offered.
-- **Headroom** per provider is advisory: it counts eligible and degraded slots and the best remaining percentage, and it can never promise what a reservation would refuse because both read the same eligibility predicate.
-- Holds: a Claude slot can serve several phases at once up to a per-account cap; a Codex slot serves one at a time because its refresh tokens are single-use.
-- Slot choice orders by usage band, then live-hold count, then used percent, then the latest reset, so bursts spread across accounts rather than stacking on one.
-
-A poller refreshes an active slot's usage every 5 minutes and a disabled one daily. Separately, vendor status pages are polled for provider health; that signal says nothing about your own accounts' windows, walls or quarantine.
-
-## What the settings page shows
-
-Your tenant's coding-accounts page lists each slot with a five-value status, first match wins: expired-or-revoked, walled, active, attested (healthy and active, but the provider is unobserved), unobserved. A drilldown shows the windows, the holds and the history.
-
-## What a key cannot read yet, and what to say
-
-Coding-account status (provider, declared and observed state, window percentages and resets, walls, quarantine, live holds) is served only behind the tenant's admin gate. So when a human asks "why is nothing running?":
-
-1. Run `node scripts/explain-ticket.mjs <ticket>` for a stuck ticket. `routing_unavailable` with a detail naming a slot or provider, or `no_eligible_account_slot` in the routing block, points at accounts.
-2. Read the live rows with `catalyst-skills accounts` and say what they show; an empty list means no account is enrolled, and the script prints the settings link. Do not guess a wall or a quarantine from silence — a wall is the `walled` field, a quarantine is `quarantined` with its reason.
-3. Treat it as ONE fleet-level cause for every ticket it holds, never as a per-ticket escalation.
-
-The customer session never holds or mints a coding-account credential; phases run in the cloud on the enrolled accounts, and repository access is a per-phase installation token.

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

@@ -1,20 +0,0 @@
-# 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/stages-and-mapping.md

@@ -1,56 +0,0 @@
-# Stages and mapping: eleven slots, five that matter, and how to read this team's map
-
-This reference restates invariants (the slot vocabulary, which slots are load-bearing, the allowed state types, the three mapping modes). Everything about YOUR team — which Linear stage each slot maps to, its name, its type, whether it still exists — is live on the contract under `teams[].stages`. Read it with `node scripts/show-my-map.mjs [--team <key>]`; never quote a stage name or id from memory.
-
-## The eleven slots, in pipeline order
-
-`dispatch`, `intake`, `research`, `plan`, `implement`, `remediate`, `verify`, `review`, `pr`, `done`, `canceled`
-
-A slot is Catalyst's name for a position on the board. A stage is the Linear workflow state your team actually has. Mapping is the per-team table that binds each slot to one stage.
-
-## Five slots are load-bearing
-
-| Slot | Why it matters | Allowed Linear state types |
-| -- | -- | -- |
-| `dispatch` | Moving a card here is how work is dispatched. Nothing is offered from any other column. | `unstarted`, `backlog` |
-| `intake` | Where a never-seen ticket lands for the optional intake pass. | `unstarted`, `backlog` (never Linear's reserved triage type) |
-| `pr` | Where a card must sit for `merge` to be offered. | `started` |
-| `done` | Written by the merge webhook. | `completed` |
-| `canceled` | Terminal; a card here is never work. | `canceled` |
-
-An absent or wrongly-typed mapping on one of these five is a distinct silent failure: the ladder simply never moves. The other six slots are informational — a wrong value costs a warning in readiness, not a stall. That asymmetry is why "map my stages" is a five-field decision.
-
-## Three mapping modes
-
-The contract's `teams[].workflowMode` reports which one a team is in:
-
-- **adopted**: Catalyst created its recommended stage set for the team, one stage per slot, with verify and review sharing one validation stage.
-- **mapped**: the team kept its existing stages and a human chose which stage fills each slot.
-- **mixed**: some slots adopted, some hand-chosen.
-
-`teams[].gitAutomation` is a stored consent for a feature that is not built yet (Catalyst managing a team's Linear git automations); nothing reads it, so `off` never stops work and turning it on would start none. What decides whether a team's tickets start is the mapping above: until dispatch, pr, done and canceled each point at a live stage, Catalyst starts nothing in that team, and `explain` says so by name.
-
-Stage mappings live in the app, at Settings → Linear teams. The cloud reads each repository's `.catalyst/catalyst.toml`, but that file has no stage-mapping section, so a mapping written there changes nothing. An older `.catalyst/config.json` is not imported.
-
-## The state id is the authority; names are display
-
-Each mapped stage carries a `stateId`, a display `name`, a `type`, `stateStillExists` and a `source` (how the mapping was chosen). Only the id is a lookup key. A Linear-to-Linear import can preserve every human-readable name while re-minting every state id, and then a name-based lookup points at nothing. So:
-
-- Move cards by slot (`catalyst-linear`'s move script does this) and let the CLI resolve the id from the contract. Never move a card "to Todo" by name.
-- `stateStillExists: false` means the mapped state is provably gone; the map needs fixing in your tenant settings before that slot can be written to. The CLI refuses such a move rather than guessing.
-- The stage names the contract shows come from the mirror's live view of Linear, not from a stored snapshot, so they are current at read time.
-
-## How to read the printed map
-
-`node scripts/show-my-map.mjs` prints, per team, one row per slot: the slot, the stage name (or `(unmapped)`, or `(state gone)`), the state type, whether the state still exists, and the source. Load-bearing slots are starred. Then the team's ask, hold and release labels with `(absent)` where the workspace has no such label, then the ladder (phases, keying, intake on or off) and the live thresholds.
-
-Reading it for a question:
-
-- "Why does nothing dispatch?" — is `dispatch` mapped, does its state still exist, and is the card actually in that stage? `node scripts/explain-ticket.mjs <ticket>` names `not_at_dispatch_stage` when the card is elsewhere.
-- "Why is merge not running?" — is the card in the `pr` slot's stage?
-- "Why did the card go to Remediate?" — `remediate` is mapped, so a failed phase moved it there (see `references/when-a-phase-fails.md`); if `remediate` is unmapped the same episode shows up as the hold label from `teams[].labels.hold` instead.
-- "The team's Backlog is not in the list" — correct. Backlog is not a slot. Parking a card is a move to the team's backlog-type state, which the CLI resolves from the team's live workflow states rather than from the map.
-
-## Readiness over the mapping
-
-The contract carries a readiness vector per team (`teams[].readiness`), including whether every mapped state exists, whether the mapping is total, whether the types are compatible, whether the labels are present, whether writes land and whether the webhook covers the team. A check the cloud could not run is `unknown`, never `pass`. `catalyst-setup` reads this vector; this skill only points at it.

package/skills/how-catalyst-works/references/the-ladder.md

@@ -1,41 +0,0 @@
-# The ladder: eight phases, what each one produces
-
-This reference restates invariants. The phase order and what each phase leaves behind do not vary per tenant. The only live values are whether intake is switched on for your tenant and which keying the advance table uses; both are on the contract under `ladder` (print them with `node scripts/show-my-map.mjs`).
-
-## The phases, in order
-
-| Phase | What it produces | Notes |
-| -- | -- | -- |
-| `intake` | nothing projected (a classification pass) | Optional head. Offered only to a ticket that has never entered the ladder, and only when the contract says `ladder.intakeEnabled` is true. |
-| `research` | `research.md` | The first ladder phase. Offered when the card sits in the team's dispatch slot. |
-| `plan` | `plan.md` | |
-| `implement` | `implement.md` | Creates the ticket branch (named exactly the ticket identifier) and opens a draft pull request. |
-| `validate` | `validation.md` | Its success moves the card to the team's review stage; verify and review are two slots that both land on that stage. |
-| `pr` | `pr.md` | The first line is the pull-request title, then a blank line, then the body. The phase rebases onto the default branch, force-pushes, writes the title and body, and marks the PR ready for review. |
-| `remediate` | `remediation.json` | An interrupt, not a step forward. It repairs a phase that failed and never advances the card past the PR slot. |
-| `merge` | a receipt, no artifact | Applies the queue-ready label once its evidence gate passes. It writes no board state. |
-
-Every artifact-bearing phase (all but `intake` and `merge`) projects its artifact into Linear as a document attached to the ticket, with a short link comment; `catalyst-linear` describes those shapes.
-
-## What moves the card
-
-An advance table maps a phase outcome to a card move: research done moves the card from the dispatch slot to the research slot, plan done from research to plan, implement done from plan to implement, validate done from implement to review, pr done from review to pr. The table is served on the contract as `ladder.advance` so you can read the exact rows; do not restate them from memory, because the tenant's keying decides whether a stage names the phase that just finished (trailing, the default) or the phase still ahead (leading).
-
-Three rows never move the card:
-
-- A **failed** phase writes no board state. The ticket stays where it was, retryable, and the failure handling in `references/when-a-phase-fails.md` takes over.
-- **`remediate` done** writes nothing by itself; the card restores to its exact pre-failure stage once a remediation round succeeds.
-- **`merge` done** writes nothing. The receipt only ever meant "the queue-ready label was applied".
-
-## Done is written by the merge, never by a phase
-
-The terminal move to the done slot is keyed to the real pull-request-merged event from GitHub, not to any phase receipt. When the PR merges, the mirror's own ingest path moves the ticket to Done within a few seconds, with no session and no human sweep, and a bounded periodic sweep backstops a dropped webhook. So:
-
-- A ticket still not Done a minute after its PR merged is a finding, not a chore to hand-close.
-- Done is not the same as live. A change to something that is deployed separately is inert until that deployment happens; the ticket state says the code merged, nothing more.
-
-## How to read a ticket's position on the ladder
-
-1. The card's stage tells you which phase last finished (under trailing keying) — read the team's map with `node scripts/show-my-map.mjs --team <key>` to translate a stage name into a slot.
-2. The phase-outcome comments on the ticket tell you which attempts ran and how they ended; the document attachments are the artifacts themselves.
-3. `node scripts/explain-ticket.mjs <ticket>` tells you what the cloud will run next, or why it will not.

package/skills/how-catalyst-works/references/what-catalyst-is.md

@@ -1,30 +0,0 @@
-# What Catalyst Cloud is
-
-Explain it in this person's terms: their repositories, their tickets, how they work today. Use their examples. Keep the facts exact; the wording is yours.
-
-## The short version
-
-They keep filing tickets in Linear. Moving a card into the team's dispatch column starts the work. Catalyst Cloud then takes the ticket through research, a plan, the implementation, validation, a pull request and the merge.
-
-Each phase runs in a cloud container, on a coding account the tenant enrolled. Each phase leaves a document and an outcome comment on the ticket, so the ticket is the record.
-
-Their laptop stops being where coding sessions run. There are no local sessions, no home server, and no test runners or headless browsers competing for the machine. They install two skill packs and a small CLI that holds their sign-in.
-
-Each container is set up for the repository: the same skills, MCP servers, environment variable names and secrets. They declare the names once; the values stay in the app.
-
-Agents react to events instead of polling: a ticket edited, a pull request opened, a review landing, a check failing. The `run-this-project` skill explains the watch.
-
-A decision only they can make arrives as a ticket in their own Linear. It has options, a default if they stay silent, and a list of what it holds. Everything else keeps moving.
-
-## What changes in their day
-
-- They start work by moving a card into the dispatch column. Nothing else starts a ticket. See `references/stages-and-mapping.md`.
-- They write the ticket for a reader who cannot see their chat: an outcome in the title, what done looks like, a priority, no open blocker.
-- They never move a card into a working stage by hand, and they never close a ticket. The merge writes Done. See `references/the-ladder.md`.
-- A draft pull request appears that they did not open. A later phase marks it ready. A green pull request with no open review threads merges through the queue. A hold label keeps it out.
-- They answer asks instead of being paged. One stuck ticket or a provider outage is never an ask.
-- A comment they post gets an eyes reaction and a reply in its thread.
-
-## Why it is different
-
-Every item above has a mechanism in another reference. Retries and repair rounds are in `references/when-a-phase-fails.md`. An unknown verdict means "could not look": see `references/what-runs-next.md`. One outage is one alert, not one per ticket.