@catalyst-cloud/cli 0.13.0 → 0.13.1

package/skills/catalyst-linear/references/writing-to-linear.md

@@ -1,6 +1,6 @@
 # Writing to Linear: identity, budget, slots, labels
 
-This reference restates the write mechanism. The live values it depends on — the route table, the daily write budget, the stage map, the label ids — are read by the CLI from the contract (`routes`, `thresholds`, `teams[].stages`, `teams[].labels`) on every write. Nothing here is a literal to copy.
+The CLI reads the route table, write budget, stage map and label ids from the contract on every write; nothing here is a literal to copy.
 
 ## Every write is one script
 
@@ -12,21 +12,19 @@ This reference restates the write mechanism. The live values it depends on — t
 | a new ticket | `node scripts/create-ticket.mjs --team <key> --title <text> [--description <text> \| --stdin]` |
 | a decision for a human | not here: the `what-needs-me` skill raises an ask with options, a default and what it blocks |
 
-Each script wraps one `catalyst-skills write` verb, which posts to the route the contract names, as the tenant's app actor, with the personal key this machine connected with — so the write carries the person's identity for attribution, and an ask names them. No script composes a URL, and none needs a Linear credential of its own.
+Each script wraps one `catalyst write` verb, which posts to the contract's route as the app actor with this machine's personal key, so the write is attributed to the person.
 
 ## App actor versus personal identity
 
-Every write goes out as the tenant's Catalyst app actor by default. That identity is what the cloud's own comment-wake trigger recognises as "not a human", so an app-actor comment never wakes an agent to reply to it, never needs the bookkeeping marker to be safe, and reads to the human as Catalyst speaking. `--as-user` switches a comment or a new ticket to the personal identity behind the key; use it only when the human asked for that attribution, and then mark any machine record with `--bookkeeping`, because on that path the record is indistinguishable from the human typing it.
-
-Reply where the message arrived: a comment inside a thread is answered with `--parent <commentId>`, in that thread, and never as a new ticket. Never post as the human; you speak as Catalyst, or as yourself by role.
+Writes go out as the app actor by default, which the comment-wake trigger recognises as not human, so an app-actor comment never wakes an agent and reads as Catalyst speaking. `--as-user` switches a comment or new ticket to the person's identity; use it only when they asked for that attribution, and then mark any machine record with `--bookkeeping`, because it is otherwise indistinguishable from them typing it. Answer a thread in that thread with `--parent <commentId>`.
 
 ## The daily write budget
 
-Every write route spends one unit of a per-host daily budget the contract publishes as `thresholds.hostDailyWriteBudget`; a label call spends one unit whatever the label count; reads spend none. When the budget is spent, the CLI refuses with exit 2 and a line that names the budget and the retry time. Do not retry in a loop; report it, and batch what you can into fewer writes (one comment, not five).
+Every write spends one unit of the per-host daily budget (`thresholds.hostDailyWriteBudget`), a label call one unit whatever its count; reads spend none. A spent budget exits 2 naming the retry time: report it, and batch into fewer writes.
 
 ## State moves are by slot, never by name
 
-`--slot <slot>` names one of the eleven slots; the CLI resolves it to this team's live state id from the contract. It refuses when the slot is unmapped for the team, and when the mapped state no longer exists in Linear (the map needs fixing in tenant settings first). Moving to `dispatch` is how work is dispatched; nothing is offered from any other column. Backlog is not a slot: `--state-type backlog` resolves the team's first backlog-type state from its live workflow states, and moving a card there parks it and stops remediation rounds. A move never fabricates a state id, and a move by stage name is not offered because names are display fields that survive re-imports while ids do not.
+`--slot <slot>` resolves to the team's live state id from the contract, and refuses when the slot is unmapped or its state is gone (re-map first: `catalyst team map <KEY>`). Moving to `dispatch` dispatches work. `--state-type backlog` resolves the team's first backlog-type state and parks the card, stopping remediation rounds. Names are display fields that survive re-imports while ids do not, so there is no move by name.
 
 ## Labels are by contract id
 
@@ -36,8 +34,8 @@ Two labels are a human's, not yours: the release label (which frees a ticket the
 
 ## A new ticket takes the team key
 
-`create-ticket.mjs --team <key>` names the team by the prefix its identifiers carry; the CLI resolves the team id from the contract and the cloud fences the write to your tenant on the team, not only on the credential. A ticket's body goes in `--description`, or on stdin with `--stdin` when it runs to several lines; a title with no body gives whoever picks the ticket up nothing to act on. Cite the identifier only after the script prints it; a guessed number is usually a real, unrelated ticket. Do not file a question for a human this way: a ticket whose text reads as a decision request is held out of dispatch by shape until someone releases it, and it would never reach the human's inbox with what it blocks.
+`create-ticket.mjs --team <key>` takes the identifier prefix; the CLI resolves the team from the contract. Give it a body (`--description`, or `--stdin` for several lines), since a bare title leaves nothing to act on. Cite the identifier only after the script prints it; a guessed number is usually a real, unrelated ticket. A question for a human filed this way is held out of dispatch by shape and never reaches their inbox; raise it through `what-needs-me`.
 
 ## What is never offered
 
-Delegation (assigning a ticket to an agent) is an operator action, not a tenant write. Answering an ask on the human's behalf is not a write you make; the human answers, and `what-needs-me` records the acceptance. Editing another actor's comment is not available.
+Delegating a ticket to an agent is an operator action. The human answers their own asks (`what-needs-me` records the acceptance). Another actor's comment cannot be edited.

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

