@catalyst-cloud/cli 0.13.0 → 0.13.1

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.

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

@@ -1,115 +1,59 @@
 # The one path
 
-The steps run in the order a person can act on them, and the order says why: the coding account first, because nothing runs without one and it needs nothing else; the Linear integration, because the project list cannot be read without it; one project; the GitHub App and the repository it will work in; the person's own connected accounts, GitHub last because a registered repository is the proof the App is usable; the repository's settings file; then the first ticket. Each step is the cheapest place to catch the failure the next one would otherwise hide.
-
-Walk them **one at a time**. Before each step say what it is for, in a sentence, and ask one question or do one thing. After it, show what actually came back. `node scripts/where-am-i.mjs --next` decides which step you are on, never your memory of the last turn. Two or three short sentences per turn is the right size.
-
-Each step states: what it is for, what you ask or run or hand over, **what you read back to prove it landed**, and **who owns it**.
+The steps run in the order a person can act on them, each the cheapest place to catch what the next would hide. The script prints each step's owner and link; this page adds why it matters, what to ask, and its trap. Browser handovers follow `references/what-the-browser-owns.md`.
 
 ## 0. Where are we
 
-**For:** starting from the truth instead of an assumption. A person arrives having done anything from nothing to most of it, and the installer has usually connected the machine already.
-
-**You run:** `node scripts/where-am-i.mjs --next`. Read the one line, then say in a sentence which step is next and whose it is. Do not paste the full report.
-
-**Owner:** you.
+Run `node scripts/where-am-i.mjs --next` and say which step is next and whose it is.
 
 ## 1. Connect this machine
 
-**For:** giving this machine a credential, so every later read is the person's own. The installer normally did this; you are here only when the script says the machine is not connected.
+Only when the script says the machine is not connected: ask "Shall I start the login now?", then follow `references/connecting-this-machine.md`.
 
-**You ask:** "Shall I start the login now?" On a yes, run `catalyst login`. It prints a short code and a URL. The person approves it in a browser, from a phone if this machine has none. Do not offer the key form; it exists for a person who already holds a personal key and says so.
+## 1b. Leftovers of the old local runtime
 
