@catalyst-cloud/cli 0.8.0

package/skills/catalyst-linear/scripts/read-ticket.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// read-ticket.mjs — one ticket with its comments, relations, labels, linked pull requests and agent
+// sessions inline, from the replica when it is fresh, else the origin-fresh API. The source line the
+// CLI prints on stderr is the freshness verdict; it is always shown.
+import { parseFlags, parseJson, relayStderr, runCli, usage, wantsHelp } from "./lib/cli.mjs";
+
+const HELP = `Usage: node scripts/read-ticket.mjs <ticket> [--comments] [--source replica|api] [--json]
+
+Reads one ticket record. Wraps: catalyst-skills query issue.
+
+  <ticket>               the Linear identifier, e.g. KEY-123
+  --comments             also print every comment (id, author, time, body)
+  --source replica|api   force one source; default is the replica when fresh, else the API
+  --json                 print the full record as JSON
+
+The first stderr line names the source ("source: replica (cursor N)" or "source: api (replica
+stale|absent|not configured)"); quote it when the freshness of the answer matters.
+
+Exit 0 found, 1 not found or a usage error, 2 when this machine is not connected to a tenant or the
+cloud refused the read (the line says which).`;
+
+const argv = process.argv.slice(2);
+if (wantsHelp(argv)) {
+  console.log(HELP);
+  process.exit(0);
+}
+const { flags, positionals } = parseFlags(argv, { bool: ["comments", "json"], value: ["source"] });
+const ticket = positionals[0];
+if (!ticket) usage("read-ticket needs a ticket identifier (see --help)");
+
+const args = ["query", "issue", ticket, "--json"];
+if (flags.source) args.push("--source", flags.source);
+const r = runCli(args);
+relayStderr(r);
+if (r.code !== 0) {
+  const out = r.stdout.trimEnd();
+  if (out) console.log(out);
+  process.exit(r.code);
+}
+const row = parseJson(r.stdout);
+if (!row || typeof row !== "object") {
+  console.log(r.stdout.trimEnd());
+  process.exit(1);
+}
+if (flags.json) {
+  console.log(JSON.stringify(row));
+  process.exit(0);
+}
+
+const line = (label, value) => {
+  if (value === undefined || value === null || value === "") return;
+  console.log(`${label}: ${typeof value === "string" ? value : JSON.stringify(value)}`);
+};
+const names = (list, key) => (Array.isArray(list) ? list.map((x) => (x && typeof x === "object" ? (x[key] ?? JSON.stringify(x)) : String(x))) : []);
+
+line("ticket", row.identifier ?? row.id);
+line("title", row.title);
+line("state", row.state);
+line("priority", row.priority_label ?? row.priority);
+line("assignee", row.assignee_name ?? row.assignee);
+line("delegate", row.delegate_name ?? row.delegate);
+line("team", row.team_key ?? row.team_name ?? row.team_id);
+line("project", row.project_name ?? row.project_id);
+line("cycle", row.cycle_name ?? row.cycle_id);
+line("parent", row.parent_identifier);
+line("labels", names(row.labels, "name").join(", "));
+line("url", row.url);
+line("updated", row.updated_at);
+if (Array.isArray(row.relations) && row.relations.length) {
+  console.log(`relations (${row.relations.length}):`);
+  for (const rel of row.relations) console.log(`  ${rel.type ?? "?"}: ${rel.issue_identifier ?? ""} -> ${rel.related_identifier ?? JSON.stringify(rel)}`);
+}
+if (Array.isArray(row.linked_pulls) && row.linked_pulls.length) {
+  console.log(`linked pull requests (${row.linked_pulls.length}):`);
+  for (const pr of row.linked_pulls) console.log(`  #${pr.number ?? "?"} ${pr.repo_id ?? ""} [${pr.node_id ?? ""}]`);
+}
+if (Array.isArray(row.agent_sessions)) line("agent sessions", row.agent_sessions.length);
+if (Array.isArray(row.activity)) line("activity entries", row.activity.length);
+if (Array.isArray(row.comments)) line("comments", row.comments.length);
+if (row.description) {
+  console.log("description:");
+  console.log(String(row.description).trimEnd());
+}
+if (flags.comments && Array.isArray(row.comments)) {
+  console.log(`== comments (${row.comments.length})`);
+  for (const c of row.comments) {
+    const who = c.author_name ?? c.author_id ?? "?";
+    const bot = c.is_bot ? " [bot]" : "";
+    const parent = c.parent_id ? ` reply-to ${c.parent_id}` : "";
+    console.log(`-- ${c.id} · ${who}${bot} · ${c.updated_at ?? c.created_at ?? ""}${parent}`);
+    console.log(String(c.body ?? "").trimEnd());
+  }
+}

