@catalyst-cloud/cli 0.9.4 → 0.13.0

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

@@ -8,13 +8,13 @@ These will never be a command, on any release. Each is an authorization a person
 
 | step | where | what you say |
 | -- | -- | -- |
-| approving the login | the URL and short code that `catalyst-skills login` printed | "I have started the login. It printed this code and this URL — approve it in your browser, or on your phone, and tell me when it is done." |
+| 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-skills 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-skills connections personal github start` | "Approve your own GitHub account in this browser. I will check the grant status afterward." |
+| 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." |
 
 Say **by construction**, not "not supported yet". A person who thinks it is a missing feature will wait for it.
 
@@ -24,17 +24,14 @@ These are settings pages today because the routes behind them take a browser ses
 
 | step | where | what you say |
 | -- | -- | -- |
-| seeing every project they could set up | `<their cloud>/settings/linear-teams` | "I can read the projects that are already mapped, but the full list is only on this page today. Open it and tell me the ones you see." |
-| checking a project's readiness, or re-checking it | the same page | "I can read the verdict your tenant last stored, from the contract. Asking for a fresh check is on that page." |
-| mapping stages, or adopting the workflow | the same page, per project | "Pick one project, then **Map my stages** — or **Adopt the Catalyst workflow** if you want Catalyst's stages created for you." |
 | registering a repository | `<their cloud>/settings/repositories` | "Add the repository here, and attach it to the project you just mapped, in the same form." |
-| approving the environment **for one repository**, and entering its values | that repository's Environment 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-skills environment` does those.) |
+| 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.) |
 
 ⛔ **Do not compose a request for any of these.** A skill script never makes a request of its own; only the CLI does, and the CLI has no verb for them. If you find yourself constructing a URL, stop.
 
 ## The URL to hand over
 
-Never type a host from memory. `catalyst-skills status` prints the API it is connected to on its `API:` line, and `node scripts/where-am-i.mjs` prints ready-made links built from it. Use those. A person pointed at the wrong tenant's settings page has a worse afternoon than one pointed at no page at all.
+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.
 
 ## Handing over, and coming back
 
@@ -50,5 +47,5 @@ When they come back:
 
 - Re-run `node scripts/where-am-i.mjs` and read them the part that should have changed.
 - If it changed, say what it now says and move on.
-- If it did not, refresh the contract once (`catalyst-skills contract --refresh`) and read it again — the contract is cached, and a page can be ahead of it by a few seconds.
+- If it 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.

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

@@ -6,40 +6,59 @@ Setup is eight parts. Each has one instrument, and each instrument answers about
 
 | part | instrument | what a pass proves | what it does **not** prove | who fixes a failure, and where |
 | -- | -- | -- | -- | -- |