-**Read back:** the `Connected to …` and `Connected as …` lines, then the script again so the machine part flips.
-
-**Owner:** you run it; the approval is the person's, in a browser, and always will be. Do not re-run the command while a code is outstanding. If it refuses, stop and use the `connect-me` skill.
+Only when the script notes them (from the CLI's fixed list; current jobs are never on it); left in place they can start old jobs or shadow current commands. Ask once, recommending it: "Shall I remove the old runtime's leftovers now? It keeps your data folders." On a yes, run `catalyst legacy --remove --yes` and read back its `removed:` and `re-checked:` lines; offer `--data` separately. On a no, the note stays.
 
 ## 2. A coding account
 
-**For:** what the work runs on. Catalyst runs each stage of a ticket on an account the person owns, at their own rate, under their own name. With none enrolled, every later step can be finished and nothing will ever start.
-
-**You ask:** "Do you already have a coding account you want Catalyst to run on?" Then `references/choosing-a-coding-account.md`: the four kinds, what each asks for, how to enrol one, and what to do with an account that is out of rotation, needs a new credential, or has ended.
-
-**Read back:** the `coding accounts` part: an enrolled, active account, named by its label. A cancelled or ended one is kept for reporting, not used, never re-tokened, and does not hold this step up.
-
-**Owner:** a workspace owner or admin, in a browser, on the AI accounts page. Nothing you run ever sees the credential.
+Each stage of a ticket runs on an account the person owns, at their own rate, under their own name; with none, nothing ever starts. It needs nothing else, so it comes first. Ask "Do you already have a coding account you want Catalyst to run on?", then follow `references/what-a-phase-needs.md`.
 
 ## 3. Connect the Linear integration
 
-**For:** the workspace. Until the workspace's Linear connection exists, no project can be read or mapped. Say that this is the one connection the whole workspace shares, made once by an admin.
-
-**You hand over:** `<their cloud>/settings/connections` (the Integrations page; Settings labels it Connections today), and say: connect Linear. It sends them to Linear to authorise and brings them back.
-
-**Read back:** after they say it is done, re-run the script and read them the `account` line. A resolved workspace is proof. If it still reads unresolved, run `catalyst contract --refresh` and read it again.
-
-**Owner:** a workspace owner or admin, in a browser. **Browser by construction**: it is an authorization grant, and no key can perform one.
+The one Linear connection the whole workspace shares, made once by an owner or admin on `<their cloud>/settings/connections`; no project can be read without it.
 
 ## 4. Pick one project, and map its stages
 
-**For:** the project. A project is one Linear team plus the repositories registered to it. Until a project's stages are mapped, a card moved into it does nothing at all; this is the single most common reason a new workspace sees no activity.
-
-**You run:** `catalyst team list` to see the teams without checking readiness. Have the person choose one team key. Then `catalyst team map <KEY>`, or `catalyst team adopt <KEY>` if they want Catalyst's stages created for them: each prints a preview; show it, and pass `--yes --plan-hash <hash>` only after they approve that exact plan. Run `catalyst team check <KEY>` only for the selected team when you need its verdict. The same steps exist on `<their cloud>/settings/linear-teams` (**Map my stages**, **Adopt the Catalyst workflow**) for a person who prefers the page.
-
-**Read back:** re-run the script and read the `projects` line: the verdict and any failing checks by name. A project that reads `blocked` is not set up whatever its gate says; the script names the blocking checks and their owner. Three of them are Linear's own Git automation rules (in Linear: Settings → Teams → the team → Workflow → Git automation, set the named rule to No action). No Catalyst key can change those, so say so, hand it over, and afterwards run `catalyst team check <KEY>`.
-
-For manual setup, `catalyst team checklist <KEY>` prints the same lines as the browser. If it cannot read the live stages, fix the Linear connection and retry. Moving tickets out of old stages is a separate decision: preview with `team migrate <KEY>`, review source and destination ids and counts, then confirm with `--yes --plan-hash <hash>` from that preview. Retiring emptied source stages requires a later `team migrate <KEY> --retire` preview and a separate approval using its preview hash. `team adopt <KEY> --undo` likewise previews the exact stages previously created by Adopt before asking for confirmation.
+A card moved into an unmapped project does nothing, the most common reason a new workspace sees no activity. Lead with the pilot: one project changes no other (`references/reading-ready.md`, "Setting up one team at a time", which also says Map or Adopt).
 
-**Owner:** a workspace owner or admin, with their own login. You run the commands; the person picks the team and approves each write after seeing its preview. A run that exits 3 stopped before applying anything.
+`catalyst team list` shows the teams without checking readiness; the person picks one key. `catalyst team map <KEY>` or `catalyst team adopt <KEY>` prints a preview to approve before `--yes --plan-hash <hash>` (exit 3 applied nothing). Run `catalyst team check <KEY>` only for the selected team. `team migrate <KEY>`, its `--retire`, and `team adopt <KEY> --undo` each preview and need their own approval. `catalyst capabilities` says which verbs this cloud serves.
 
-⭐ **One project at a time is safe, and lead with this.** Mapping one project changes no other project's stages and moves no other project's tickets. Encourage a pilot: the project they care least about breaking.
+A `blocked` project is not set up. Linear's own Git automation rules change only in Linear (Settings → Teams → the team → Workflow → Git automation → No action); hand that over, then re-check.
 
 ## 5. Install the GitHub App
 
-**For:** the workspace's GitHub integration. Without it Catalyst can read tickets but cannot touch code.
-
-**You hand over:** the same Connections page, and say: install the GitHub App, and grant it the repository they want worked and `<org>/thoughts`. Catalyst's cloud phases write their notes to `<org>/thoughts`, where `<org>` owns the code repository. If it does not exist, they create a private repository named `thoughts`, initialized with a README, and then on the App's installation page for that org choose All repositories, or add `thoughts` to the selected repositories. The script's `repositories` part notes whether `gh` can see that repository, never that the App can reach it, so do not claim that.
-
-**Read back:** it is confirmed by step 6 succeeding. A repository cannot be registered through an App that is not installed. Say that is what you are waiting for.
-
-**Owner:** a workspace owner or admin, in a browser. Browser by construction, same reason as step 3.
+Without it Catalyst cannot touch code. On the same page, the owner or admin installs the App and grants it the repository plus `<org>/thoughts`, where cloud phases write their notes (`<org>` owns the code repository). If it does not exist, they create a private repository named `thoughts`, initialized with a README, then on the App's installation page for that org choose All repositories or add `thoughts`. The script notes whether `gh` can see that repository, never that the App can reach it. Step 6 succeeding is the proof the App is installed.
 
 ## 6. Register the repository
 
-**For:** the repository. Registering, attached to a project, is what makes a repository something that project can dispatch work into.
-
-**You hand over:** `<their cloud>/settings/repositories`, and say: add the repository, **and attach it to the project you mapped in step 4**, in the same form.
-
-**Read back:** re-run the script and read the `repositories` line. The repository appearing there proves it was registered, and only that; see `references/who-fixes-what.md` for what registration does not prove.
-
-**Owner:** a workspace owner or admin. ⛔ Registering is settings-page work today. ⛔ A repository registered without a project attached is the trap: the call succeeds, the repository is listed, and nothing can ever dispatch into it.
+On `<their cloud>/settings/repositories`, add the repository **and attach it to the project from step 4** in the same form. A repository registered without a project is listed and never receives work.
 
 ## 7. Connect your own accounts
 
-**For:** the person. The integrations serve the whole workspace; a connected account is this person's own Linear or GitHub login, so that what Catalyst does for them is attributed to them, and asks assigned to them can be told apart from everyone else's.
-
-**You run:** `catalyst connections personal linear start`. It prints a short-lived URL and tries to open it; if the browser does not open, hand them the URL. Then `catalyst connections personal linear status`. Do GitHub the same way, with `github`, only after the GitHub App is installed and the repository is registered: `catalyst connections personal github start`, then `status`.
-
-**Read back:** each `status`, and the script's `person` part: their label and role, whether their Linear identity is matched, and each grant. A URL opening is not proof a grant landed. If Linear identity stays unmatched after consent, `catalyst identity linear status`, then `options`; the person picks their own listed identity and you run `catalyst identity linear set <linearUserId>`. An already-resolved or claimed identity, and an inactive seat, need an owner or admin.
-
-**Owner:** you start and check; the person approves in a browser.
+The person's own logins, so work done for them is attributed to them and their asks can be told apart. Run `catalyst connections personal linear start` (hand over the URL if no browser opens), then `catalyst connections personal linear status`. Do GitHub the same way, only after the GitHub App is installed and the repository is registered. An unmatched Linear identity is in `references/connecting-this-machine.md`.
 
 ## 8. The repository's settings file
 
-**For:** the repository's own settings, in `.catalyst/catalyst.toml` on its default branch: the Linear team it belongs to, the names of the variables and secrets its build needs, and its setup commands. Names leave the machine; values are entered once, by them, in the app.
-
-**You ask:** one thing at a time. First: "Shall I draft it from your repository's own build files?" On a yes, ask where the repository is checked out on this machine; if it is not, write the file here for them to add. Then `references/declaring-a-repository.md`: the inventory, the file's shape, the pull request. Say what happens after the merge as context, not as a second task for now. After the merge, an owner or admin approves the revision on the repository's Environment page (Settings → Repositories → the repository → Environment → Setup declaration → Approve this revision) and enters the values on the same page. A workspace-wide declaration, if they want one, goes through `catalyst environment` (read, propose, `--approve`), the one setup write you can perform.
-
-**Read back:** the script's `repository declarations` part, read from each project's `environment_declared` check: no file yet, invalid, awaiting approval, or in effect, per repository. Names only, never a value.
+Ask "Shall I draft it from your repository's own build files?", then follow `references/declaring-a-repository.md`. Mention the approval after the merge as context, not a second task. A workspace-wide declaration goes through `catalyst environment` (read, propose, `--approve`).
 
-**Owner:** the person, with you, in the repository; a workspace owner or admin for the approval.
+Once you know the checkout path, rerun `node scripts/where-am-i.mjs --next --repo <path>` (a read) and follow `references/repository-agent-setup.md` for the offers it notes.
 
 ## 9. Verify, then run the first ticket
 
-**For:** the only thing that proves setup worked.
-
-**You run:** `catalyst team check <KEY>` first when the script's next step names it (an owner or admin whose CLI has the verb), then `catalyst ready`. Its READY does not cover the coding account or the host; the script does. Read them the verdict and every failing line with its own fix and owner. If it says NOT READY, go to `references/who-fixes-what.md` before you touch anything.
-
-**Then:** one question, worded like this: "Move one ticket into ENG's start stage (usually Todo) and tell me its id." Nothing else in that turn: no offer to explain the pipeline, to look at the board, or to pick one for them. Then watch. `catalyst explain <ticket>` says why it is or is not about to run. If they opted into local sync, use the optional first-event check in `references/local-sync.md`.
-
-**Read back:** what `explain` actually said, and the first comment the agent leaves on the ticket. If `explain` says the ticket cannot start, the reason it names is the answer; use the `how-catalyst-works` skill for what it means, then `unstick` if something is holding it.
+Run `catalyst ready`; READY covers neither the coding account nor the host, which the script reads. On NOT READY, read `references/reading-ready.md` before touching anything.
 
-**Owner:** the card move is theirs. The verdict is the workspace's.
+Then ask one thing: "Move one ticket into ENG's start stage (usually Todo) and tell me its id." Nothing else that turn. `catalyst explain <ticket>` says why it is or is not about to run, and the agent's first comment on the ticket confirms it started. With local sync on, use the optional first-event check in `references/local-sync.md`. A reason it cannot start goes to the `whats-happening` skill, then `unstick`.
 
 ## When you are done
 
-Say what is set up, name anything still unfinished with its owner, and never say work can run while the `coding accounts` or `host` part is unfinished. Tell them the standing question "am I set up?" now belongs to the `catalyst-setup` skill, and "what's happening?" to `whats-happening`. You do not need to be invoked again.
+Say what is set up and name anything unfinished with its owner; work can run only when the `coding accounts` and `host` parts are finished.

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

@@ -1,46 +1,39 @@
 # What a phase needs to run
 
-A person can finish every other step and still see nothing run. A phase needs two more things: an enrolled coding account, and a host check that passes. `node scripts/where-am-i.mjs` reads both, as the `coding accounts` and `host` parts. Read those parts; never assume either.
+A phase needs the `coding accounts` and `host` parts of `node scripts/where-am-i.mjs`, however much else is finished. Say a phase can run only when the script's last line says nothing is left; otherwise name the unfinished part and its owner, and say no work will start yet.
 
 ## Coding accounts
 
-**For:** a phase runs on one of the tenant's own enrolled coding accounts. With none active, no phase can start.
+One coding account is enough to start. A second, on another provider or plan, gives the router somewhere to go at a limit; offer it later.
 
-**Instrument:** `codingAccounts` in `catalyst contract`. It carries a `state`, a printable `line`, who enrolls an account (`enrolledByLine`) and the `page`. The script prints all of them. It never shows a credential or an email. When the state is `enrolled`, the script also reads `catalyst accounts` to check each account's credential.
+### The kinds, and enrolling
 
-**What each state means:**
-
-| state | what it says | what to do |
+| they say | kind | the page asks for |
 | -- | -- | -- |
-| `enrolled` | at least one account is active. Another account can still have a dead credential | read the account lines. If one says "<provider> account <slot> needs a new credential", that is the next step: follow `references/replacing-a-credential.md`. If the part reads `unreadable`, the accounts could not be checked in detail; say so and read it again later. Otherwise nothing |
-| `none_enrolled` | no account is enrolled | hand over the page; the enroller the contract names enrols one |
-| `inactive` | accounts exist, but every one is out of rotation | reactivate one on the page. Never tell them to enrol another |
-| `unread` | the cloud could not read the accounts | say it could not be read. It is not "no accounts". Do not tell them to enrol one; read it again later |
+| "Claude Pro or Max", "I use Claude Code" | Claude setup token | what `claude setup-token` prints, after `/status` in `claude` shows the account they mean |
+| "ChatGPT", "Codex" | Codex auth file | `~/.codex/auth.json` after `codex login` (steps in `references/replacing-a-credential.md`) |
+| "a GLM key", "Z.ai" | GLM API key | the key from the provider's console |
+| "a Qwen key", "Alibaba Model Studio" | Qwen API key | the key from the provider's console |
 
-**Owner:** the one the contract names. The person does it in the browser. Never ask for the credential, and never handle it. A key cannot enrol one. Which kinds of account exist, what each asks for, and what to do with an ended or cancelled one are in `references/choosing-a-coding-account.md`; it is step 2 of the path, the first thing asked.
+A plain Anthropic or OpenAI API key cannot be enrolled; say so and ask whether they have one of these. Before a Codex paste, say Catalyst takes over that login: its refresh token is single-use, so they sign in to Codex again locally afterwards.
 
-**Older cloud:** if the contract has no `codingAccounts`, the script says the cloud is older and reads `catalyst accounts` instead. That list counts the accounts enrolled and the ones able to take work. An expired, revoked or quarantined account does not count. The owner is then a tenant owner or admin, at `<their cloud>/settings/coding-accounts`.
-
-## Host
+Enrolling is a browser step by construction: on Settings → AI accounts, an owner or admin picks the provider, labels the account, and pastes the credential into a write-only field. Call an account by its label, else its email, else its slot (`displayName` in `catalyst accounts --json`).
 
-**For:** the contract carries this as the `hosts_current` readiness check on each project. It reads the same on every project, because it is about the whole account.
+### The states
 
-**Instrument:** the `hosts_current` check in `catalyst contract --path teams`, and its owner in `catalyst contract --path readinessChecks`.
+**Instrument:** `codingAccounts` in `catalyst contract`; with `enrolled`, the script also reads `catalyst accounts` for each credential. With no `codingAccounts` (an older cloud) it reads `catalyst accounts` alone, and the owner is an owner or admin at `<their cloud>/settings/coding-accounts`.
 
-**What each reading means:**
-
-| reading | what it says | what to do |
+| state | what it says | what to do |
 | -- | -- | -- |
-| `pass` | nothing is waiting on a host. A tenant that runs no host of its own reads this too | nothing |
-| `unknown`, `no_host_connected` | no Catalyst host is connected | name the owner and stop |
-| `unknown`, `hosts_unreported` | a host is connected but has not said which mapping it loaded | name the owner; it clears when the host reconnects |
-| `fail`, `hosts_behind` | a connected host runs an older mapping | name the owner |
-| the part reads `unreadable` | no project has been checked yet | run `catalyst team check <KEY>` when the script names it (it does when the CLI has the verb and the person is an owner or admin); otherwise press Re-check on the projects page; then read it again |
+| `enrolled` | one is active; another can still have a dead credential | "<provider> account <slot> needs a new credential" is the next step: `references/replacing-a-credential.md`. `unreadable` detail: read again later |
+| `none_enrolled` | none enrolled | hand over the page to the enroller the contract names |
+| `inactive` | every account is out of rotation | reactivate one on its page, never enrol another |
+| `unread` | the cloud could not read them | it is not "no accounts"; read again later |
 
-**Owner:** the contract names the owner of `hosts_current`, and where they act in its `fixedWhere`. When `fixedWhere` has a page, the script prints it, and the command too when there is one. When it is null, which it is today, the script prints the owner sentence alone. Then there is no page, so do not invent one. Say who owns it and that they connect it.
+**A cancelled or ended account** stays for reporting, unused, and does not hold setup up; say so in one clause. It keeps its own login: a token from another login would put a live account onto a dead slot. It stays enrolled rather than retired or deleted, and a returning subscription reactivates it on its page.
 
-⛔ `catalyst ready` treats this check as a note, so it can print READY while no host is connected. READY there is not proof a phase can run. The `host` part is.
+## Host
 
-## Saying it is ready
+The `hosts_current` check reads the same on every project, because it is about the whole account. `pass` means nothing waits on a host, including an account that runs none. `no_host_connected`, `hosts_unreported` (clears when the host reconnects) and `hosts_behind` each mean: name the owner and stop. `unreadable` means no project has been checked yet. The owner and where they act (`fixedWhere`) come from `catalyst contract --path readinessChecks`; when `fixedWhere` is null, name the owner with no page.
 
-Say a phase can run only when the script's last line says nothing is left. While either part is unfinished or unreadable, name that part, its owner, and where, and say plainly that no work will start yet.
+⛔ `catalyst ready` treats this check as a note, so it can print READY while no host is connected. The `host` part, not READY, says whether a phase can run.

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

@@ -1,51 +1,34 @@
 # What the browser owns
 
-Some steps you cannot do, and the honest thing is to say which and why. There are two kinds, and they deserve different sentences.
+## Browser by construction
 
-## Kind one: browser by construction
+Each is an authorization a person grants in their own session, so no command will ever do it. Say **by construction**; a person told "not supported yet" waits for a feature that will never come.
 
-These will never be a command, on any release. Each is an authorization a person grants in their own session; a credential that could perform one would defeat the point of it.
+| step | where |
+| -- | -- |
+| approving the login | the URL and short code `catalyst login` printed |
+| enrolling a coding account, or replacing its credential | the AI accounts page the script printed |
+| connecting the Linear integration, installing the GitHub App | `<their cloud>/settings/connections` |
+| creating `<your GitHub org>/thoughts` and letting the App reach it | GitHub, then the App's installation page for that org: All repositories, or add `thoughts` (step 5 of `references/the-one-path.md`) |
+| connecting personal Linear, then personal GitHub | the URL `catalyst connections personal <linear\|github> start` printed |
 
-| step | where | what you say |
-| -- | -- | -- |
-| approving the login | the URL and short code that `catalyst login` printed | "I have started the login. It printed this code and this URL — approve it in your browser, or on your phone, and tell me when it is done." |
-| enrolling a coding account, or replacing its credential | the AI accounts page the script printed for the `coding accounts` part | "Choose the provider, give the account a label you will recognise, and paste the credential the page asks for. Nothing on this side sees it. Tell me when it is saved and I will read it back." |
-| connecting the Linear integration | `<their cloud>/settings/connections` (the Integrations page; Settings labels it Connections today) | "Open this page and connect Linear. It will send you to Linear to authorize it and bring you back." |
-| installing the GitHub App | `<their cloud>/settings/connections` | "Open the same page and install the GitHub App, granting it the repository you want worked and `<your GitHub org>/thoughts`." |
-| creating or confirming `<your GitHub org>/thoughts`, and letting the GitHub App reach it | GitHub, then the GitHub App's installation page for that org | "Catalyst's cloud phases write their notes to `<your GitHub org>/thoughts`, in the org that owns the code repository. Check it exists. If not, create a private repository named `thoughts`, initialized with a README. Then, on the GitHub App's installation page for that org, choose All repositories, or add `thoughts` to the selected repositories." |
-| connecting personal Linear | the URL printed by `catalyst connections personal linear start` | "Approve your own Linear account in this browser. I will check the grant status afterward." |
-| connecting personal GitHub, after the tenant GitHub App is installed and its repository is registered | the URL printed by `catalyst connections personal github start` | "Approve your own GitHub account in this browser. I will check the grant status afterward." |
+## Not a command yet
 
-Say **by construction**, not "not supported yet". A person who thinks it is a missing feature will wait for it.
+Their routes take a browser session, not a key. Call them gaps, route the person through the browser, and never guess at a route.
 
-## Kind two: not a command yet
+| step | where |
+| -- | -- |
+| registering a repository and attaching it to a project | `<their cloud>/settings/repositories` |
+| approving one repository's declaration, and entering its values | that repository's Environment page (`references/declaring-a-repository.md`) |
 
-These are settings pages today because the routes behind them take a browser session and not a key. A key-callable path is being built. They are gaps, and you should say so in those words — but you must still route the person through the browser, and you must not guess at a route. Trying one and being refused wastes their time and teaches them the tool is unreliable.
+`catalyst environment` handles a workspace-wide declaration. ⛔ Only the CLI makes requests; if you find yourself building a URL for one of these, stop.
 
-| step | where | what you say |
-| -- | -- | -- |
-| registering a repository | `<their cloud>/settings/repositories` | "Add the repository here, and attach it to the project you just mapped, in the same form." |
-| approving the environment **for one repository**, and entering its values | that repository's Environment page under `<their cloud>/settings/repositories`: the Setup declaration tab's Approve this revision button approves, and the Environment variables and Secrets tabs take the values | "The names come from `.catalyst/catalyst.toml` in the repository, which I can write with you. Approving it and entering the values happen here, once, by you. Nothing I run ever sees a value." (Account-wide names are **not** on this list: `catalyst environment` does those.) |
+## The link to hand over
 
-⛔ **Do not compose a request for any of these.** A skill script never makes a request of its own; only the CLI does, and the CLI has no verb for them. If you find yourself constructing a URL, stop.
-
-## The URL to hand over
-
-Never type a host from memory. `catalyst status` prints the API it is connected to on its `API:` line, and `node scripts/where-am-i.mjs` prints ready-made links built from it. Use those. A person pointed at the wrong tenant's settings page has a worse afternoon than one pointed at no page at all.
+Use the links `node scripts/where-am-i.mjs` prints, built from the `API:` line of `catalyst status`, never a host from memory: the wrong account's settings page costs more than none.
 
 ## Handing over, and coming back
 
-The shape is always the same three parts, and all three matter:
-
-1. **What to open.** One link, and what they will see on it.
-2. **What to do there.** One action, named the way the page names it.
-3. **What you need back.** Not "let me know when you are done" — say what you will check and how. "When you have saved it, say so and I will re-read your tenant and tell you what it now says."
-
-Then **wait**. Do not run anything while they are mid-flow, do not narrate, and do not move to the next step.
-
-When they come back:
+Hand over one link, one action named the way the page names it, and what you will check when they are back. Then wait, without running anything.
 
-- Re-run `node scripts/where-am-i.mjs` and read them the part that should have changed.
-- If it changed, say what it now says and move on.
-- If it did not, refresh the contract once (`catalyst contract --refresh`) and read it again — the contract is cached, and a page can be ahead of it by a few seconds.
-- If it still did not, report both: what the page told them, and what the instrument says. Ask what they saw. **Never mark a step done because the person said a page worked** — the instrument is the record, and this is exactly where a confident false "all set" costs them an hour later.
+When they come back, read the part again (step 5 of a turn in `SKILL.md`). The contract is cached, so a page can be seconds ahead of it: refresh once before reporting a disagreement, then ask what they saw. A step is done when the instrument reads done.

package/skills/{catalyst-setup → catalyst-onboard}/scripts/check.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 // check.mjs — "am I set up?" in one verdict: the machine checks the CLI runs (Node, the connection,
 // the cached contract, the CLI path, the skills, the SDK, the optional replica) plus every team's
-// readiness vector from the tenant contract, then the list of who can click what. Wraps
-// `catalyst-skills ready --json`; reports, never repairs. Exit 0 READY, 1 NOT READY, 2 not connected.
-import { parseJson, runCli } from "./lib/cli.mjs";
+// readiness from the account's contract, then the list of who can click what. Wraps
+// `catalyst ready --json`; reports, never repairs. Exit 0 READY, 1 NOT READY, 2 not connected.
+import { runCli, tryJson } from "./lib/cli.mjs";
 
 const HELP = `Usage: node scripts/check.mjs [--json]
 
@@ -12,7 +12,8 @@ verdict, and a "who can click what" list grouped by the person or role each fix
 A note never flips the verdict (the replica is optional; an informational readiness check is a note).
 
 --json prints the CLI's report document {ready, checks[]} unchanged.
-Exit 0 READY, 1 NOT READY, 2 this machine is not connected to a tenant yet.`;
+Exit 0 READY, 1 NOT READY, 2 this machine is not connected yet or the CLI could not run.
+How to read each line: references/reading-ready.md.`;
 
 const args = process.argv.slice(2);
 if (args.includes("--help") || args.includes("-h")) {
@@ -27,13 +28,13 @@ if (unknown.length > 0) {
 }
 
 const res = runCli(["ready", "--json"]);
-if (res.code === 2) {
-  console.error(res.stderr.trim() || "catalyst-skills ready refused");
+const report = tryJson(res.stdout);
+if (!res.ran || (res.code === 2 && !report)) {
+  console.error(res.stderr.trim() || "catalyst ready refused");
   process.exit(2);
 }
-const report = parseJson(res.stdout);
 if (!report || !Array.isArray(report.checks)) {
-  console.error(res.stderr.trim() || res.stdout.trim() || "catalyst-skills ready printed no report");
+  console.error(res.stderr.trim() || res.stdout.trim() || "catalyst ready printed no report");
   process.exit(res.code === 0 ? 1 : res.code);
 }
 if (args.includes("--json")) {
@@ -70,6 +71,6 @@ if (failures.length > 0) {
 const notes = report.checks.filter((c) => c.note && !c.ok);
 if (notes.length > 0) {
   console.log("");
-  console.log(`Notes that do not block: ${notes.map((c) => c.id).join(", ")} — see references/what-each-check-means.md`);
+  console.log(`Notes that do not block: ${notes.map((c) => c.id).join(", ")} — see references/reading-ready.md`);
 }
 process.exit(report.ready ? 0 : 1);

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: spawn the catalyst-skills CLI.
+// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: spawn the catalyst CLI.
 // The CLI holds the SDK and the key; this file holds neither. It reads customer.json only to learn
 // where the CLI lives. Run any script beside this one with --help; this file is a library.
 //
@@ -13,7 +13,9 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 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 NOT_CONFIGURED_EXIT = 2;
 export const CONNECT_LINE = CONNECT_COMMAND;
 
@@ -53,11 +55,11 @@ export function cliTarget(cfg = tryLoadConfig()) {
   const recorded = recordedPath !== null;
   return recorded
     ? { command: process.execPath, prefix: [cfg.cliPath], via: `node ${cfg.cliPath}`, recorded: true }
-    : { command: "npx", prefix: [PACKAGE], via: `npx ${PACKAGE}`, recorded: false };
+    : { command: "npx", prefix: NPX_ARGS, via: `npx -p ${PACKAGE} catalyst`, recorded: false };
 }
 
 /**
- * Run one catalyst-skills verb. Returns {code, stdout, stderr, ran} and never exits: a verb that
+ * Run one catalyst verb. Returns {code, stdout, stderr, ran} and never exits: a verb that
  * refuses because the machine is not connected is a READING, not a failure of this script.
  * `ran` is false when the CLI could not be started at all.
  */

package/skills/catalyst-onboard/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) {