package/skills/catalyst-linear/scripts/search.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// search.mjs — tenant search across ticket identifiers and titles, pull-request titles, project and
+// initiative names. Always the origin-fresh API (the replica holds no search view).
+import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wantsHelp } from "./lib/cli.mjs";
+
+const HELP = `Usage: node scripts/search.mjs <terms...> [--limit <n>] [--json]
+
+Searches your tenant for tickets, pull requests, projects and initiatives matching the terms.
+Wraps: catalyst-skills query search.
+
+  <terms>       one or more words; matched against identifiers, titles and names
+  --limit <n>   max rows (default 50)
+  --json        print the rows as JSON
+
+Exit 0 (an empty result is still 0 and prints "no matches"), 1 on a usage error, 2 when this
+machine is not connected to a tenant or the cloud refused the search (the line says which).`;
+
+const argv = process.argv.slice(2);
+if (wantsHelp(argv)) {
+  console.log(HELP);
+  process.exit(0);
+}
+const { flags, positionals } = parseFlags(argv, { bool: ["json"], value: ["limit"] });
+if (positionals.length === 0) usage("search needs at least one term (see --help)");
+
+const args = ["query", "search", ...positionals, "--json"];
+if (flags.limit) args.push("--limit", flags.limit);
+const r = runCli(args);
+exitOnFailure(r);
+relayStderr(r);
+const rows = parseJson(r.stdout);
+if (flags.json) {
+  console.log(JSON.stringify(rows ?? r.stdout.trimEnd()));
+  process.exit(0);
+}
+const list = Array.isArray(rows) ? rows : rows && typeof rows === "object" ? Object.values(rows).flat() : [];
+if (list.length === 0) {
+  console.log("no matches");
+  process.exit(0);
+}
+for (const row of list) {
+  if (!row || typeof row !== "object") {
+    console.log(String(row));
+    continue;
+  }
+  const kind = row.kind ?? (row.identifier ? "issue" : row.number ? "pull" : "row");
+  const id = row.identifier ?? (row.number !== undefined ? `#${row.number}` : row.id ?? "");
+  console.log(`${kind}  ${id}  ${row.title ?? row.name ?? ""}${row.state ? `  (${row.state})` : ""}`);
+}

package/skills/catalyst-onboard/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: catalyst-onboard
+description: >-
+  Walk a person from nothing to their first Catalyst Cloud ticket running, one step at a time, hand-held. Use when someone says "set me up", "onboard me", "I just signed up", "get me started", "what do I do first", or when they have the Catalyst Cloud skills installed and nothing else. Reads each part of the setup with the instrument that owns it — this machine, the person, the account, one project, one repository — never folding one into another, does every step a key can do through the catalyst-skills CLI, and for the steps only a browser can do hands over the exact page and says what to come back with. Never claims a step it did not watch succeed.
+disable-model-invocation: true
+allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
+---
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.8.0 — written in this repository for customer tenants -->
+
+# Onboard me
+
+You take one person from "the skills are installed" to "a ticket is running on my own tenant". You do it **one step at a time**: do the step, show them what actually came back, say what it means and what is next, then stop and let them answer. You never print the whole ladder at them and you never batch several steps into one turn.
+
+Setup has seven parts and each is read by its own instrument: this **machine**, the **person**, the **account**, one **project** (a project is one Linear team), one **repository**, the **coding accounts** a phase runs on, and the **host**. Never say work can run while either of the last two is unfinished. A failure in one is not a failure in another, and a failing part names who can fix it and where. Getting that wrong is the one mistake that wastes a person's afternoon: a project problem reported as a machine problem sends them retrying a local command that was never going to help.
+
+## Run first
+
+Scripts are run, never read. Each prints `--help`.
+
+- `node scripts/where-am-i.mjs` — every part, each with the instrument that read it, its verdict, and for anything unfinished who can fix it and the page it is on. Works before the machine is connected; that is one of the states it reports.
+- `node scripts/where-am-i.mjs --next` — the same reading, reduced to the single next step.
+- `node scripts/where-am-i.mjs --json` — the same document for you to branch on.
+
+Start every session with it, and run it again after every step the person completes. It is the only thing that decides where you are.
+
+## Load on demand
+
+| when | read |
+| -- | -- |
+| walking the steps — what each one does, what to read back, when it is done | `references/the-one-path.md` |
+| anything reports not ready, or you are about to say who should fix something | `references/who-fixes-what.md` |
+| the next step is a browser page, or a page said it worked and you have to confirm it | `references/what-the-browser-owns.md` |
+| the person asks what Catalyst actually is, or how a ticket gets worked | the `how-catalyst-works` skill |
+| the machine will not connect, or a login expired | the `connect-me` skill |
+| the person asks how to install, update, or migrate Catalyst skills | `references/skill-sources.md` |
+| the person's repository needs environment names declared | `references/declaring-a-repository.md` |
+| the `coding accounts` or `host` part is not ok, or you are about to say work can run | `references/what-a-phase-needs.md` |
+| setup is finished and they want the standing readiness verdict | the `catalyst-setup` skill |
+| the first ticket did not start and you need the reason | the `how-catalyst-works` skill, then `unstick` |
+
+## Rules
+
+- **One step, then stop.** Say what you are about to do, do it, show the real output, say what it means and what comes next. Never queue several steps into one message, and never move on from a step you did not watch finish.
+- **Report what you observed, not what you expected.** Print the lines the command actually produced. "That worked" without the output it produced is the single easiest thing to get wrong here, and a person who later finds it did not work stops trusting every other step you reported.
+- **Each part by its own instrument.** Read the machine with the machine's instrument and the project with the project's, and label every finding with the part it belongs to. The script does this for you; keep it that way when you summarize.
+- **Not ready is a question about who, not a reason to retry.** When something reports not ready, name which check, who can fix it, and where. If the owner is not the person in front of you, say so and stop — re-running a local command cannot move a check that belongs to a tenant owner, an admin, or a browser page.
+- **Never invent a count or a list.** Every number and every name comes from what a command printed. If you want to tell them how many projects are mapped, read it off the script's output; do not carry one over from an earlier turn.
+- **Three steps belong to a browser and always will**: approving the login, connecting Linear, and installing the GitHub App. Hand over the page and say what you need back. Do not claim you did them.
+- **Some steps a key cannot do yet.** Listing every project, saving a stage mapping, adopting the workflow, registering a repository and approving one repository's environment are settings-page work today; a key-callable path for them is being built. Route those through the browser and say plainly that it is a gap, not the design. Never guess at a route for them.
+- **The account-wide environment declaration is the exception, and the one setup write you can perform.** `catalyst-skills environment` reads it, proposes it and approves it. Use the verb; do not send them to a page for it.
+- **Their tenant, as them.** Everything goes through the CLI and the person's own login. You never name another tenant, and you never ask for a key you could avoid — the keyless login needs nothing pasted.
+- **Use the right skill source.** This tenant onboarding skill comes from `catalyst-cloud-skills`. Coding workflows come from `catalyst-dev-skills`. Never direct a person to install skills from the deprecated local runtime or its `catalyst-dev@catalyst` plugin.
+- **Write like a capable colleague.** Plain words, short sentences, one idea each, active voice. Say what a thing does with a fact or a number. No em dashes, no emoji, no chatbot openers or flattery, and bold only the rare thing. Reread each message before you send it and fix what sounds machine-written.
+- **Ask once before you write to their machine.** Say what you found, what you will write and where, then wait for a yes. A skill migration asks again before each removal.
+- **A blocked command is the person's call.** If the harness blocks `npx`, a global `npm install -g`, or a tool permission, ask for approval or hand them the command. Never skip it silently, never edit your own permission settings, and never report a step you did not see succeed.
+- **An older cloud is not a broken command.** When the CLI says the cloud is older than the bundle, say so and move on. The command exists; this tenant's cloud has not deployed it yet.
+- **Stop at a wall you cannot pass.** A suspended account, a seat that is not active, a person who is not an owner or admin where one is required: say what you found, name who can act, and stop. Do not loop.