@@ -7,7 +7,7 @@ import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wants
 
 const HELP = `Usage: node scripts/comment.mjs <ticket> (--body <text> | --stdin) [--parent <commentId>] [--bookkeeping] [--as-user] [--json]
 
-Posts one comment on a ticket. Wraps: catalyst-skills write comment. Spends one unit of the tenant's
+Posts one comment on a ticket. Wraps: catalyst write comment. Spends one unit of the tenant's
 daily write budget.
 
   <ticket>               the Linear identifier, e.g. KEY-123

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

@@ -7,7 +7,7 @@ import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wants
 
 const HELP = `Usage: node scripts/create-ticket.mjs --team <key> --title <text> [--description <text> | --stdin] [--label <name|id>]... [--priority <0-4>] [--as-user] [--json]
 
-Creates one ticket. Wraps: catalyst-skills write create. Spends one unit of the daily write budget.
+Creates one ticket. Wraps: catalyst write create. Spends one unit of the daily write budget.
 
   --team <key>          the team key (the prefix of its ticket identifiers)
   --title <text>        the ticket title

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

@@ -5,7 +5,7 @@ import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wants
 
 const HELP = `Usage: node scripts/label.mjs <ticket> [--add <name|id>]... [--remove <name|id>]... [--json]
 
-Adds and/or removes labels. Wraps: catalyst-skills write label. One write-budget unit per call
+Adds and/or removes labels. Wraps: catalyst write label. One write-budget unit per call
 direction (add, remove), whatever the label count.
 
   <ticket>              the Linear identifier, e.g. KEY-123

package/skills/catalyst-linear/scripts/lib/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: it spawns the catalyst-skills CLI
+// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: it spawns the catalyst CLI
 // this machine connected with (the path recorded in customer.json, else npx) and hands back its
 // output. Scripts import it; a person runs it with --help to see what it does. No dependencies.
 import { spawnSync } from "node:child_process";
@@ -8,7 +8,9 @@ import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
-export const PACKAGE = "@catalyst-cloud/catalyst-skills";
+export const PACKAGE = "@catalyst-cloud/cli";
+/** The package ships two commands, so npx needs the one to run named: `npx -p <package> catalyst`. */
+export const NPX_ARGS = ["-p", PACKAGE, "catalyst"];
 export const CONNECT_HINT = CONNECT_COMMAND;
 
 /** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME (used by tests) over HOME. */
@@ -39,8 +41,8 @@ export function notConfigured(reason) {
 }
 
 /**
- * Run one catalyst-skills verb. Returns { code, stdout, stderr }. The CLI is `node <cliPath>` when
- * the config recorded one that still exists, else `npx @catalyst-cloud/catalyst-skills`.
+ * Run one catalyst verb. Returns { code, stdout, stderr }. The CLI is `node <cliPath>` when
+ * the config recorded one that still exists, else `npx -p @catalyst-cloud/cli catalyst`.
  * Exits 2 (not configured) before spawning anything when the config is absent or unreadable.
  */
 export function runCli(args, { stdin } = {}) {
@@ -55,7 +57,7 @@ export function runCli(args, { stdin } = {}) {
     argv = [cfg.cliPath, ...args];
   } else {
     cmd = process.platform === "win32" ? "npx.cmd" : "npx";
-    argv = [PACKAGE, ...args];
+    argv = [...NPX_ARGS, ...args];
     shell = process.platform === "win32";
   }
   const r = spawnSync(cmd, argv, {
@@ -152,8 +154,8 @@ if (runDirectly) {
       [
         "lib/cli.mjs — shared helper for this skill's scripts (not a command of its own)",
         "",
-        "Reads ~/.config/catalyst-cloud/customer.json and runs the catalyst-skills CLI recorded there",
-        `(or npx ${PACKAGE} when no path is recorded). Exit 2 when the machine is not connected.`,
+        "Reads ~/.config/catalyst-cloud/customer.json and runs the catalyst CLI recorded there",
+        `(or npx -p ${PACKAGE} catalyst when no path is recorded). Exit 2 when the machine is not connected.`,
         "",
         `Connect first with: ${CONNECT_HINT}`,
         `Config in use: ${configPath()}`,

package/skills/catalyst-linear/scripts/lib/credential.mjs

@@ -6,12 +6,12 @@
 //
 // 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
+// catalyst 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)";
+  "npx -p @catalyst-cloud/cli catalyst login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx -p @catalyst-cloud/cli catalyst login)";
 
 /** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
 export function hasCredential(cfg) {

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

@@ -5,7 +5,7 @@ import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wants
 
 const HELP = `Usage: node scripts/move.mjs <ticket> (--slot <slot> | --state-type <type>) [--json]
 
-Moves a ticket's card. Wraps: catalyst-skills write state. Spends one unit of the daily write budget.
+Moves a ticket's card. Wraps: catalyst write state. Spends one unit of the daily write budget.
 
   <ticket>              the Linear identifier, e.g. KEY-123
   --slot <slot>         one of the eleven slots: dispatch, intake, research, plan, implement,

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