-| **machine** | `catalyst-skills status`, and the non-team checks of `catalyst-skills ready` | Node is new enough, this machine holds a credential, the CLI is where the config says, the contract is cached, the skills are on disk | anything at all about the tenant | the person at this keyboard, here |
-| **person** | `catalyst-skills me`, and `catalyst-skills connections personal <linear|github> status` | the credential resolves to this person, shows their role and Linear identity match, and reports each personal grant's state | that their seat is active, or that they may change tenant settings | the member approves missing or expired personal grants in a browser; an owner or admin handles seat or identity conflicts in Settings → Members |
-| **account** | `catalyst-skills contract --path account` | a resolved Linear workspace means the tenant's Linear grant landed | that the GitHub App is installed — the contract does not carry it | a tenant owner or admin, `<their cloud>/settings/connections` |
-| **project** | `catalyst-skills contract --path teams`, and the `team:` checks of `ready` | for each project **that has been mapped**: its readiness verdict and each failing check by name | that this is every project they have — see below | a tenant owner or admin, `<their cloud>/settings/linear-teams` |
-| **repository** | `catalyst-skills contract --path merge.repositories` | the repository is registered to the account | that it is active, that a project can dispatch into it, or that its environment is declared | a tenant owner or admin, `<their cloud>/settings/repositories` |
-| **coding accounts** | `codingAccounts` in `catalyst-skills contract` (`catalyst-skills accounts` on an older cloud) | an account is enrolled and active | that it has headroom left for the next phase | the enroller and page the contract names; see `references/what-a-phase-needs.md` |
-| **repository declarations** | the `environment_declared` check in `catalyst-skills contract --path teams`, and its per-repository notes | the project's default repository has a committed `.catalyst/catalyst.toml` in effect: ingested, valid, and its latest revision approved | that the values the names refer to exist; that any other repository is declared, unless its note says so | the person, with you, in the repository for the file; a tenant owner or admin for the approval, at the repository's Environment page under `<their cloud>/settings/repositories` |
-| **host** | the `hosts_current` check in `catalyst-skills contract --path teams` | no host is missing or behind, or the tenant runs none | anything before a project has been checked | the owner the contract names for `hosts_current`; see `references/what-a-phase-needs.md` |
+| **machine** | `catalyst status`, and the non-team checks of `catalyst ready` | Node is new enough, this machine holds a credential, the CLI is where the config says, the contract is cached, the skills are on disk | anything at all about the tenant | the person at this keyboard, here |
+| **person** | `catalyst me`, and `catalyst connections personal <linear|github> status` | the credential resolves to this person, shows their role and Linear identity match, and reports each personal grant's state | that their seat is active, or that they may change tenant settings | the member approves missing or expired personal grants in a browser; an owner or admin handles seat or identity conflicts in Settings → Members |
+| **account** | `catalyst contract --path account` | a resolved Linear workspace means the tenant's Linear grant landed | that the GitHub App is installed — the contract does not carry it | a tenant owner or admin, `<their cloud>/settings/connections` |
+| **project** | `catalyst team list`, then `team check <KEY>` and the `team:` checks of `ready` for the selected team | the live team list and the selected team's latest readiness verdict | that an unchecked team is ready | a tenant owner or admin, through `catalyst team` or `<their cloud>/settings/linear-teams` |
+| **repository** | `catalyst contract --path merge.repositories` | the repository is registered to the account | that it is active, that a project can dispatch into it, or that its environment is declared | a tenant owner or admin, `<their cloud>/settings/repositories` |
+| **coding accounts** | `codingAccounts` in `catalyst contract` (`catalyst accounts` on an older cloud) | an account is enrolled and active | that it has headroom left for the next phase | the enroller and page the contract names; see `references/what-a-phase-needs.md` |
+| **repository declarations** | the `environment_declared` check in `catalyst contract --path teams`, and its per-repository notes | the project's default repository has a committed `.catalyst/catalyst.toml` in effect: ingested, valid, and its latest revision approved | that the values the names refer to exist; that any other repository is declared, unless its note says so | the person, with you, in the repository for the file; a tenant owner or admin for the approval, at the repository's Environment page under `<their cloud>/settings/repositories` |
+| **host** | the `hosts_current` check in `catalyst contract --path teams` | no host is missing or behind, or the tenant runs none | anything before a project has been checked | the owner the contract names for `hosts_current`; see `references/what-a-phase-needs.md` |
 
 `node scripts/where-am-i.mjs` runs all eight, in the order a person can act on them, and labels each finding with its part. Use it rather than composing this by hand.
 
 ## The two silences that are not absences
 
-⛔ **An empty project list means nothing is mapped yet — it does not mean they have no projects.** The tenant contract carries a project only once someone has saved a stage mapping for it. A brand-new tenant has projects in Linear and an empty list here, and reading that as "you have no projects" sends the person looking for a problem that does not exist. Say: *nothing is mapped yet*, and go to step 4. The list of every project they could map is browser-only today.
+⛔ **An empty contract project list means nothing is mapped yet — it does not mean they have no projects.** The tenant contract carries a project only once someone has saved a stage mapping for it. Read the available team list with `catalyst team list`, choose one, then go to step 4. `team check --all` performs readiness checks and may create asks for every team.
 