package/skills/catalyst-onboard/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Onboard me"
+  short_description: "Walk a person from nothing to their first Catalyst Cloud ticket running, one step at a time, saying who owns each step"
+  default_prompt: "Use $catalyst-onboard to set me up on Catalyst Cloud, one step at a time."
+policy:
+  allow_implicit_invocation: false

package/skills/catalyst-onboard/agents/portability.yaml

@@ -0,0 +1,5 @@
+identity: { pack: catalyst-cloud-skills, skill: catalyst-onboard }
+effects: [local-write, external-write]
+mutating: true
+invocation: explicit
+exposure: [catalog]

package/skills/catalyst-onboard/references/declaring-a-repository.md

@@ -0,0 +1,23 @@
+# Declaring what one repository's containers need
+
+The cloud containers build and test the repository. They need the names of the variables and secrets it reads. You write the names; the person enters the values in the app. Never read or print a value.
+
+## The inventory, in order
+
+1. Start from the commands that already build and test the repository: the README's setup section, the scripts in `package.json` or its equivalent, and the build and test steps in CI. Those are what the container runs. A name they never read does not belong in the file.
+2. For each name, record the file it came from: a `.env.example` (never `.env`, which holds live values), a CI secret in a workflow's `env:` block, or a platform binding. A name you cannot tie to a file is a guess. Say so instead of listing it.
+3. Mark whether the container needs it to build and test, or only to deploy. Containers build and test. They do not deploy.
+4. Leave platform bindings and deploy-only CI secrets out by default. The platform supplies a binding at run time, and no build or test reads a deploy-only secret. Include one only when the person says the build needs it, and say why.
+5. Write the names into `catalyst.env.json` at the repository root and open a pull request. Use that exact name and place; the cloud reads no other file. It reads the file once the pull request merges to the default branch. A tenant owner or admin then approves it at Settings → Repositories → the repository → Environment, and the person enters the values on that page.
+
+## The file's shape
+
+`"version": 1` plus eight arrays, each present even when empty: `toolchains`, `systemPackages`, `setup`, `verify`, `services`, `environment`, `agentAssets`, `provenance`. The repository's Environment page in the app shows a complete, valid example. Start from it rather than from memory.
+
+- `setup` and `verify` carry this repository's own install and test commands. `command` is an argument list, not a shell string.
+- Each name under `environment` says whether it is `required`. Add `"secret": true` beside a secret.
+- Each `provenanceIds` entry points at a record under `provenance` that names the file the name came from.
+
+## After the merge
+
+`catalyst-skills ready` reports `environment_declared` for the team's default repository and names the next step: commit the file, fix it, or approve it. The `catalyst-setup` check table has each reason. The account-wide declaration is separate; `catalyst-skills environment` handles it (step 7 of `references/the-one-path.md`).