@@ -6,7 +6,7 @@ import { parseFlags, parseJson, relayStderr, runCli, usage, wantsHelp } from "./
 
 const HELP = `Usage: node scripts/read-ticket.mjs <ticket> [--comments] [--source replica|api] [--json]
 
-Reads one ticket record. Wraps: catalyst-skills query issue.
+Reads one ticket record. Wraps: catalyst query issue.
 
   <ticket>               the Linear identifier, e.g. KEY-123
   --comments             also print every comment (id, author, time, body)

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

@@ -6,7 +6,7 @@ import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wants
 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.
+Wraps: catalyst query search.
 
   <terms>       one or more words; matched against identifiers, titles and names
   --limit <n>   max rows (default 50)

package/skills/catalyst-onboard/SKILL.md

@@ -1,79 +1,59 @@
 ---
 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. Starts with the coding account, then the project, the integrations and the person's connected accounts, each repository's settings file, and ends with one real ticket moving. Reads each part of the setup with the instrument that owns it, does every step a key can do through the catalyst 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:*) Bash(npx -p @catalyst-cloud/cli catalyst:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
+  Set up Catalyst Cloud and say whether setup is working. Walks a person from nothing to their first ticket running, one step at a time: the coding account, the project, the integrations and connected accounts, each repository's settings file, then one real ticket moving. Also logs this machine in, reads the readiness verdict with who can fix each failure, and checks the optional local replica. Use when someone says "set me up", "onboard me", "I just signed up", "get me started", "what do I do first", "log me in", "which account is this machine on", "am I set up", "what is missing", "why does nothing happen" or "is the replica running", when a login expired, or when a skill script exits 2 saying this machine is not connected. Does every step a key can do through the catalyst CLI, hands over the exact page for the steps only a browser can do, and never claims a step it did not watch succeed.
+allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.1 — written in this repository for customer accounts -->
 
 # Onboard me
 
-You are the guide a new member gets on their first day with Catalyst Cloud. You take one person from "the skills are installed" to "a ticket is running on my own workspace", and you do it the way a good colleague would at their desk: one step at a time, one question at a time, saying why each step matters, and checking that it landed before you go on. You never print the whole ladder at them, and you never batch several steps into one turn.
+You are the guide a new member gets on day one and comes back to when they ask whether setup still works: one step and one question at a time, saying why each step matters and checking it landed. The path has five stops, in order: a **coding account**, one **project** (which needs the Linear integration first), the **integrations** and the person's own **connected accounts**, each repository's **settings file**, then a green `ready` with **one real ticket moving**.
 
-The path has five stops, in this order: a **coding account** the work will run on, one **project** (a Linear team plus its repositories, which needs the Linear integration first), the **integrations** and the person's own **connected accounts**, each repository's **settings file**, and then a green `ready` with **one real ticket moving**. `node scripts/where-am-i.mjs --next` always says which stop you are at; your memory of the last turn never does.
+**Words:** **Workspace** is the person's whole cloud account (a command that prints `Tenant:` means it). **Project** is one Linear team plus its registered repositories. **Integration** is a workspace connection (Linear, the GitHub App); a **connected account** is the person's own login. **Coding account** is the AI provider login the work runs on.
 
-## How a turn goes
+## Which branch you are on
 
-1. Run `node scripts/where-am-i.mjs --next` and read the one line it prints. If a `note:` line follows it, say the note in one clause in the same turn (a cancelled account is kept for reporting, not used, never re-tokened); it is information, not a task.
-2. Say, in one or two sentences, what that step is for. The person should always know why they are doing it.
-3. Ask one question, or do one thing. If it is a command a key can run (the script's `do:` line), run it now without asking whether to, and show the lines it printed. If it needs a browser, hand over one link, one action named the way the page names it, and say what you will check when they are back.
-4. Stop. Wait for their answer.
-5. When they answer, run the script again and read them the part that should have changed. If it changed, say so and move on. If it did not, refresh the contract once (`catalyst contract --refresh`) and read it again; if it still did not, say what the page told them and what the instrument says, and ask what they saw.
+- **"Am I set up?", "what is missing?", "why does nothing happen?"** Run `node scripts/check.mjs`, read it with `references/reading-ready.md`, and end with the verdict and the who-can-click-what list.
+- **Not connected, a login expired, "which account is this?"** `references/connecting-this-machine.md`.
+- **"Is the replica running?", or local SQL.** `node scripts/local-sync.mjs`, then `references/local-sync.md`.
 
-Two or three short sentences per turn is the right size. A turn that lists every part's verdict is a wall of status, not help. The full report exists for you to read, not to paste.
+## How a turn goes on the path (first day, "what do I do first")
 
-## Run first
+1. Run `node scripts/where-am-i.mjs --next` and read its one line; trust it over your memory of the last turn. A `note:` after it is worth one clause.
+2. Say what the step is for.
+3. Ask one question or do one thing. Run a `do:` command a key can run and show its output; hand over a browser step as `references/what-the-browser-owns.md` says.
+4. Wait for the answer. Two or three short sentences a turn; the full report is for you, not to paste.
+5. Re-run the script and read back the part that should have changed. Still unchanged after one `catalyst contract --refresh`: report both what the page said and what the instrument says.
 
-Scripts are run, never read. Each prints `--help`.
+## Run first
 
-- `node scripts/where-am-i.mjs --next`: the single next step, with who owns it and where.
-- `node scripts/where-am-i.mjs`: every part in the order above, each with its instrument, its verdict, and for anything unfinished who can fix it and the page it is on. Works before the machine is connected.
-- `node scripts/where-am-i.mjs --json`: the same document for you to branch on.
-- `node scripts/local-sync.mjs`: optional local replica and event sync status. Run `--start` only after the person chooses local sync.
+Scripts are run, never read; each prints `--help`.
+- `node scripts/where-am-i.mjs [--next] [--json] [--repo <path>]`: every part of setup with its instrument, verdict, and who can fix what is unfinished; works before the machine is connected. A `note:` names a cancelled coding account, old-runtime leftovers (`catalyst legacy`), or a named checkout's agent-setup offers.
+- `node scripts/check.mjs [--json]`: the `catalyst ready` verdict, with fix and owner under each failure. Exit 0 READY, 1 NOT READY, 2 not connected.
+- `node scripts/local-sync.mjs [--start]`: the optional local replica and event cache; `--start` only once chosen.
 
 ## Load on demand
 
 | when | read |
 | -- | -- |
-| walking the steps: what each is for, what to ask, what to read back, when it is done | `references/the-one-path.md` |
-| the coding account: which kinds exist, what each one asks for, a cancelled or ended one | `references/choosing-a-coding-account.md` |
-| the script says a coding account needs a new credential | `references/replacing-a-credential.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` |
-| anything reports not ready, or you are about to say who should fix something | `references/who-fixes-what.md` |
-| the repository's settings file, `.catalyst/catalyst.toml`, and its approval | `references/declaring-a-repository.md` |
-| the `host` part is not ok, or you are about to say work can run | `references/what-a-phase-needs.md` |
-| the person chooses an optional local event and replica cache | `references/local-sync.md` |
-| the person asks what Catalyst 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` |
-| 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` |
-
-## Words
-
-Use the product's words, and name the page label Settings shows today when it differs. **Workspace** is the whole customer account. **Project** is one Linear team plus the repositories registered to it. **Repository** is one `owner/name`. **Integration** is a workspace-level connection, the Linear connection or the GitHub App (the page is Settings → Connections). **Connected account** is the person's own Linear or GitHub login. **Member** is a person who can sign in. A **coding account** is an AI provider login the work runs on (Settings → AI accounts). Say "tenant" and "org" only when quoting a command's output.
+| walking the path, step by step | `references/the-one-path.md` |
+| logging in, a refused or expired login, which account this is, the Linear identity | `references/connecting-this-machine.md` |
+| anything reports not ready, a check id, or who fixes something | `references/reading-ready.md` |
+| the coding account or the `host` part, or before saying work can run | `references/what-a-phase-needs.md`; a credential to replace, `references/replacing-a-credential.md` |
+| a browser step, or confirming a page that said it worked | `references/what-the-browser-owns.md` |
+| the repository's `.catalyst/catalyst.toml` and its approval; its AGENTS.md block and agent layout | `references/declaring-a-repository.md`; `references/repository-agent-setup.md` |
+| the replica or event cache | `references/local-sync.md` |
+| installing, updating, or migrating Catalyst skills | `references/skill-sources.md` |
+| what Catalyst is, or why the first ticket did not start | the `whats-happening` skill, then `unstick` if something holds it |
 
 ## Rules
 
-- **One step, then stop.** Say what you are about to do and why, do it, show the real output, say what it means, ask the one question. Never queue several steps into one message, and never move on from a step you did not watch finish.
-- **Open with the step, not a recap.** At most one clause on what is already done ("your coding account is in place"), then the step. Never list the parts with a status each; that is the report, and the report is for you.
-- **One question has one answer.** Ask a yes-or-no, or one fact. Never offer two alternatives to choose between, and never pair a page to open with a second thing to do after it. If two things are needed, the second one waits for the next turn.
-- **Say who can do a step; do not ask whether they are that person.** The script's `person` line already says their role. "This needs a workspace owner or admin, which you are" is a statement, not a question, and it never becomes a second thing to answer.
-- **No internal labels reach the person.** Never cite a step number, a reference file, or "the script"; say what to do. The status line's `Tenant:` is their workspace; say "your workspace", never a tenant number.
-- **Name accounts by their label.** "Your Claude account, Work laptop, is ready", never a slot id or "account 2". The script prints the label when the cloud has one.
-- **Report what you observed, not what you expected.** Print the lines the command produced. "That worked" without the output is the easiest thing to get wrong here, and a person who later finds it did not work stops trusting every other step.
-- **Each part by its own instrument.** The script labels every finding with the part it belongs to. Keep that when you summarize: a project problem is never a machine problem, and re-running a local command cannot move a check that belongs to an owner, an admin, or a browser page.
-- **Not ready is a question about who.** Name which check, who can fix it, and where. If the owner is not the person in front of you, say so and stop.
-- **Never invent a count or a list.** Every number and every name comes from what a command printed.
-- **Provider consent belongs to the person in a browser.** Login approval, the workspace's Linear connection and GitHub App install, and the person's own connected accounts. Give the printed URL, then check `status`. Never claim a grant succeeded because a browser opened.
-- **Team setup is CLI work now; two steps still are not.** `team list`, `team check`, `team map`, `team adopt`, `team migrate` and `team checklist` run with the person's own login: show each preview, and pass `--yes --plan-hash` only after they approve that exact plan. `catalyst capabilities` says what this CLI can do on this cloud, and the script consults it and the person's role before it names a command or a page. Registering a repository and approving one repository's settings file are settings-page work today; route those through the browser and say plainly that it is a gap, not the design. Never guess at a route.
-- **The workspace-wide environment declaration is the one setup write you can perform.** `catalyst environment` reads it, proposes it and approves it.
-- **Local sync is opt-in.** API-backed skills work without it. Ask before running `local-sync.mjs --start`; a detached process starting is not evidence of freshness. See `references/local-sync.md`.
-- **A cancelled or ended coding account is kept, not retired.** It stays for reporting, is not used, and is never given a new token; a token minted from a live login must never land on it. Reactivating it is the person's call if the subscription comes back. Never tell anyone to retire or delete it.
-- **Their workspace, as them.** Everything goes through the CLI and the person's own login. You never name another workspace, never ask for a key you could avoid, and never see a credential or a secret's value.
-- **Ask once before you write to their machine or their repository.** Say what you found, what you will write and where, then wait for a yes.
-- **A blocked command is the person's call.** If the harness blocks `npx`, a global install, or a tool, ask or hand them the command. Never skip it silently, never edit your own permission settings.
-- **An older cloud is not a broken command.** When the CLI says the cloud is older than the bundle, say so and move on.
-- **Stop at a wall you cannot pass.** A suspended workspace, 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.
-- **Write like a capable colleague.** Plain words, short sentences, one idea each, active voice, warm and unhurried. No em dashes, no emoji, no chatbot openers or flattery, and bold only the rare thing. Reread each message before you send it.
+- **One step, then stop.** Open with the step. One question has one answer: a yes-or-no, or one fact. State who can do a step instead of asking ("this needs an owner or admin, which you are").
+- **Report what you observed.** Every number and name comes from output; `status`, not an opened URL, proves a grant landed. Name accounts by their label; no slot id, step number, file name or "the script" reaches the person.
+- **Each part by its own instrument;** a project problem is never a machine problem. Not ready is a question of who: name the check, the owner and where, and stop if that is someone else.
+- **Previews before project writes.** `team map`, `team adopt` and `team migrate` preview; pass `--yes --plan-hash` only after the person approves that exact plan.
+- **Their machine and their repository need a yes,** a login included. Say what you will write and where, then wait.
+- **Local sync is opt-in.** Every skill works through the API without it; a started process is not proof of freshness.
+- **Stop at a wall.** A suspended workspace, an inactive seat, an owner or admin needed where the person is neither, a blocked command: say what you found and who can act, then stop. An older cloud is not a broken command. A person with no account joins one by invitation from its admin.
+- **Write like a capable colleague:** plain words, short sentences, warm and unhurried.

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

@@ -1,6 +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"
+  short_description: "Set up Catalyst Cloud one step at a time, log this machine in, and say whether setup is ready and who fixes what is missing"
   default_prompt: "Use $catalyst-onboard to set me up on Catalyst Cloud, one step at a time."
 policy:
-  allow_implicit_invocation: false
+  allow_implicit_invocation: true

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

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

package/skills/catalyst-onboard/references/connecting-this-machine.md

@@ -0,0 +1,35 @@
+# Connecting this machine
+
+## Which cloud account is this machine on
+
+`catalyst status` prints the account on its `Tenant:` line, the API, and the config paths. Say "your cloud account" and its name. The credential is the only account selector; there is no `--account`. If the cloud names no account for the login, stop and say so.
+
+## Logging in
+
+Keyless is the preferred rail: `catalyst login` with no key prints a short code and a URL the person approves in a browser, or from a phone. Ask first, and run it once per code. The session refreshes silently, so they stay connected for months.
+
+A **personal key** is the fallback for a script or an unattended shell. Any active member mints one at Settings → API keys. The environment form keeps it out of shell history:
+
+```sh
+CATALYST_CLOUD_TOKEN=<your-personal-key> catalyst login
+```
+
+`CATALYST_CLOUD_BASE_URL` or `--base-url` pins a non-default cloud. The account key (`ctc_acct_`) belongs to hosts and runners: a person connected with it has no name on anything their agent writes, and "what needs me" cannot mean them.
+
+## An unmatched Linear identity
+
+An unmatched Linear identity is the person's to match: `catalyst identity linear status`, then `catalyst identity linear options`; they pick their own listed identity and you run `catalyst identity linear set <linearUserId>`. An identity someone else claimed, and an inactive seat, need an owner or admin at Settings → Members. Connecting Linear personally does not set the identity: the identity and the personal grant are two different stored facts. Until the identity is matched, "what needs me" shows everyone's asks.
+
+## What login writes
+
+`~/.config/catalyst-cloud/customer.json` (mode 0600) holds the credential, the resolved account and person, and this CLI's path for skill scripts; `contract.json` beside it caches the contract. `CATALYST_SKILLS_HOME` moves the directory. With no home directory (a container, or `HOME` unset or `/`) the config lands under `/`: stop, confirm this is the person's own machine, and set `CATALYST_SKILLS_HOME` if it is. Login installs no skills (`references/skill-sources.md`).
+
+## When login fails
+
+- **"Your login expired or was revoked."** One fresh `catalyst login`.
+- **A 401 on the key rail.** A stale, mistyped or revoked key: mint a new one at Settings → API keys.
+- **A 403 on the contract naming an older cloud.** The cloud lacks personal-key access: update the cloud, or use the account key until then.
+- **A line naming two contract versions.** `npm install -g @catalyst-cloud/cli@latest && catalyst login` before using the other skills.
+- **A refusal naming `jwt-no-membership`.** The cloud learns of a person at their first sign-in to the app. Have them sign in once, then log in again. If it repeats, their seat is inactive and an owner or admin activates it.
+
+Retry a failed login once, by hand, after the fix. A key goes into the login command or `CATALYST_CLOUD_TOKEN` and nowhere else: never a ticket, a transcript, or a file you write. After a bundle update, the next command prints a one-line notice; read it to the person if they are watching.

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

@@ -1,20 +1,17 @@
 # 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.
-
-This is step 8 of `references/the-one-path.md`. Offer to draft the file from the repository's own build files, say which files you will read and what you will write, and wait for a yes before you write anything. If the repository already has one, verify it against the inventory below instead of rewriting it.
+The cloud containers build and test the repository and 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. Say which files you will read and what you will write, and wait for a yes. An existing file gets verified against the inventory, not rewritten.
 
 ## 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. Read these files directly; the inventory needs no git command.
-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/catalyst.toml` and open a pull request. Use that exact path. The cloud reads no other file, and an older `catalyst.env.json` is ignored. Once the pull request merges, each push to the default branch that touches the file makes the cloud read it and propose it as a new revision. A tenant owner or admin opens Settings → Repositories → the repository → Environment → Setup declaration and clicks Approve this revision. The person enters the values on the same page's Environment variables and Secrets tabs.
+1. Start from what builds and tests the repository: the README's setup section, the scripts in `package.json` or its equivalent, and CI's build and test steps. A name none of them reads does not belong in the file.
+2. Tie each name to 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. Leave out platform bindings and deploy-only secrets, since containers build and test but never deploy, unless the person says the build needs one.
+4. Write the names into `.catalyst/catalyst.toml`, the only file the cloud reads, and open a pull request. Each merged change to it is proposed as a new revision, which an owner or admin approves at Settings → Repositories → the repository → Environment → Setup declaration → Approve this revision; the person enters values on that page's Environment variables and Secrets tabs.
 
 ## The file's shape
 
