@catalyst-cloud/cli 0.9.5 → 0.13.1

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) {

package/skills/catalyst-onboard/scripts/where-am-i.mjs

@@ -14,6 +14,7 @@ import { runLocalSync } from "./local-sync.mjs";
 const SPEC = {
   next: { help: "print only the single next step" },
   json: { help: "one JSON document instead of the report" },
+  repo: { value: true, help: "a checkout of a mapped repository on this machine: its agent setup (AGENTS.md block, portable layout) is read and reported, never changed" },
 };
 const NOTES = [
   "Reads, in this order: `status` (machine), `ready --json` (machine checks and project checks, kept apart),",
@@ -22,6 +23,8 @@ const NOTES = [
   "`contract --path codingAccounts` and `accounts --json` (coding accounts, and which one needs a new credential), and each",
   "project's hosts_current check with its fixedWhere (host), and each project's environment_declared check with its per-repository notes (repository declarations). The teams read is refreshed, so a mapping just saved reads back mapped.",
   "Reads `capabilities --json` once: when the installed CLI can run a step for this person's role (`team check`, `team map`), the next step is that command; otherwise the page, with who can.",
+  "Reads `legacy --json` when the CLI has the verb: leftovers of the old local Catalyst runtime become a machine line and a note; removing them is the person's yes.",
+  "With --repo <path>, reads `repo agent-setup <path> --json` (a read; nothing changes) and adds a `repository agent setup` part that never blocks: the Catalyst block in AGENTS.md and the portable layout, with the writes named for the person to approve.",
   "Also runs `gh repo view <owner>/thoughts` for each registered repository's owner, as a note: it shows the repository exists, never that the GitHub App can reach it.",
   "When the tenant serves a contract version this CLI refuses, runs `npm view @catalyst-cloud/cli version` once to say whether a newer CLI is published.",
   "Writes nothing and changes nothing. Runs before this machine is connected — that is one of the states it reports.",
@@ -29,7 +32,7 @@ const NOTES = [
 
 const { help, flags, positionals } = parseFlags(process.argv.slice(2), SPEC);
 if (help) {
-  printHelp("node scripts/where-am-i.mjs [--next] [--json]", SPEC, NOTES);
+  printHelp("node scripts/where-am-i.mjs [--next] [--json] [--repo <path>]", SPEC, NOTES);
   process.exit(0);
 }
 if (positionals.length > 0) {
@@ -155,6 +158,19 @@ if (connected) {
   const capDoc = tryJson(runCli(["capabilities", "--json"]).stdout);
   capabilities = Array.isArray(capDoc?.capabilities) ? capDoc.capabilities : null;
 }
+// Leftovers of the old local Catalyst runtime (its plugin, jobs, commands, state), from the CLI's own
+// fixed list. Reported on the machine part and as a note; removal is the person's yes, never this script's.
+let legacyNote = null;
+if (verbAvailable("legacy")) {
+  const legacyDoc = tryJson(runCli(["legacy", "--json"]).stdout);
+  const found = Array.isArray(legacyDoc?.found) ? legacyDoc.found : [];
+  if (found.length > 0) {
+    const machine = parts.find((p) => p.part === "machine");
+    const names = found.map((f) => `${f.kind} ${f.name}`);
+    machine?.lines.push(`note leftovers of the old local Catalyst runtime (${found.length}): ${names.slice(0, 6).join(", ")}${found.length > 6 ? ", …" : ""}; removing them is strongly recommended: catalyst legacy --remove (the data folders are a separate yes, --data)`);
+    legacyNote = `this machine still carries ${found.length} piece${found.length === 1 ? "" : "s"} of the old local Catalyst runtime (${names.slice(0, 4).join(", ")}${found.length > 4 ? ", …" : ""}); offer catalyst legacy --remove once, strongly recommended, then --data as a separate question`;
+  }
+}
 
 // ── person ────────────────────────────────────────────────────────────────────────────────────────
 if (!connected) {
@@ -593,6 +609,45 @@ if (!connected) {
   }
 }
 
+// ── repository agent setup (only with --repo) ─────────────────────────────────────────────────────
+// A checkout the person named. Read through the CLI's own verb, never by this script opening files:
+// the verb is the one place that knows the block's words and the portable layout. Never blocking:
+// a repository that is not portable still runs; this is an offer, and the writes wait for a yes.
+let repoNote = null;
+let repoNext = null;
+if (typeof flags.repo === "string" && flags.repo !== "") {
+  const REPO_INSTRUMENT = `repo agent-setup ${flags.repo} --json`;
+  if (!connected) {
+    add("repository agent setup", REPO_INSTRUMENT, "unreadable", ["not readable until this machine is connected"], null, null, false);
+  } else if (!verbAvailable("repo agent-setup")) {
+    add("repository agent setup", REPO_INSTRUMENT, "unreadable", ["this CLI has no repo agent-setup verb; update the CLI to read a checkout's agent setup"], null, null, false).next =
+      "update the CLI (it lacks repo agent-setup); the checkout's agent setup cannot be read until then (does not block anything)";
+  } else {
+    const res = runCli(["repo", "agent-setup", flags.repo, "--json"]);
+    const doc = tryJson(res.stdout);
+    if (doc === null) {
+      add("repository agent setup", REPO_INSTRUMENT, "unreadable", [`the checkout could not be read (${(res.stderr || res.stdout).trim().split("\n")[0] || "no output"})`], null, null, false).next =
+        `run this again with the checkout's real path; ${flags.repo} could not be read`;
+    } else {
+      const block = doc.agentsMd?.block ?? "unknown";
+      const verdict = doc.verdict ?? "unknown";
+      const ok = verdict === "portable" && block === "current";
+      const lines = [
+        `AGENTS.md: ${doc.agentsMd?.present ? `present; Catalyst block ${block}` : "absent"}`,
+        `CLAUDE.md: ${doc.claudeMd?.present ? (doc.claudeMd.importsAgentsMd ? "imports AGENTS.md" : `${doc.claudeMd.otherLines ?? "?"} lines of its own guidance, no @AGENTS.md import`) : "absent"}`,
+        `layout: ${verdict}${Array.isArray(doc.plan) && doc.plan.length ? ` — ${doc.plan.join("; ")}` : ""}${Array.isArray(doc.blockers) && doc.blockers.length ? ` — by hand: ${doc.blockers.join("; ")}` : ""}`,
+      ];
+      const offers = [];
+      if (block !== "current") offers.push(`the Catalyst block for AGENTS.md (catalyst repo agents-block ${flags.repo} --write)`);
+      if (verdict === "convertible") offers.push(`the portable layout (catalyst repo agent-setup ${flags.repo} --apply)`);
+      if (verdict === "needs_hand_merge") offers.push("a hand merge first (the layout line names what)");
+      repoNext = ok ? null : `say in one clause what the checkout holds, then offer ${offers.join(" and ")}, each after a yes, on a branch for the pull request the person opens`;
+      add("repository agent setup", REPO_INSTRUMENT, ok ? "ok" : "unfinished", lines, ok ? null : "you, after the person's yes, in their checkout; the pull request is theirs", ok ? null : `catalyst repo agent-setup ${flags.repo}`, false);
+      if (!ok) repoNote = `repository ${flags.repo}: Catalyst block ${block}, layout ${verdict} — offer ${offers.join(" and ")} after a yes (references/repository-agent-setup.md)`;
+    }
+  }
+}
+
 // ── the single next step ──────────────────────────────────────────────────────────────────────────
 // The machine's next action is not one sentence: an unconnected machine needs the login, and a
 // connected one needs whatever check failed — and `ready` already printed that check's own fix, so
@@ -620,6 +675,7 @@ const NEXT = {
   repositories: "install the GitHub App on the Connections page, granting it the repository you want worked; registering that repository on the Repositories page, attached to the project, is the step right after",
   "coding accounts": accountsNext,
   "repository declarations": declNext,
+  "repository agent setup": repoNext ?? "read the checkout's agent setup again",
   host: "connect a Catalyst host",
 };
 // The parts are read in the order their data allows and reported in the order a person can act on
@@ -627,7 +683,7 @@ const NEXT = {
 // workspace's Linear integration, the project, the GitHub App with its repository, the person's own
 // connected accounts (personal GitHub after the repository proves the App), the repository's
 // declaration, and last the host. `--next` is the first unfinished part in this order.
-const ORDER = ["machine", "coding accounts", "account", "projects", "repositories", "person", "repository declarations", "host"];
+const ORDER = ["machine", "coding accounts", "account", "projects", "repositories", "person", "repository declarations", "repository agent setup", "host"];
 parts.sort((a, b) => ORDER.indexOf(a.part) - ORDER.indexOf(b.part));
 // A personal Linear grant cannot start until the tenant's Linear workspace exists. Once that account
 // connection is present, a missing personal grant becomes the next member step before project setup.
@@ -680,9 +736,9 @@ if (contractMismatch !== null && stuck !== null) {
 const finished = parts.every((p) => p.verdict === "ok");
 
 if (flags.json) {
-  console.log(JSON.stringify({ cli: via, connected, cloud, personalConnections, parts, localSync, next, finished, notes: retireNote === null ? [] : [retireNote] }));
+  console.log(JSON.stringify({ cli: via, connected, cloud, personalConnections, parts, localSync, next, finished, notes: [retireNote, repoNote, legacyNote].filter((n) => n !== null) }));
 } else if (flags.next) {
-  process.on("exit", () => { if (retireNote !== null) console.log(`note: ${retireNote}`); });
+  process.on("exit", () => { for (const n of [retireNote, repoNote, legacyNote]) if (n !== null) console.log(`note: ${n}`); });
   if (next === null) console.log("nothing left: every part is finished, a coding account is enrolled and the host check passes. Move one card into the project's start stage (usually Todo).");
   else console.log(`${next.part}: ${next.action}${next.blocking ? "" : " (does not block the steps below)"}${next.owner ? ` — who: ${next.owner}` : ""}${next.where ? ` — ${next.where.startsWith("http") ? "where" : "do"}: ${next.where}` : ""}`);
 } else {