package/skills/catalyst-onboard/references/skill-sources.md

@@ -0,0 +1,35 @@
+# Catalyst skill sources
+
+Catalyst has two supported skill packs. They have separate purposes and versions.
+
+The installer the person ran first, at their cloud's `/install.sh` (the app's setup page shows the command), installs both packs in one pass. It stages them with a pinned skills CLI, installs exact commits, and stops on any same-named skill it does not recognise, naming the path. A home install schedules a daily refresh that also picks up new skills. Re-run it to refresh or repair either pack. The commands in the table are the by-hand equivalent.
+
+| Pack | Purpose | By hand | Optional Claude Code plugin |
+| -- | -- | -- | -- |
+| `coalesce-labs/catalyst-cloud-skills` | Tenant setup and operation | `npx skills@latest add coalesce-labs/catalyst-cloud-skills --all -g` | `catalyst@catalyst-cloud` |
+| `coalesce-labs/catalyst-dev-skills` | Coding workflows | `npx skills@latest add coalesce-labs/catalyst-dev-skills --all -g` | `catalyst-dev@catalyst-dev-skills` |
+
+Install both packs on a workstation used for coding and tenant operations. Each Claude plugin is an alternative to `npx skills` for that same pack. Do not install a pack through both methods.
+
+## Where each install lands
+
+- Global (`-g`): the skills go in `~/.agents/skills/`, and `~/.claude/skills/` holds links into it. Codex, Cursor and OpenCode read `~/.agents/skills/`; nothing fills `~/.codex/skills/` or `~/.cursor/skills/`.
+- Project (no `-g`): `.agents/skills/`, `.claude/skills/` and `skills-lock.json` at the project root. Nothing lands in the home directory.
+- The global lock is `$XDG_STATE_HOME/skills/.skill-lock.json` when `XDG_STATE_HOME` is set, else `~/.agents/.skill-lock.json`. A project uses its own `skills-lock.json`.
+- The installer writes relative links. Resolve each with `readlink -f` before you compare paths.
+
+## Is each pack there
+
+`catalyst-skills ready` checks the Cloud pack only. Check `catalyst-onboard/SKILL.md` (Cloud pack) and `research-codebase/SKILL.md` (development pack) in the intended directory. If both are there, have the person type `/catalyst-onboard` (`$catalyst-onboard` in Codex).
+
+## Migrate an existing installation
+
+Inventory source and scope before removing anything:
+
+1. Run `claude plugin list` and record whether `catalyst-dev@catalyst` is installed and at which scope.
+2. Inspect the selected agent's home skill directory and the current project's skill directory separately. Read any `skills-lock.json` files and source/provenance markers. A folder name alone does not prove which repository supplied it. Check whether `.claude/skills` is a symlink to another skills directory before changing either path.
+3. If the old plugin is active, remove only `catalyst-dev@catalyst`: `claude plugin uninstall catalyst-dev@catalyst --scope user --keep-data --yes`. Keep `catalyst-dev@catalyst-dev-skills` and `catalyst@catalyst-cloud`. If old skill copies are present, remove only copies whose recorded source is the deprecated local runtime. Keep unrelated skills and plugin installs.
+4. Install the replacement pack or packs in the intended scope with the commands above. For the Cloud pack, omit `-g` only when a project-scoped install is intended. Do not use a blanket `npx skills remove --all` during migration.
+5. Read back the plugin list or skill lock and the destination skill folders. Start a new agent session after changing Claude plugins.
+
+Do not delete a Catalyst checkout, local project data, or a same-named skill whose source is not known. If the source or scope is ambiguous, stop and report what is unclear before removing anything.

package/skills/catalyst-onboard/references/the-one-path.md