-`[project]` with `linear_team` is required. Every other section is optional. The names a build needs go under `[environment]`:
+`[project]` with `linear_team` is required; every other section is optional.
 
 ```toml
 #:schema https://staging.catalystcloud.dev/schemas/catalyst.schema.json
@@ -36,11 +33,4 @@ name = "install"
 run = ["npm", "ci"]
 ```
 
-- `linear_team` is the key of the Linear team this repository's work belongs to.
-- Each `[[environment.variables]]` entry names one variable and says whether it is `required`. Add `secret = true` for a secret. Names only: a value never goes in this file.
-- `[[environment.setup]]` steps carry this repository's own install commands. `run` is an argument list, not a shell string, and `name` is kebab-case. `verify` steps have the same shape and carry the test commands. `toolchains`, `system_packages`, `services` and the other `[environment]` tables are optional; the schema lists their fields.
-- The `#:schema` line lets an editor check the file as you type.
-
-## After the merge
-
-`catalyst 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 workspace-wide declaration is separate; `catalyst environment` handles it (also step 8 of `references/the-one-path.md`).
+`linear_team` is the Linear team's key. `run` is an argument list, not a shell string, and `name` is kebab-case; `verify` steps share the shape and carry the test commands. The schema lists the optional tables (`toolchains`, `system_packages`, `services`). After the merge, `catalyst ready` reports `environment_declared` with the next step.

package/skills/catalyst-onboard/references/local-sync.md

@@ -1,15 +1,27 @@
-# Optional local events and replica
+# The optional local replica and event cache
 
-**For:** a person who wants an on-machine event file and searchable replica. The normal API-backed skills work without this, so ask before starting a background writer.
+The replica is an on-machine SQLite copy of the account for cheap repeated reads and ad hoc SQL; the event cache holds recent events. Every skill works without them through the API, which is origin-fresh. Start a background writer only when the person asks for local data.
 
-**You run:** `node scripts/local-sync.mjs` to show the current local state. Only if the person opts in, run `node scripts/local-sync.mjs --start`. The script uses `catalyst replica start --detach`, whose writer also starts the local event cache. It waits up to 90 seconds; `--wait <seconds>` sets a bounded wait from 0 to 300.
+## The replica's exit codes
 
-**Read back:** `Local sync current` only when both the replica and event cache have live writer heartbeats and each cursor equals its own cloud head. A detached process starting, one fresh heartbeat alone, or replica freshness alone does not prove event freshness. `catalyst replica status --probe --json` checks the replica cursor; `catalyst events status --probe --json` checks the separate event cursor. Either command can report stale or unknown; unknown means the cloud comparison could not be proved, not that the cache is stale. Exit 0 means current, 1 stale, 2 unknown or not connected, and 3 absent. Do not tell the person local data is current unless the combined check says so.
+`catalyst replica status` needs no network. Exit 0 is fresh (a live writer, a heartbeat under 15 seconds, a cursor), and skills read the replica. Exit 1 is stale and 3 is absent; skills read the API, and `catalyst replica start --detach` restarts a stale one. Exit 2 is not connected (`references/connecting-this-machine.md`). `--probe` adds one network call comparing the local cursor with the cloud head. Every read verb names its source on standard error.
 
-**Owner:** you check and, with the person's opt-in, start. The local writer is optional. A reboot recovery service is separate work; if this machine restarts, recheck status before relying on local data.
+## Checking and starting both
+
+`node scripts/local-sync.mjs` shows the local state. Only after the person opts in, `--start` starts the replica and event cache writers and waits up to 90 seconds (`--wait <seconds>`, 0 to 300).
+
+Say `Local sync current` only when both writers have live heartbeats and each cursor equals its cloud head. A detached process starting, one fresh heartbeat, or replica freshness alone does not prove event freshness. `catalyst replica status --probe --json` checks the replica cursor; `catalyst events status --probe --json` checks the separate event cursor. Unknown means the comparison could not be proved, which is not stale. The script exits 0 current, 1 stale, 3 absent, and 2 for "not connected" or "unknown", with a printed reason. After a restart, check again before relying on local data.
 
 ## First ticket event
 
-Ask before starting the local writer. Before the person moves a card, run `node scripts/local-sync.mjs --start` after they opt in and wait until it reports current. Then run `catalyst events status --probe --json` and record its `cursor` as `<cursor-before-move>`. Move the card only after this baseline is captured. Once the card is moved, run `catalyst events wait-for --ticket <ticket-identifier> --after <cursor-before-move> --timeout 300` with the identifier `explain` printed. Do not guess an event type. The explicit cursor lets `wait-for` find the event if it reached the local cache before the command began.
+Before the person moves a card, run `node scripts/local-sync.mjs --start` (after they opt in) and wait until it reports current. Then run `catalyst events status --probe --json` and record its `cursor` as `<cursor-before-move>`. Move the card only after this baseline is captured. Then run `catalyst events wait-for --ticket <ticket-identifier> --after <cursor-before-move> --timeout 300` with the identifier `explain` printed, and no guessed event type. The explicit cursor finds an event that reached the cache before the command began.
+
+Exit 0 prints a matching event after the baseline, proving it reached this machine's cache. Exit 1 means no matching cached event arrived within five minutes; recheck `node scripts/local-sync.mjs` and report stale or unknown evidence without inferring a cloud or webhook failure. Exit 3 means the event cache is absent; ask before starting it. Other errors are unknown. `explain` stays the API-backed answer to why a ticket can or cannot run.
+
+## The writer
+
+`catalyst replica --help` lists `start`, `stop`, `sql` and `schema`. It needs Node 22.15 or newer, or bun 1.4 or newer, and its files stay bounded under `~/.config/catalyst-cloud/`. The first start seeds the whole snapshot before going live, so `status` reads stale until the cursor appears; ask again after the live line, or watch `status --probe` count down. The lock refuses a second writer on the same file.
+
+The writer backs off after a failed snapshot pull and gives up after five consecutive snapshot failures; `catalyst replica status` and `catalyst ready` then name the stopped state, the last error and the restart command, and the file reads stale (exit 1).
 
-Exit 0 prints a matching event after the recorded baseline and proves it reached this machine's cache. Exit 1 means no matching cached event arrived within five minutes; recheck `node scripts/local-sync.mjs` and report stale or unknown evidence without inferring a cloud or webhook failure. Exit 3 means the event cache is absent; ask before starting it. Other errors are unknown. `explain` remains the API-backed source for why a ticket can or cannot run.
+To survive a reboot, run `catalyst replica start` without `--detach` under the platform's supervisor: a launchd agent with `KeepAlive` on macOS, a systemd user unit with `Restart=on-failure` on Linux (plus `loginctl enable-linger $USER` to run while logged out), or a Task Scheduler task at logon on Windows.

package/skills/catalyst-onboard/references/reading-ready.md

@@ -0,0 +1,79 @@
+# Reading `catalyst ready`: what each check proves and who fixes it
+
+Read this before telling a person something is not ready or what to do about it. `catalyst ready` prints one verdict over the machine and every project; `node scripts/check.mjs` adds each failure's fix and owner and a "who can click what" list.
+
+## The parts, and the instrument that owns each
+
+| part | instrument | a pass does not prove |
+| -- | -- | -- |
+| **machine** | `catalyst status`, and the machine checks of `ready` | anything about the cloud account |
+| **person** | `catalyst me`, `catalyst connections personal <linear|github> status` | an active seat (an owner or admin fixes it in Settings → Members) |
+| **account** | `catalyst contract --path account` (a resolved Linear workspace) | that the GitHub App is installed |
+| **project** | `catalyst team list`, then `team check <KEY>` and the `team:` checks of `ready` | that an unchecked team is ready |
+| **repository** | `catalyst contract --path merge.repositories` | that it is active, attached to a project, or declared |
+| **repository declarations** | `environment_declared` in `catalyst contract --path teams` | that the values behind the names exist |
+| **coding accounts**, **host** | `references/what-a-phase-needs.md` | that a phase has headroom |
+
+⛔ **An empty contract project list means nothing is mapped yet**; pick one from `catalyst team list`. `team check --all` checks every team and may file an ask for each. ⛔ **A registered repository is not a dispatchable one**; if a card does not start, `catalyst explain <ticket>` names the reason.
+
+## Triaging NOT READY
+
+Split the verdict first. In `catalyst ready --json`, an id that begins with `team:` is a **project** finding; the rest are **machine** findings. Report the two groups separately, machine first, each with its owner, its `pass`, `fail` and `unknown` counts, and when each team verdict was computed (`teams[].readiness.checkedAt`, null before any pass).
+
+- **A machine check failed:** the person's, here, now. Do its `fix` line.
+- **A project check failed:** name the check, the project and the `who`. A mapping is repaired with `catalyst team check`, `team map` or `team adopt`; a Linear connection, permission or team setting in a browser. Re-running `ready` fixes nothing.
+- **A note** never moves the verdict; waiting is not failing, and unknown is not a pass.
+
+End every readiness answer with the verdict and the who-can-click-what list, in that order. Run each check once; waiting for one to clear is the project owner's watch (`run-this-project`).
+
+## The checks
+
+The contract's `readinessChecks[]` is the list of record, with each check's severity; `teams[].readiness` holds each team's states. A check listed there and not here is newer than this page: `node scripts/check.mjs` still prints its line, fix and owner, so read that and say you did.
+
+A team is `ready`, `degraded`, `blocked` or `unchecked` (no pass yet, a note). Severity decides whether a failing check blocks, degrades or only informs; an unknown (the engine could not look) degrades regardless. Readiness is stamped with the mapping revision it read, so a stale verdict shows as stale.
+
+| check id | proves | when it fails | who clicks |
+| -- | -- | -- | -- |
+| `oauth_scope` | the Linear connection has the permissions it needs | re-authorise it | owner or admin, in settings |
+| `token_live` | the Linear connection is accepted now | reconnect if expired, revoked or never connected; re-check if Linear was unreachable | owner or admin |
+| `team_visible` | Catalyst can see the team | usually it went private: grant access in Linear | owner or admin, in Linear |
+| `mapped_states_exist` | every mapped stage still exists | `catalyst team map <KEY>`; `stages_pending_write` means a mapping was just saved, so wait | owner or admin |
+| `mapping_total` | every stage Catalyst moves tickets into is mapped | map them ("absent": never mapped) | owner or admin |
+| `types_compatible` | each load-bearing stage is the right kind (dispatch and intake unstarted or backlog, PR started, done completed, canceled canceled) | map a stage of the right kind | owner or admin |
+| `labels_present` | Catalyst's labels exist | none: they are created on first use | nobody |
+| `writes_land` | Catalyst has written to the team | `no_write_observed` clears on the first move; a refused write: check the connection and permissions | owner or admin when refused; otherwise nobody |
+| `webhook_covers_team` | the team's events arrive | `no_delivery_observed` clears once a registered repository's events flow | owner or admin, by registering the repository |
+| `hosts_current` | no connected host runs an older mapping | `references/what-a-phase-needs.md`; `no_host_connected` is waiting | whoever runs that host |
+| `environment_declared` | the default repository's `.catalyst/catalyst.toml` is ingested, valid and approved | the reason names the step: register a default repository, commit or fix the file, or approve it (`references/declaring-a-repository.md`) | owner or admin, except committing the file, which is whoever can push |
+| `tools_resolvable` | every MCP server and CLI the declaration names resolves | `tool_reference_unresolved`: add the secret or fix the declaration; `toolchain_cli_missing` is not self-service | owner or admin, in the declaration or Settings → Environment |
+| `reviewer_required` | the repository can merge under its policy | a strict policy with no reviewer: configure one at Settings → Repositories → Code reviews, or relax the policy; only the merge waits | owner or admin, in settings |
+| `reviewer_configured` | a code reviewer is configured at all | configure one there; a fail never blocks or degrades | owner or admin, in settings; nobody is required when it fails |
+
+## The machine checks the CLI adds
+
+Each failing line prints its own fix.
+
+| id | proves |
+| -- | -- |
+| `runtime` | this runtime can run the CLI: Node 22.15+ or bun 1.4+. The fix, `npx -y -p @catalyst-cloud/cli catalyst runtime install`, puts a pinned Node in the CLI's cache and leaves the default Node alone |
+| `config` | `customer.json` exists and loads (`references/connecting-this-machine.md`) |
+| `contract` | the contract is cached and its major version is in this bundle's range |
+| `bundle` | the CLI meets the account's minimum version; a note |
+| `cliPath` | the CLI path recorded at login still exists |
+| `skills` | the Cloud pack's copied skills are all present; a pack installed another way reads as a note (`references/skill-sources.md`) |
+| `cliRelease` | the CLI is not behind the newest release; a note |
+| `skillsRelease` | the skill files are not behind the newest bundle; "could not run" means the registry was unreachable |
+| `sdk` | the SDK loads, so the replica and the watch are available; reads work through the API meanwhile |
+| `replica` | the optional replica is fresh; a note (`references/local-sync.md`) |
+
+## Setting up one team at a time
+
+A team receives work once its stages are saved. Saving one team changes no other team's stages or tickets; only the labels Adopt creates are shared. Once saved, tickets in its dispatch stage start, so pilot on a low-stakes team and first move anything there that should wait back to Backlog. Nothing reads `gitAutomation` in the contract.
+
+Each action exists in the terminal and on `<their cloud>/settings/linear-teams`:
+
+- **Check** (`catalyst team check <KEY>`, Re-check) saves the team's verdict, changing no ticket or mapping, and files one setup ticket for an admin if something is missing.
+- **Map** (`catalyst team map <KEY>`, Map my stages) saves a mapping from the team's existing stages and creates nothing in Linear.
+- **Adopt** (`catalyst team adopt <KEY>`, Adopt the Catalyst workflow) creates the missing stages and Catalyst's labels with the admin's own Linear authorisation, including the hold label a failed phase uses when the team has no remediate stage (`teams[].labels.hold`). The label alone means nothing failed.
+
+Map when the team's stages already cover the work, Adopt when they do not.