-⛔ **A registered repository is not a dispatchable one.** The contract's repository list carries no status and no project attachment, so a paused repository and an active one look identical there, and a repository registered without a project attached looks exactly like a correctly attached one. Registration is all it proves. If a card does not start, `catalyst-skills explain <ticket>` names the real reason; do not conclude anything about the repository from its presence in a list.
+⛔ **A registered repository is not a dispatchable one.** The contract's repository list carries no status and no project attachment, so a paused repository and an active one look identical there, and a repository registered without a project attached looks exactly like a correctly attached one. Registration is all it proves. If a card does not start, `catalyst explain <ticket>` names the real reason; do not conclude anything about the repository from its presence in a list.
 
 ⭐ And the general form of both: **an instrument that answers about a part it does not own will answer confidently and wrongly.** When you are unsure which part something belongs to, look it up in the table above rather than guessing from the wording of an error.
 
 ## Triaging NOT READY
 
-`catalyst-skills ready` prints one verdict over every check, machine and project together. That single verdict is correct for "can work run?" and useless for "what should I do now?", because it folds two parts into one word. Split it before you act:
+`catalyst ready` prints one verdict over every check, machine and project together. That single verdict is correct for "can work run?" and useless for "what should I do now?", because it folds two parts into one word. Split it before you act:
 
-1. Run `catalyst-skills ready --json`. Every check has an `id`.
+1. Run `catalyst ready --json`. Every check has an `id`.
 2. A check whose id begins with `team:` is a **project** finding. Everything else is a **machine** finding.
 3. Report the two groups separately, in that order, each with its own owner.
 
-- **A machine check failed.** This is the person's, here, now. Each failing check carries its own `fix` line; read it and do it. A missing or partial skill set is `catalyst-skills install`; a stale contract is `catalyst-skills contract --refresh`; a missing CLI path is one more `catalyst-skills login`.
-- **A project check failed.** ⛔ **Nothing you run on this machine can move it.** Name the check, name the project, and name the owner — the `who` field carries the tenant's own owners and admins. Point at `<their cloud>/settings/linear-teams`. Then stop. Re-running `ready` in a loop is the failure this section exists to prevent: it will keep saying NOT READY for a reason that lives somewhere else entirely.
-- **A check is a note.** Notes never move the verdict. A stale or absent replica or event cache is optional; an unknown freshness probe means the cloud comparison could not be proved. The API-backed skills still work. Say whether the local cache is absent, stale or unknown, and ask before starting the optional writer.
+- **A machine check failed.** This is the person's, here, now. Each failing check carries its own `fix` line; read it and do it. A missing or partial skill set is `catalyst install`; a stale contract is `catalyst contract --refresh`; a missing CLI path is one more `catalyst login`.
+- **A project check failed.** Name the check, the project, and the owner; the `who` field carries the workspace's own owners and admins. An admin or owner can run the check, preview a stage mapping, or adopt the workflow through `catalyst team`; some failures still need provider consent or a browser action, and `<their cloud>/settings/linear-teams` is where those live. Use the check's reason to choose the next action. Re-running `ready` alone does not fix it.
+- **A check is a note.** Notes never move the verdict. A stale or absent replica or event cache is optional; an unknown freshness probe means the cloud comparison could not be proved. A check that has never been run is waiting, not failing; a check the engine could not run is unknown, which is not a pass and not a failure. Say which it is. The API-backed skills still work; ask before starting the optional writer.
 
 ## When to stop rather than continue
 
 - **They have no account yet.** There is no self-serve sign-up. Coalesce Labs provisions each account, and a person joins one by invitation from its admin. Say so and stop; the next step is theirs.
 - **The account is suspended.** Setup cannot proceed and no retry changes that. Say so and name the conversation they need to have.
 - **Their seat is not active, or they are not an owner or admin where one is required.** Say who is, and what to ask for. Do not offer a workaround.