@@ -0,0 +1,149 @@
+# The one path
+
+Nine steps, in this order. The order is the product's own: the tenant-side steps run Linear, then the project, then GitHub, then the repository, because each one is the cheapest place to catch the failure the next one would otherwise hide.
+
+Walk them **one at a time**. Before each step say what you are about to do and why; after it, show what actually came back. `node scripts/where-am-i.mjs --next` decides which step you are on — never your memory of the last turn.
+
+Each step below states: what it is for, what you run or hand over, **what you read back to prove it landed**, and **who owns it**.
+
+---
+
+## 0 — Where are we
+
+**For:** starting from the truth instead of from an assumption. A person arrives here having done anything from nothing to most of it.
+
+**You run:** `node scripts/where-am-i.mjs`
+
+**Read back:** the whole thing, as it printed. Then say in one sentence which part is unfinished and whose it is.
+
+**Owner:** you.
+
+---
+
+## 1 — Connect this machine
+
+**For:** giving this machine a credential, so every later read is the person's own.
+
+**You run:** `catalyst-skills login`. It prints a short code and a URL. The person approves it in a browser — from a phone, if this machine has none.
+
+**Read back:** the `Connected to …` and `Connected as …` lines the command printed, then `node scripts/where-am-i.mjs` again so the machine part flips.
+
+**Owner:** you run it; **the approval is the person's, in a browser, and always will be.** Wait for them. Do not re-run the command while a code is outstanding — that invalidates the code they are typing.
+
+If it refuses, stop here and use the `connect-me` skill; it owns every failure mode of this step.
+
+---
+
+## 2 — Who you are
+
+**For:** the person grain. A connected machine does not mean an active seat, and an active seat does not mean their Linear identity is matched.
+
+**You run:** it is already in the step 0 script's `person` line.
+
+**Read back:** their label and role, and whether their Linear identity is matched.
+
+**Owner:** an unmatched Linear identity is fixed by a tenant owner or admin in Settings → Members. A seat that is not active is the same. Say which, and move on — neither blocks the steps below, but an unmatched identity means "what needs me" will show everyone's asks until it is fixed, and they should know that now rather than later.
+
+---
+
+## 3 — Connect Linear
+
+**For:** the account grain. Nothing about a project can be read or mapped until the tenant's Linear workspace is connected.
+
+**You hand over:** `<their cloud>/settings/connections`, and say: connect Linear.
+
+**Read back:** after they say it is done, re-run `node scripts/where-am-i.mjs` and read them the `account` line. A resolved workspace is proof. If it still reads unresolved, say the contract may be cached and run `catalyst-skills contract --refresh`, then read it again.
+
+**Owner:** a tenant owner or admin, in a browser. **This is a browser step by construction** — it is an authorization grant, and no key can perform one.
+
+---
+
+## 4 — Pick one project, and map its stages
+
+**For:** the project grain. A project is one Linear team. Until a project's stages are mapped, a card moved into it does nothing at all — this is the single most common reason a new tenant sees no activity.
+
+**You hand over:** `<their cloud>/settings/linear-teams`. They pick one project and press **Map my stages**, or **Adopt the Catalyst workflow** if they want Catalyst's own stages created for them.
+
+**Read back:** re-run the script and read the `projects` line. A project that now appears with a readiness verdict is proof it was saved. Read them the verdict and any failing checks by name.
+
+**Owner:** a tenant owner or admin. ⛔ **Listing the projects and saving a mapping are settings-page work today** — a key cannot do either yet, and a key-callable path is being built. Say that plainly; it is a gap in the product, not something they did wrong.
+
+⭐ **One project at a time is safe, and lead with this.** Mapping one project changes no other project's stages and moves no other project's tickets. Encourage a pilot: pick the project they care least about breaking.
+
+---
+
+## 5 — Install the GitHub App
+
+**For:** the account grain again. Without it Catalyst can read tickets but cannot touch code.
+
+**You hand over:** `<their cloud>/settings/connections`, and say: install the GitHub App, and grant it the repository they want worked.
+
+**Read back:** it is confirmed by step 6 succeeding — a repository cannot be registered through an app that is not installed. Say that is what you are waiting for rather than claiming you verified it here.
+
+**Owner:** a tenant owner or admin, in a browser. **Browser by construction**, same reason as step 3.
+
+---
+
+## 6 — Register the repository
+
+**For:** the repository grain. Registering is what makes a repository something a project can dispatch work into.
+
+**You hand over:** `<their cloud>/settings/repositories`, and say: add the repository, **and attach it to the project you mapped in step 4**.
+
+**Read back:** re-run the script and read the `repositories` line. The repository appearing there is proof it was registered — and **only that**. It is not proof it can be dispatched to; see `references/who-fixes-what.md` for what registration does and does not prove.
+
+**Owner:** a tenant owner or admin. ⛔ **Registering is settings-page work today**; a key-callable path is being built. ⛔ A repository registered without a project attached is the trap here: the call succeeds, the repository is listed, and nothing can ever dispatch into it. Make sure they attach the project in the same form, and say why.
+
+---
+
+## 7 — Declare what the containers need
+
+**For:** the environment a phase runs in — the names of the variables and secrets the person's code needs. Names leave the machine; values are entered once, by them, in the app.
+
+⭐ **This is the one setup step you can actually do.** Every other step above is a page. This one is a command, and it is worth saying so to the person.
+
+**You run:** `catalyst-skills environment` first, to read what the tenant already declares — the current revision, whether it is approved, and which revision a phase's checkout actually carries. Those last two are different things more often than people expect: a proposal that nobody approved changes nothing.
+
+To change it, write the declaration to a JSON file and propose it:
+
+```sh
+catalyst-skills environment propose --file declaration.json
+```
+
+Add `--approve` to approve exactly the revision that propose just returned, which is the one-command form and the one to prefer — it is a compare-and-set, and nothing gets copied between two commands by hand. `catalyst-skills environment approve` on its own reads the current revision and approves that.
+
+**Read back:** the revision and hash the command printed, and whether it says the declaration is now what a phase's checkout carries. If it prints `referenced but not set on this tenant yet`, read those names out: the declaration names them and the tenant has no value for them, so a phase that needs one will fail on it until someone adds it in the app.
+
+**Owner:** you can read it from any active seat; proposing and approving need an admin or owner seat, and the cloud refuses with that sentence if the person does not have one — read the refusal to them rather than retrying.
+
+⛔ **Values never pass through you.** The declaration carries the *names* a build needs. The values are entered by the person, once, in the app, and nothing you run ever sees them. Say that plainly; a person asked for a secret by an agent is right to be suspicious. The names one repository needs go in its own committed `catalyst.env.json`. See `references/declaring-a-repository.md`.
+
+If they do not know what their build needs yet, skip this step. It blocks nothing until a phase needs a secret.
+
+---
+
+## 8 — A coding account, and a host
+
+**For:** what a phase runs on. Without an enrolled coding account and a passing host check, every step above can be done and nothing starts.
+
+**You run:** it is already in the script, as the `coding accounts` and `host` parts. What each reading means, who owns it, and what to hand over are in `references/what-a-phase-needs.md`. The contract names who enrols the account and who owns the host.
+
+---
+
+## 9 — Verify, then run the first ticket
+
+**For:** the only thing that proves setup worked.
+
+**You run:** `catalyst-skills ready`. Its READY does not cover step 8; the script does. Read them the verdict and every failing line, each with its own fix and owner. If it says NOT READY, go to `references/who-fixes-what.md` before you touch anything — a project check failing is not something re-running anything on this machine can fix.
+
+**Then:** have them move one card into the project's dispatch stage, and watch. `catalyst-skills explain <ticket>` says why it is or is not about to run.
+
+**Read back:** what `explain` actually said. If it says the ticket cannot start, the reason it names is the answer — read it to them and use the `how-catalyst-works` skill for what the reason means, then `unstick` if something is holding it.
+
+**Owner:** the card move is theirs. The verdict is the tenant's.
+
+---
+
+## When you are done
+
+Say what is set up, name anything still unfinished with its owner, and never say work can run while the `coding accounts` or `host` part is unfinished, and tell them the standing question "am I set up?" now belongs to the `catalyst-setup` skill, and "what's happening?" to `whats-happening`. You do not need to be invoked again.

