@catalyst-cloud/cli 0.9.5 → 0.13.1

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.9.5 — 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.

package/skills/catalyst-onboard/references/replacing-a-credential.md

@@ -1,51 +1,26 @@
 # Replacing a coding account's credential
 
-When the script prints "<provider> account <slot> needs a new credential", replace that account's credential on its own page. Do not enroll a second account. A second account is a duplicate, and the dead one stays in place.
-
-## Why an account needs one
-
-The script flags an account in three cases:
-
-- it is quarantined;
-- it is expired or revoked;
-- its last polls failed on the credential itself, such as `no_access_token`, three or more times in a row. The script can see this only when the cloud reports each account's polls.
-
-Other accounts can be healthy at the same time. The contract can still say `enrolled`, so that line alone never proves every account works.
-
-## Who does it
-
-A tenant owner or admin, in the browser. The person copies the credential and pastes it. You never read it, print it, or paste it. The script prints the page link; use it, and never type a host.
+When the script prints "<provider> account <slot> needs a new credential" (quarantined, expired, revoked, or three or more polls failed on the credential), replace that account's credential on its own page. Do not enroll a second account. It would be a duplicate beside the dead one. A workspace owner or admin does it in the browser, from the link the script prints; the person copies and pastes the credential, and you never read, print or paste it.
 
 ## Codex
 
 The person runs these steps on their own machine:
 
 1. Run `codex login` and choose "Sign in with ChatGPT".
-2. The login writes `~/.codex/auth.json`. If `CODEX_HOME` is set, the file is `$CODEX_HOME/auth.json`. On macOS, `pbcopy < ~/.codex/auth.json` copies it.
-3. In the browser, open Settings → AI accounts, then open that Codex account.
+2. The login writes `~/.codex/auth.json`, or `$CODEX_HOME/auth.json` when `CODEX_HOME` is set. On macOS, `pbcopy < ~/.codex/auth.json` copies it.
+3. In the browser, open Settings → AI accounts, then that Codex account.
 4. Paste the file into "Replacement auth.json contents", then press Replace credential.
 
-Then you run `node scripts/where-am-i.mjs` again and read back the `coding accounts` part.
-
-Say these two things plainly:
-
-- Do not enroll a second account. Replace the credential on the one the script named.
-- Catalyst takes over this login. Its refresh token is single-use, so the copy on this machine stops working once Catalyst uses it. To use Codex locally, sign in to Codex again, separately, after the replacement.
+Say plainly that Catalyst takes over this login: its refresh token is single-use, so the local copy stops working once Catalyst uses it, and to use Codex locally they sign in to Codex again, separately, after the replacement.
 
 ## Claude
 
-The same page takes a Claude account's new credential. Its field is "Replacement setup token". `claude setup-token` mints a token for whichever Claude account the terminal is logged into, not for the slot. So first match them: read the slot's account on the AI accounts page (its label or email), then have the person run `claude` and `/status` to see the email the terminal is logged into. If they differ, stop, and log in to the slot's account first. Only then run `claude setup-token`, paste the token into that field, and press Replace credential. Then re-run the script.
-
-## A cancelled or ended account
-
-An account whose subscription is cancelled, or which has ended, is not a credential problem, and no token revives it. It stays enrolled for reporting, is not used, and is not something to retire or delete. Never replace its credential with a token from another account: that puts a working account's login onto a dead slot. If the subscription is live again, the person reactivates it on its own page.
+The field is "Replacement setup token". `claude setup-token` mints a token for whichever account the terminal is logged into, not for the slot, so match them first: compare the slot's email on the AI accounts page with what `/status` in `claude` shows, and log in to the slot's account if they differ. Then run `claude setup-token`, paste the token, and press Replace credential.
 
 ## Any other provider
 
-Replace its credential on the same page, with the credential that page asks for.
-
-## What Replace credential does
+The same page, with the credential it asks for. A cancelled or ended account is not a credential problem, and no token revives it.
 
-It stores the new credential and clears the account's quarantine in the same step. A tenant owner or admin can do it. An operator is not needed.
+## Afterwards
 
-A failed poll is recorded until the account is polled again. If the script still names the account right after the replacement, wait for the next poll and read it again. If it still names it, report both: what the page said, and what the script says.
+Replace credential also clears the quarantine; no operator is needed. Run `node scripts/where-am-i.mjs` again. A failed poll stays on record until the next poll, so if the script still names the account, wait for that poll before reporting a disagreement.

package/skills/catalyst-onboard/references/repository-agent-setup.md