-- **A page said it worked and the instrument still disagrees.** Refresh the contract once (`catalyst-skills contract --refresh`) and read it again. If it still disagrees, report both facts — what the page said and what the instrument says — and let the person decide. Do not pick one for them.
+- **A page said it worked and the instrument still disagrees.** Refresh the contract once (`catalyst contract --refresh`) and read it again. If it still disagrees, report both facts — what the page said and what the instrument says — and let the person decide. Do not pick one for them.
+
+## What still happens in a browser, and why
+
+Every step a key can do, the guide does. These are the ones it hands over, each with the reason; when a reason stops being true, the step moves to the CLI and this table changes in the same release.
+
+| step | today | why it is still the person's |
+| -- | -- | -- |
+| install Node, or a coding agent | the person, on their machine | outside the CLI |
+| approve the login | the code and URL `login` prints, in a browser | a grant only the person can give |
+| connect the Linear integration | Settings → Connections | an OAuth grant, by construction |
+| install the GitHub App | Settings → Connections | an OAuth grant, by construction |
+| enrol a coding account, or replace its credential | Settings → AI accounts | the credential is theirs to paste; a CLI verb for the paste is being built |
+| register a repository to a project | Settings → Repositories | the route exists; the CLI verb is being built |
+| approve one repository's settings file | the repository's Environment page | the route for a key is being built |
+| enter a secret's value | the repository's Environment page, or `secret set` | a value never passes through the agent |
+| the person's own Linear and GitHub connected accounts | the link `connections personal … start` prints | a grant only the person can give |
+| move the first ticket | Linear, or `write state` when they ask | their call which ticket runs first |
+
+A project's readiness check, its stage mapping and adopting the workflow are CLI steps (`team check`, `team map`, `team adopt`) when `catalyst capabilities` says the installed CLI can run them for the person's role; the script names the command, and the page only for a person whose role cannot.

package/skills/catalyst-onboard/scripts/local-sync.mjs

@@ -8,7 +8,7 @@ import { cliTarget } from "./lib/cli.mjs";
 const STATUS_COMMAND = ["replica", "status", "--probe", "--json"];
 const EVENTS_COMMAND = ["events", "status", "--probe", "--json"];
 const START_COMMAND = ["replica", "start", "--detach"];
-const RECOVERY_COMMAND = "catalyst-skills replica start --detach";
+const RECOVERY_COMMAND = "catalyst replica start --detach";
 
 function defaultRun(args) {
   const target = cliTarget();
@@ -105,7 +105,7 @@ function readStatus(run) {
         current: false,
         reason: `replica status is unknown: ${replicaResult.error || replicaResult.stderr.trim() || "invalid JSON"}`,
       },
-      recovery: replicaResult.code === 2 ? "catalyst-skills login" : "catalyst-skills replica status --probe --json",
+      recovery: replicaResult.code === 2 ? "catalyst login" : "catalyst replica status --probe --json",
     };
   }
   const eventsResult = run(EVENTS_COMMAND);
@@ -120,7 +120,7 @@ function readStatus(run) {
         current: false,
         reason: `event freshness is unknown: ${eventsResult.error || eventsResult.stderr.trim() || "invalid JSON"}`,
       },
-      recovery: "catalyst-skills events status --probe --json",
+      recovery: "catalyst events status --probe --json",
     };
   }
   return { status, events, assessment: assessLocalSync(status, events) };
@@ -140,12 +140,12 @@ export async function runLocalSync({
   if (reading.assessment.current || !start)
     return { ...reading, started: false, recovery: reading.recovery ?? RECOVERY_COMMAND };
   if (!reading.status)
-    return { ...reading, started: false, recovery: reading.recovery ?? "catalyst-skills replica status --probe --json" };
+    return { ...reading, started: false, recovery: reading.recovery ?? "catalyst replica status --probe --json" };
   if (
     reading.status?.verdict === "not-configured" ||
     reading.status?.dbPath == null
   ) {
-    return { ...reading, started: false, recovery: "catalyst-skills login" };
+    return { ...reading, started: false, recovery: "catalyst login" };
   }
   let started = false;
   if (reading.status.writerAlive !== true && ["absent", "stale"].includes(reading.assessment.verdict)) {
@@ -177,7 +177,7 @@ export async function runLocalSync({
     recovery: reading.assessment.verdict === "unknown"
       ? "node scripts/local-sync.mjs --json"
       : reading.status?.writerAlive
-        ? "catalyst-skills replica stop && catalyst-skills replica start --detach"
+        ? "catalyst replica stop && catalyst replica start --detach"
         : RECOVERY_COMMAND,
   };
 }