package/skills/catalyst-onboard/references/what-a-phase-needs.md

@@ -0,0 +1,46 @@
+# What a phase needs to run
+
+A person can finish every other step and still see nothing run. A phase needs two more things: an enrolled coding account, and a host check that passes. `node scripts/where-am-i.mjs` reads both, as the `coding accounts` and `host` parts. Read those parts; never assume either.
+
+## Coding accounts
+
+**For:** a phase runs on one of the tenant's own enrolled coding accounts. With none active, no phase can start.
+
+**Instrument:** `codingAccounts` in `catalyst-skills contract`. It carries a `state`, a printable `line`, who enrolls an account (`enrolledByLine`) and the `page`. The script prints all of them. It never shows a credential or an email.
+
+**What each state means:**
+
+| state | what it says | what to do |
+| -- | -- | -- |
+| `enrolled` | at least one account is active | nothing |
+| `none_enrolled` | no account is enrolled | hand over the page; the enroller the contract names enrols one |
+| `inactive` | accounts exist, but every one is out of rotation | reactivate one on the page. Never tell them to enrol another |
+| `unread` | the cloud could not read the accounts | say it could not be read. It is not "no accounts". Do not tell them to enrol one; read it again later |
+
+**Owner:** the one the contract names. The person does it in the browser. Never ask for the credential, and never handle it. A key cannot enrol one.
+
+**Older cloud:** if the contract has no `codingAccounts`, the script says the cloud is older and reads `catalyst-skills accounts` instead. That list counts the accounts enrolled and the ones able to take work. An expired, revoked or quarantined account does not count. The owner is then a tenant owner or admin, at `<their cloud>/settings/coding-accounts`.
+
+## Host
+
+**For:** the contract carries this as the `hosts_current` readiness check on each project. It reads the same on every project, because it is about the whole account.
+
+**Instrument:** the `hosts_current` check in `catalyst-skills contract --path teams`, and its owner in `catalyst-skills contract --path readinessChecks`.
+
+**What each reading means:**
+
+| reading | what it says | what to do |
+| -- | -- | -- |
+| `pass` | nothing is waiting on a host. A tenant that runs no host of its own reads this too | nothing |
+| `unknown`, `no_host_connected` | no Catalyst host is connected | name the owner and stop |
+| `unknown`, `hosts_unreported` | a host is connected but has not said which mapping it loaded | name the owner; it clears when the host reconnects |
+| `fail`, `hosts_behind` | a connected host runs an older mapping | name the owner |
+| the part reads `unreadable` | no project has been checked yet | press Re-check on the projects page, then read it again |
+
+**Owner:** the contract names the owner of `hosts_current`, and where they act in its `fixedWhere`. When `fixedWhere` has a page, the script prints it, and the command too when there is one. When it is null, which it is today, the script prints the owner sentence alone. Then there is no page, so do not invent one. Say who owns it and that they connect it.
+
+⛔ `catalyst-skills ready` treats this check as a note, so it can print READY while no host is connected. READY there is not proof a phase can run. The `host` part is.
+
+## Saying it is ready
+
+Say a phase can run only when the script's last line says nothing is left. While either part is unfinished or unreadable, name that part, its owner, and where, and say plainly that no work will start yet.