@@ -0,0 +1,23 @@
+# The repository's agent setup
+
+Two CLI verbs, both on a checkout the person names, both writing only to its working tree. Nothing here pushes or reaches the cloud; the branch, commit and pull request are the person's, never on the default branch. When `catalyst capabilities` lacks `repo agents-block` and `repo agent-setup`, say the CLI is older and skip this; never paste the block by hand.
+
+Say in one clause what the report found ("CLAUDE.md carries your guidance, there is no AGENTS.md, and `.claude/skills` is a real directory"), then offer each write below after its own yes, in the same pull request as the settings file when that is open.
+
+## The Catalyst block in AGENTS.md
+
+`catalyst repo agents-block <path>` reads AGENTS.md as `absent`, `missing` (no block), `stale` (words differ from this CLI's) or `current`. `--write` creates the file, appends the block, or replaces the region between `<!-- catalyst:start -->` and `<!-- catalyst:end -->`; a rerun changes nothing. The block says the repository is worked through Catalyst and names the skills that explain the process; it carries no process of its own, so it never goes stale with the pipeline.
+
+## The portable layout
+
+`catalyst repo agent-setup <path>` reports AGENTS.md (size, block state), CLAUDE.md (whether a line is exactly `@AGENTS.md`, and its own line count), `.agents/skills|rules` and `.claude/skills|rules` (absent, real directory, or symlink and target), and other agent files it saw (`.codex`, `.cursor`, `GEMINI.md`), then one verdict:
+
+- **portable**: AGENTS.md is canonical, CLAUDE.md imports it, each `.claude/` twin is absent or a relative symlink into `.agents/`. Offer only the block if it is missing.
+- **convertible**: the report lists the plan (CLAUDE.md's guidance moves into AGENTS.md and CLAUDE.md becomes `@AGENTS.md` plus Claude-only notes; `.claude/skills|rules` move to `.agents/` behind a relative symlink). `--apply` does exactly that.
+- **needs a hand merge**: both directories are real, or a symlink points elsewhere. `--apply` refuses and names each blocker.
+
+Portable means one AGENTS.md serves every coding agent, so a second harness finds the same instructions and skills without a drifting copy.
+
+`--with-check` writes `scripts/agents-md-check.mjs`, a dependency-free CI script that fails when CLAUDE.md stops importing AGENTS.md, a `.claude/` twin stops being a relative symlink into `.agents/`, AGENTS.md outgrows 120 lines or 16 KiB (`AGENTS_MD_MAX_LINES`, `AGENTS_MD_MAX_BYTES`), or a backticked path it cites is gone. The person wires it into CI.
+
+**Read back:** rerun `catalyst repo agent-setup <path>` after any write. Exit 0 is portable with the block current; exit 1 lists what is still open.

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

@@ -1,38 +1,32 @@
 # 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.
+The installer at the cloud's `/install.sh` (the app's setup page shows the command) installs both packs from exact commits, stops on any same-named skill it does not recognise, and on a home install schedules a daily refresh. Re-run it to refresh or repair; the table is 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-cloud-skills` | Cloud account 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.
+Install each pack by one method: `npx skills` or its plugin.
 
 ## 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.
-
+Global (`-g`) installs go to `~/.agents/skills/`, linked from `~/.claude/skills/`, with the lock at `$XDG_STATE_HOME/skills/.skill-lock.json` or `~/.agents/.skill-lock.json`. Project installs go to `.agents/skills/` and `.claude/skills/` with `skills-lock.json`. Links are relative; resolve each with `readlink -f` before comparing paths.
 
-The `npx skills add --all` command replaces existing same-named directories and links. Before a first install or refresh on an existing machine, read the lock above. Inspect every same-named agent destination. Proceed only when each destination is absent or a verified, unmodified copy of the intended pack or its symlink. A lock entry alone does not verify every destination. Keep independent, changed, or uncertain copies in place and resolve the conflict before adding either pack. Do not schedule raw add commands as an unattended refresh.
+`npx skills add --all` replaces same-named directories and links. Before running it on an existing machine, inspect every same-named destination and proceed only when each is absent or a verified, unmodified copy of the intended pack (a lock entry verifies nothing on disk). Resolve any other copy first. Schedule only the installer, never raw add commands.
 
 ## Is each pack there
 
-`catalyst 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).
+`catalyst ready` checks the Cloud pack only. Look for `catalyst-onboard/SKILL.md` (Cloud) and `research-codebase/SKILL.md` (development) in the intended directory.
 
-## Migrate an existing installation
+## Migrating 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`. For a copied skill whose lock source names the deprecated Catalyst runtime repository, use `npx skills remove <name> -g -y` only when every existing global agent path is that canonical copy or a symlink to it. Omit `-g` for a proven project install and inspect every same-named project agent path first. The command removes that name across agent directories. Leave independent or uncertain copies in place and report the conflict.
-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, the lock for each changed scope, and the destination skill folders. Start a new agent session after changing Claude plugins.
+1. `claude plugin list`: record whether `catalyst-dev@catalyst` is installed, and at which scope.
+2. Inspect the home and project skill directories separately, with their locks and provenance markers; a folder name does not prove its source, and `.claude/skills` may link elsewhere.
+3. Remove only `catalyst-dev@catalyst`: `claude plugin uninstall catalyst-dev@catalyst --scope user --keep-data --yes`. For a copied skill whose lock source is the deprecated Catalyst runtime repository, `npx skills remove <name> -g -y` (no `-g` for a proven project install), and only when every agent path with that name is that copy or a link to it. Remove by name, never with `--all`.
+4. Install the replacement packs in the intended scope with the commands above.
+5. Read back the plugin list, each changed lock and the folders, and start a new agent session after a plugin change.
 
-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.
+Keep any Catalyst checkout, local project data, and same-named skill of unknown source; if source or scope is ambiguous, stop and report it.