package/skills/catalyst-onboard/references/what-the-browser-owns.md

@@ -0,0 +1,50 @@
+# What the browser owns
+
+Some steps you cannot do, and the honest thing is to say which and why. There are two kinds, and they deserve different sentences.
+
+## Kind one: browser by construction
+
+These will never be a command, on any release. Each is an authorization a person grants in their own session; a credential that could perform one would defeat the point of it.
+
+| step | where | what you say |
+| -- | -- | -- |
+| approving the login | the URL and short code that `catalyst-skills login` printed | "I have started the login. It printed this code and this URL — approve it in your browser, or on your phone, and tell me when it is done." |
+| connecting Linear | `<their cloud>/settings/connections` | "Open this page and connect Linear. It will send you to Linear to authorize it and bring you back." |
+| installing the GitHub App | `<their cloud>/settings/connections` | "Open the same page and install the GitHub App, granting it the repository you want worked." |
+
+Say **by construction**, not "not supported yet". A person who thinks it is a missing feature will wait for it.
+
+## Kind two: not a command yet
+
+These are settings pages today because the routes behind them take a browser session and not a key. A key-callable path is being built. They are gaps, and you should say so in those words — but you must still route the person through the browser, and you must not guess at a route. Trying one and being refused wastes their time and teaches them the tool is unreliable.
+
+| step | where | what you say |
+| -- | -- | -- |
+| seeing every project they could set up | `<their cloud>/settings/linear-teams` | "I can read the projects that are already mapped, but the full list is only on this page today. Open it and tell me the ones you see." |
+| checking a project's readiness, or re-checking it | the same page | "I can read the verdict your tenant last stored, from the contract. Asking for a fresh check is on that page." |
+| mapping stages, or adopting the workflow | the same page, per project | "Pick one project, then **Map my stages** — or **Adopt the Catalyst workflow** if you want Catalyst's stages created for you." |
+| registering a repository | `<their cloud>/settings/repositories` | "Add the repository here, and attach it to the project you just mapped, in the same form." |
+| approving the environment **for one repository**, and entering its values | that repository's environment section under `<their cloud>/settings/repositories` | "The names come from `catalyst.env.json` in the repository, which I can write with you. Approving it and entering the values happen here, once, by you. Nothing I run ever sees a value." (Account-wide names are **not** on this list: `catalyst-skills environment` does those.) |
+
+⛔ **Do not compose a request for any of these.** A skill script never makes a request of its own; only the CLI does, and the CLI has no verb for them. If you find yourself constructing a URL, stop.
+
+## The URL to hand over
+
+Never type a host from memory. `catalyst-skills status` prints the API it is connected to on its `API:` line, and `node scripts/where-am-i.mjs` prints ready-made links built from it. Use those. A person pointed at the wrong tenant's settings page has a worse afternoon than one pointed at no page at all.
+
+## Handing over, and coming back
+
+The shape is always the same three parts, and all three matter:
+
+1. **What to open.** One link, and what they will see on it.
+2. **What to do there.** One action, named the way the page names it.
+3. **What you need back.** Not "let me know when you are done" — say what you will check and how. "When you have saved it, say so and I will re-read your tenant and tell you what it now says."
+
+Then **wait**. Do not run anything while they are mid-flow, do not narrate, and do not move to the next step.
+
+When they come back:
+
+- Re-run `node scripts/where-am-i.mjs` and read them the part that should have changed.
+- If it changed, say what it now says and move on.
+- If it did not, refresh the contract once (`catalyst-skills contract --refresh`) and read it again — the contract is cached, and a page can be ahead of it by a few seconds.
+- If it still did not, report both: what the page told them, and what the instrument says. Ask what they saw. **Never mark a step done because the person said a page worked** — the instrument is the record, and this is exactly where a confident false "all set" costs them an hour later.

package/skills/catalyst-onboard/references/who-fixes-what.md

@@ -0,0 +1,44 @@
+# Who fixes what
+
+Setup is seven parts. Each has one instrument, and each instrument answers about its own part and nothing else. Read this before you tell a person that something is not ready, and before you tell them to do anything about it.
+
+## The seven parts, and the instrument that owns each
+
+| part | instrument | what a pass proves | what it does **not** prove | who fixes a failure, and where |
+| -- | -- | -- | -- | -- |
+| **machine** | `catalyst-skills status`, and the non-team checks of `catalyst-skills ready` | Node is new enough, this machine holds a credential, the CLI is where the config says, the contract is cached, the skills are on disk | anything at all about the tenant | the person at this keyboard, here |
+| **person** | `catalyst-skills me` | the credential resolves to this person, with a role, and whether their Linear identity is matched | that their seat is active, or that they may change tenant settings | a tenant owner or admin, Settings → Members |
+| **account** | `catalyst-skills contract --path account` | a resolved Linear workspace means the tenant's Linear grant landed | that the GitHub App is installed — the contract does not carry it | a tenant owner or admin, `<their cloud>/settings/connections` |
+| **project** | `catalyst-skills contract --path teams`, and the `team:` checks of `ready` | for each project **that has been mapped**: its readiness verdict and each failing check by name | that this is every project they have — see below | a tenant owner or admin, `<their cloud>/settings/linear-teams` |
+| **repository** | `catalyst-skills contract --path merge.repositories` | the repository is registered to the account | that it is active, that a project can dispatch into it, or that its environment is declared | a tenant owner or admin, `<their cloud>/settings/repositories` |
+| **coding accounts** | `codingAccounts` in `catalyst-skills contract` (`catalyst-skills accounts` on an older cloud) | an account is enrolled and active | that it has headroom left for the next phase | the enroller and page the contract names; see `references/what-a-phase-needs.md` |
+| **host** | the `hosts_current` check in `catalyst-skills contract --path teams` | no host is missing or behind, or the tenant runs none | anything before a project has been checked | the owner the contract names for `hosts_current`; see `references/what-a-phase-needs.md` |
+
+`node scripts/where-am-i.mjs` runs all seven and labels each finding with its part. Use it rather than composing this by hand.
+
+## The two silences that are not absences
+
+⛔ **An empty project list means nothing is mapped yet — it does not mean they have no projects.** The tenant contract carries a project only once someone has saved a stage mapping for it. A brand-new tenant has projects in Linear and an empty list here, and reading that as "you have no projects" sends the person looking for a problem that does not exist. Say: *nothing is mapped yet*, and go to step 4. The list of every project they could map is browser-only today.
+
+⛔ **A registered repository is not a dispatchable one.** The contract's repository list carries no status and no project attachment, so a paused repository and an active one look identical there, and a repository registered without a project attached looks exactly like a correctly attached one. Registration is all it proves. If a card does not start, `catalyst-skills explain <ticket>` names the real reason; do not conclude anything about the repository from its presence in a list.
+
+⭐ And the general form of both: **an instrument that answers about a part it does not own will answer confidently and wrongly.** When you are unsure which part something belongs to, look it up in the table above rather than guessing from the wording of an error.
+
+## Triaging NOT READY
+
+`catalyst-skills ready` prints one verdict over every check, machine and project together. That single verdict is correct for "can work run?" and useless for "what should I do now?", because it folds two parts into one word. Split it before you act:
+
+1. Run `catalyst-skills ready --json`. Every check has an `id`.
+2. A check whose id begins with `team:` is a **project** finding. Everything else is a **machine** finding.
+3. Report the two groups separately, in that order, each with its own owner.
+
+- **A machine check failed.** This is the person's, here, now. Each failing check carries its own `fix` line; read it and do it. A missing or partial skill set is `catalyst-skills install`; a stale contract is `catalyst-skills contract --refresh`; a missing CLI path is one more `catalyst-skills login`.
+- **A project check failed.** ⛔ **Nothing you run on this machine can move it.** Name the check, name the project, and name the owner — the `who` field carries the tenant's own owners and admins. Point at `<their cloud>/settings/linear-teams`. Then stop. Re-running `ready` in a loop is the failure this section exists to prevent: it will keep saying NOT READY for a reason that lives somewhere else entirely.
+- **A check is a note.** Notes never move the verdict. A stale or absent replica is optional; a check that has never been run is waiting, not failing; a check the engine could not run is unknown, which is not a pass and not a failure. Say which of the three it is.
+
+## When to stop rather than continue
+
+- **They have no account yet.** There is no self-serve sign-up. Coalesce Labs provisions each account, and a person joins one by invitation from its admin. Say so and stop; the next step is theirs.
+- **The account is suspended.** Setup cannot proceed and no retry changes that. Say so and name the conversation they need to have.
+- **Their seat is not active, or they are not an owner or admin where one is required.** Say who is, and what to ask for. Do not offer a workaround.
+- **A page said it worked and the instrument still disagrees.** Refresh the contract once (`catalyst-skills contract --refresh`) and read it again. If it still disagrees, report both facts — what the page said and what the instrument says — and let the person decide. Do not pick one for them.