@catalyst-cloud/cli 0.15.6 → 0.16.1

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

@@ -8,9 +8,9 @@ One coding account is enough to start. A second gives the router somewhere to go
 
 ### The kinds, and enrolling
 
-Settings → AI accounts lists the providers this workspace can connect and what each one asks for; an API key is billed per token by its provider. Do not promise a provider. Ask the person to open Settings → AI accounts and choose from the providers it lists; if the one they name is not there, say so and ask whether they have a key from one that is.
+Settings → AI accounts lists the providers this workspace can connect and what each one asks for; an API key is billed per token by its provider. Do not promise a provider. Ask which provider the person has a key for. No command lists the providers yet, so check the name against that page; if it is not there, say so and ask whether they have a key from one that is.
 
-Enrolling is a browser step by construction: on Settings → AI accounts, an owner or admin picks the provider, labels the account, and pastes the key into a write-only field. If the page says Catalyst takes over a login, say so before the paste. Call an account by its label, else its email, else its slot (`displayName` in `catalyst accounts --json`).
+Adding an account has no command yet, so it is a browser step for now: on Settings → AI accounts, an owner or admin picks the provider, labels the account, and pastes the key into a write-only field. If the page says Catalyst takes over a login, say so before the paste. Call an account by its label, else its email, else its slot (`displayName` in `catalyst accounts --json`).
 
 ### The states
 
@@ -19,8 +19,8 @@ Enrolling is a browser step by construction: on Settings → AI accounts, an own
 | state | what it says | what to do |
 | -- | -- | -- |
 | `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 |
+| `none_enrolled` | none enrolled | hand over the page to the enroller the contract names; there is no command to add one yet |
+| `inactive` | every account is out of rotation | reactivate one on its page (no command does this yet), never enrol another |
 | `unread` | the cloud could not read them | it is not "no accounts"; read again later |
 
 **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 is reactivated on its page only if it can run again.

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

@@ -1,27 +1,37 @@
 # What the browser owns
 
-## Browser by construction
+Headless first: when the catalyst CLI, the SDK or an agent route can do a step, ask "Want me to do that for you?" and run it on a yes; name a web page only for a step that needs a person in a browser by nature (signing in, an OAuth or app-install consent), and then hand over the exact link the CLI printed. A step with no command yet is a gap: say so in one clause and hand over the exact page.
 
-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.
+## Commands you offer to run
 
-| step | where |
+| step | command |
+| -- | -- |
+| registering a repository and attaching it to a project | `catalyst onboard --team <KEY> --repo <owner/name>` (an owner or admin) |
+| checking, mapping or adopting a project's stages | `catalyst team check <KEY>`, `catalyst team map <KEY>`, `catalyst team adopt <KEY>` |
+| entering a repository's values | `catalyst var set NAME --repo <owner/name>`, `catalyst secret set NAME --repo <owner/name>` |
+| creating `<your GitHub org>/thoughts` | `gh repo create <org>/thoughts --private --add-readme` |
+
+## A browser by nature
+
+Each is a sign-in or a consent a person grants in their own session. Start it with the command, then hand over only the link it printed.
+
+| step | how it starts |
 | -- | -- |
 | 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` (Settings → Integrations) |
-| 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 the Linear integration, installing the GitHub App | `catalyst onboard` prints the consent link; without one, `<their cloud>/settings/connections` (Settings → Integrations) |
+| letting the App reach `<your GitHub org>/thoughts` | 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 |
 
 ## Not a command yet
 
-Their routes take a browser session, not a key. Call them gaps, route the person through the browser, and never guess at a route.
+These have no command in this CLI yet. Say so in one clause, hand over the page, and never guess at a route.
 
 | step | where |
 | -- | -- |
-| registering a repository and attaching it to a project | `<their cloud>/settings/projects` (Settings → Your projects) |
-| approving one repository's declaration, and entering its values | that repository's Environment page (`references/declaring-a-repository.md`) |
+| adding a coding account, or replacing its credential | the AI accounts page the script printed |
+| approving one repository's declaration | that repository's Environment page (`references/declaring-a-repository.md`) |
 
-`catalyst environment` handles a workspace-wide declaration. ⛔ Only the CLI makes requests; if you find yourself building a URL for one of these, stop.
+`catalyst environment` handles a workspace-wide declaration. `catalyst capabilities` lists what this CLI can do; a verb it lists replaces the page for that step. ⛔ Only the CLI makes requests; if you find yourself building a URL for one of these, stop.
 
 ## The link to hand over
 

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

@@ -85,6 +85,10 @@ const verbAdminOnly = (verb) => {
   const c = capability(verb);
   return c?.availability === "available" && c.needs === "admin" && !canManage();
 };
+// `catalyst onboard` starts the workspace consents and registers a repository; an older CLI has no
+// such verb, and then the step stays the page.
+const onboardAvailable = () => capability("onboard")?.availability === "available";
+const UPDATE_CLI = "npm install -g @catalyst-cloud/cli@latest";
 // `blocking` is false for a finding that is real and reportable but does not stop the next step —
 // an unmatched Linear identity is the one that matters: it must be said, and it must not become the
 // thing the person is told to go and do before they can map a project.
@@ -335,12 +339,12 @@ if (!connected) {
         ? "you"
         : matched
           ? null
-          : "a workspace owner or admin",
+          : "you",
       personalGrantIncomplete
         ? "catalyst connections personal <provider> start or status"
         : matched
           ? null
-          : link("/settings/account"),
+          : "catalyst identity linear options",
       false,
     );
   }
@@ -424,7 +428,7 @@ if (!connected) {
         ...envLines,
       ],
       "a workspace owner or admin",
-      link("/settings/connections"),
+      onboardAvailable() ? "catalyst onboard" : link("/settings/connections"),
     );
   }
 }
@@ -538,7 +542,7 @@ if (!connected) {
       );
       blockedProjects.push({
         key,
-        action: `fix ${key}'s blocking check${ids.length === 1 ? "" : "s"} (${ids.join(", ") || "see the projects lines"}): ${how || owner}; then run catalyst team check ${key} (or press Re-check) and run this again`,
+        action: `fix ${key}'s blocking check${ids.length === 1 ? "" : "s"} (${ids.join(", ") || "see the projects lines"}): ${how || owner}; then run catalyst team check ${key} and run this again`,
         owner,
       });
     }
@@ -565,7 +569,11 @@ if (!connected) {
       : "a workspace owner or admin";
     const mapWhere = verbAvailable("team map")
       ? "catalyst team list"
-      : link("/settings/linear-teams");
+      : verbAdminOnly("team map")
+        ? "catalyst team map <KEY>"
+        : capability("team map")
+          ? link("/settings/projects")
+          : UPDATE_CLI;
     const projectOwner =
       blockedProjects.length > 0 ? blockedProjects[0].owner : mapOwner;
     const projectWhere = blockedProjects.length > 0 ? null : mapWhere;
@@ -653,7 +661,9 @@ if (!connected) {
       rows.length > 0 ? "ok" : "unfinished",
       lines,
       "a workspace owner or admin",
-      link("/settings/projects"),
+      onboardAvailable()
+        ? "catalyst onboard --team <KEY> --repo <owner/name>"
+        : link("/settings/projects"),
     );
   }
 }
@@ -908,8 +918,9 @@ if (!connected) {
   }
 }
 
-// the Re-check step, as a command when this person can run it, else as the page with the
-// person who can. `team check` is the CLI twin of the page's Re-check button (admin or owner).
+// the re-check step, always `catalyst team check`: run it when this person can, name the owner or
+// admin who can otherwise. A CLI without the verb is told to update; only a cloud that does not
+// serve the route yet falls back to the projects page.
 const mappedKeys = () =>
   (teamRows ?? [])
     .map((t) => t.key ?? t.id)
@@ -925,14 +936,21 @@ const recheckStep = () => {
     };
   if (cmds.length > 0 && verbAdminOnly("team check"))
     return {
-      action: `a workspace owner or admin runs ${cmds.join(" and ")} (or presses Re-check on the projects page); then run this again`,
+      action: `a workspace owner or admin runs ${cmds.join(" and ")}; then run this again`,
       owner: "a workspace owner or admin",
-      where: link("/settings/linear-teams"),
+      where: cmds[0],
+    };
+  if (capability("team check"))
+    return {
+      action:
+        "this cloud does not serve catalyst team check yet, so a workspace owner or admin re-checks the project on the projects page; then run this again",
+      owner: "a workspace owner or admin",
+      where: link("/settings/projects"),
     };
   return {
-    action: "press Re-check on the projects page, then run this again",
+    action: `update the CLI (${UPDATE_CLI}), then a workspace owner or admin runs catalyst team check ${cmds.length > 0 ? mappedKeys()[0] : "<KEY>"}; then run this again`,
     owner: "a workspace owner or admin",
-    where: link("/settings/linear-teams"),
+    where: UPDATE_CLI,
   };
 };
 
@@ -989,7 +1007,7 @@ if (!connected) {
           : "no project has a readiness check yet, so whether a host is connected cannot be read.",
       ],
       teamRows === null ? "a workspace owner or admin" : step.owner,
-      teamRows === null ? link("/settings/linear-teams") : step.where,
+      teamRows === null ? "catalyst contract --refresh" : step.where,
     ).next =
       teamRows === null
         ? "refresh the contract (catalyst contract --refresh), then run this again; the project list could not be read, so the host check cannot be either"
@@ -1030,7 +1048,7 @@ const DECL_INSTRUMENT =
   "environment_declared in catalyst contract --path teams";
 const DECL_REASONS = {
   no_team_repo_default: {
-    text: "no repository is the project's default yet: register one and make it the default",
+    text: "no repository is the project's default yet: register one and make it the default (catalyst onboard --team <KEY> --repo <owner/name> registers it; the default is chosen on Your projects, with no command yet)",
     who: "a workspace owner or admin",
     page: "/settings/projects",
   },
@@ -1050,7 +1068,7 @@ const DECL_REASONS = {
     page: null,
   },
   declaration_awaiting_approval: {
-    text: "the declaration is proposed and waits for approval: Settings → Your projects → the project → Repositories → the repository → Environment → Setup declaration → Approve this revision",
+    text: "the declaration is proposed and waits for approval, because no review approved it (a non-author approval of the merged head, or a merge by an owner or admin): approve it at Settings → Your projects → the project → Repositories → the repository → Environment → Setup declaration → Approve this revision (no command approves one repository's revision yet)",
     who: "a workspace owner or admin",
     page: "/settings/projects",
   },
@@ -1058,7 +1076,7 @@ const DECL_REASONS = {
 const DECL_DO =
   "write .catalyst/catalyst.toml with references/declaring-a-repository.md, then open a pull request";
 let declNext =
-  "commit .catalyst/catalyst.toml to the repository and have an owner or admin approve it";
+  "merge .catalyst/catalyst.toml through a pull request that someone other than the author approves; that review approves it";
 if (!connected) {
   add(
     "repository declarations",
@@ -1123,9 +1141,10 @@ if (!connected) {
   let unknown = false;
   const describe = (reason) =>
     DECL_REASONS[reason] ?? {
-      text: `environment_declared ${reason ?? "failed"} (a reason this bundle does not know; read it on the page)`,
+      text: `environment_declared ${reason ?? "failed"} (a reason this bundle does not know; catalyst ready --json prints its fix line)`,
       who: "a workspace owner or admin",
-      page: "/settings/projects",
+      page: null,
+      do: "catalyst ready --json",
     };
   const flag = (team, repo, reason) => {
     const r = describe(reason);
@@ -1133,7 +1152,7 @@ if (!connected) {
     if (verdict === "ok") declNext = `${repo ? `${repo}: ` : ""}${r.text}`;
     verdict = "unfinished";
     owner ??= r.who;
-    where ??= r.page === null ? DECL_DO : link(r.page);
+    where ??= r.do ?? (r.page === null ? DECL_DO : link(r.page));
   };
   if (found.length === 0) {
     lines.push(
@@ -1169,7 +1188,7 @@ if (!connected) {
   } else {
     if (verdict !== "ok")
       lines.push(
-        "Names only: a value never passes through this script or the file. The person enters values on the repository's Environment page.",
+        "Names only: a value never passes through this script or the file. The person enters each value at a hidden prompt: catalyst var set NAME --repo <owner/name>, or catalyst secret set NAME --repo <owner/name> for a secret.",
       );
     add(
       "repository declarations",
@@ -1285,18 +1304,22 @@ const NEXT = {
       : personalGithubIncomplete
         ? "install the tenant GitHub App and register its repository before connecting your personal GitHub account"
         : "get this person's seat and Linear identity sorted",
-  account:
-    "connect the Linear integration on the Integrations page (the GitHub App comes later, with the repository)",
+  account: onboardAvailable()
+    ? "start the Linear integration with catalyst onboard and hand over the consent link it prints (the GitHub App comes later, with the repository)"
+    : "connect the Linear integration on the Integrations page (the GitHub App comes later, with the repository)",
   projects:
     blockedProjects.length > 0
       ? blockedProjects.map((b) => b.action).join("; and ")
       : verbAvailable("team map")
         ? "pick ONE project: run catalyst team list, then catalyst team map <KEY> (or team adopt <KEY>) and approve its preview"
         : verbAdminOnly("team map")
-          ? "a workspace owner or admin maps ONE project: catalyst team map <KEY>, or Map my stages on the projects page"
-          : "pick ONE project and map its stages (or adopt the Catalyst workflow)",
-  repositories:
-    "install the GitHub App on the Integrations page, granting it the repository you want worked; register it on Your projects and attach it to the project before continuing",
+          ? "a workspace owner or admin maps ONE project: catalyst team map <KEY> (or team adopt <KEY>), approving its preview"
+          : capability("team map")
+            ? "pick ONE project and map its stages (or adopt the Catalyst workflow) on the projects page; this cloud does not serve catalyst team map yet"
+            : `pick ONE project and map its stages with catalyst team map <KEY> (or team adopt <KEY>); this CLI is too old for that verb, so update it first: ${UPDATE_CLI}`,
+  repositories: onboardAvailable()
+    ? "install the GitHub App from the link catalyst onboard prints, granting it the repository you want worked; then register it and attach it to the project with catalyst onboard --team <KEY> --repo <owner/name> before continuing"
+    : "install the GitHub App on the Integrations page, granting it the repository you want worked; register it on Your projects and attach it to the project before continuing",
   "coding accounts": accountsNext,
   "repository declarations": declNext,
   "repository agent setup": repoNext ?? "read the checkout's agent setup again",
@@ -1365,7 +1388,7 @@ function versionAdvice() {
   const latest = npm.error || npm.status !== 0 ? null : semver(npm.stdout);
   // The installer is the update path, not `catalyst install`. Its command is on the app's
   // setup page; this names the script it fetches rather than composing the request here.
-  const reinstall = `re-run the install command from the app's setup page (it installs from ${link("/install.sh")})`;
+  const reinstall = `run ${UPDATE_CLI}, or re-run the install script at ${link("/install.sh")}`;
   if (installed === null || latest === null) {
     return {
       text: `Whether a newer Catalyst CLI is published could not be checked. You can ${reinstall}; if this still appears afterwards, tell the Catalyst team.`,

package/skills/run-this-project/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Own one Catalyst Cloud project end to end until it closes. Use when the person says "run this project for me", "own this until it ships", "keep this moving", or hands you a project id or a set of tickets to drive. Subscribes to the account's event stream for the scope through the catalyst CLI, reacts to each change in the same turn, makes tickets ready and moves them to dispatch, parks what should stop, chases stalls, escalates inward, and keeps one status summary current. Writes to Linear as the app actor; never polls.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.1 — written in this repository for customer accounts -->
 
 # Run this project
 

package/skills/run-this-project/references/stalls-and-escalation.md

@@ -17,7 +17,7 @@ Run `catalyst explain <ticket>` and look the reason up in the `whats-happening`
 - **It releases itself:** wait for the outcome card.
 - **The person, with their own login, acts:** do it when the move is yours (re-dispatch, a comment that clears a no-change or validate-budget hold, a question routed to `what-needs-me`), and file an ask when it is theirs.
 - **A park or hold a release clears:** once its cause is fixed, the `unstick` skill releases it (`catalyst release <ticket> --because <what changed>`). A round-threshold hold and a review that will not converge refuse that release; the table says what clears each.
-- **An owner or admin, in settings, or an operator:** one ask per repository or setting.
+- **An owner or admin, in settings, or an operator:** when the person holds that seat and a command can make the change, offer to run it; otherwise one ask per repository or setting.
 - **Finished:** close the loop in the summary.
 
 Quote a reason the table does not know as the explainer spelled it.

package/skills/unstick/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Get a stuck Catalyst Cloud ticket moving again. Use when the person asks "why is this parked and can you release it?", "unpark this", "get things flowing again", "the outage is over, retry what failed", or hands you a ticket that is not moving. Reads why nothing runs and what holds the ticket through the catalyst CLI, decides whether the recorded cause is fixed, previews the release, releases every governor holding the ticket the right way (or one failure class across a team), and raises an ask only for what a person has to do. Never releases a cause it cannot show changed without saying so.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.1 — written in this repository for customer accounts -->
 
 # Unstick
 

package/skills/what-needs-me/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   The human's decision inbox on Catalyst Cloud, and the one way an agent raises a decision on their behalf. Use when the person asks "what needs me?", "what am I blocking?", or when active work is gated on a choice only they can make. Lists open asks ranked by how much open work each one holds, files an ask through the cloud's ask route with the account's own template, and records the answer so the held work releases. Never answers as the human, never duplicates an open ask.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.1 — written in this repository for customer accounts -->
 
 # What needs me
 
@@ -15,7 +15,7 @@ An ask is one decision only the human can make, filed as a ticket in their own L
 Scripts are run, never read. Each prints `--help`; exit 2 means this machine is not connected (the `catalyst-onboard` skill connects it), exit 1 means the check itself failed or an argument was missing.
 
 - `node scripts/inbox.mjs --help`: the open asks assigned to the connected person, most open tickets held first, then the oldest; `--anyone` for everyone's; `--json` for `{scope, asks}`.
-- `node scripts/raise.mjs --help`: file one decision: `--team`, `--title`, `--option` (repeated), `--default`, and `--blocks` (repeated) or `--nothing-to-block`.
+- `node scripts/raise.mjs --help`: file one decision: `--team`, `--title`, `--option` (repeated), `--default`, and `--blocks` (repeated) or `--nothing-to-block`. When the ask decides whether a held PR may merge, `--gates-pr` (repeated) with `--released-by <letter>` makes the answer lift that PR's hold label.
 - `node scripts/settle.mjs --help`: record the answering comment on an ask and post a release note on every ticket it held; `--close` moves the ask to the done slot.
 
 ## Load on demand

package/skills/what-needs-me/references/raising-a-decision.md

@@ -4,7 +4,7 @@ The body, headings, option format and option cap come from the contract's `askTe
 
 ## When to file one
 
-File an ask when active work is gated on a product call, a priority call between two things that cannot both go first, an approval, or an action only the human can take (a click in settings, a credential, a payment). File it **before** proceeding on the default. A TODO line, board row, handoff note or chat question may point at the ask's identifier, never replace it.
+File an ask when active work is gated on a product call, a priority call between two things that cannot both go first, an approval, or an action only the human can take (a sign-in or consent, a credential, a payment). A settings change a command can make is yours to offer, not an ask. File it **before** proceeding on the default. A TODO line, board row, handoff note or chat question may point at the ask's identifier, never replace it.
 
 Brainstorming, design back-and-forth, a question the human asked first, a retry-or-abandon call a project owner can make, and a system-level failure (one status line; the tickets retry on their own) are not asks.
 
@@ -18,6 +18,17 @@ Brainstorming, design back-and-forth, a question the human asked first, a retry-
 
 `--ask-key` is an idempotency key: a re-run with the same key does not file a second ask.
 
+## When the answer releases a PR hold
+
+When the decision is whether a held PR may merge, name the PR so the answer lifts the hold itself:
+
+- `--gates-pr <n>` (repeated): each PR the answer releases.
+- `--released-by <letter>` (repeated, required with `--gates-pr`): the option letters that release it. Options are lettered A, B, C in the order you gave them, and a letter outside that range is refused.
+- `--gates-label hold|hold:preview` (repeated, default `hold`): the labels the answer removes. No other label is accepted.
+- `--gates-repo <owner/name>`: the PR's repository. It defaults to the account's repository when the account registers exactly one, and must be one the account registers.
+
+An answer with any other letter leaves the labels in place.
+
 ## One ask per decision
 
 Run `node scripts/inbox.mjs` first. When the same decision is already open, attach the new held tickets to it (the `catalyst-linear` skill adds the relation or a comment) rather than filing a twin that splits its urgency.

package/skills/what-needs-me/references/reading-the-inbox.md

@@ -19,7 +19,7 @@ So an ask that holds nothing is real, but the person may never see it in their o
 
 ## The identity is not the same as the personal Linear grant
 
-When asks are not reaching someone, check the identity first, then the grant. The **identity** is who they are in Linear, resolved by an email match or matched by the person (`catalyst identity linear status`, `options`, then `catalyst identity linear set <linearUserId>`). The **personal Linear grant** is proven by connecting Linear themselves. Connecting Linear personally does **not** set the identity. An auto-resolved identity, or one another member claims, needs an owner or admin at Settings → Members. With no identity nothing is assigned to them, even after they connect Linear, so an `unmatched` scope is not an empty queue: say "nothing is assigned to you yet, so this is everyone's list; match your identity with `catalyst identity linear set` and it becomes yours".
+When asks are not reaching someone, check the identity first, then the grant. The **identity** is who they are in Linear, resolved by an email match or matched by the person (`catalyst identity linear status`, `options`, then `catalyst identity linear set <linearUserId>`). The **personal Linear grant** is proven by connecting Linear themselves. Connecting Linear personally does **not** set the identity. An auto-resolved identity, or one another member claims, needs an owner or admin at Settings → Members; no command does this yet, so raise an ask to them. With no identity nothing is assigned to them, even after they connect Linear, so an `unmatched` scope is not an empty queue: say "nothing is assigned to you yet, so this is everyone's list; match your identity with `catalyst identity linear set` and it becomes yours".
 
 ## Presenting the queue
 

package/skills/what-needs-me/scripts/raise.mjs

@@ -14,12 +14,16 @@ const SPEC = {
   blocks: { value: true, repeat: true, help: "a ticket this decision holds (repeat per ticket)" },
   "nothing-to-block": { value: false, help: "declare that no ticket is held (the ask then never shows in Waiting on me)" },
   "ask-key": { value: true, help: "idempotency key so a re-run does not file a second ask" },
+  "gates-pr": { value: true, repeat: true, help: "a PR whose hold label the answer removes (repeat per PR; needs --released-by)" },
+  "gates-label": { value: true, repeat: true, help: "the hold the answer removes: hold or hold:preview (repeatable; default hold)" },
+  "released-by": { value: true, repeat: true, help: "an option letter whose answer releases the hold (repeat per letter)" },
+  "gates-repo": { value: true, help: "the --gates-pr repository as owner/name (default: the account's only repository)" },
   json: { value: false, help: "print the cloud's response as JSON" },
 };
 
 const { help, flags } = parseFlags(process.argv.slice(2), SPEC);
 if (help) {
-  printHelp("node scripts/raise.mjs --team <key> --title <question> [--context <text>] [--option <text>]... [--default <text>] --blocks <ticket>... | --nothing-to-block [--ask-key <key>] [--json] [--help]", SPEC, [
+  printHelp("node scripts/raise.mjs --team <key> --title <question> [--context <text>] [--option <text>]... [--default <text>] --blocks <ticket>... | --nothing-to-block [--ask-key <key>] [--gates-pr <n>... --released-by <letter>... [--gates-label hold|hold:preview]... [--gates-repo <owner/name>]] [--json] [--help]", SPEC, [
     "Search for an existing ask first (node scripts/inbox.mjs); one decision, one ask.",
     "File BEFORE proceeding on the default. Cite the identifier only from this script's output.",
   ]);
@@ -41,6 +45,10 @@ if (flags.default) args.push("--default", flags.default);
 for (const b of flags.blocks ?? []) args.push("--blocks", b);
 if (flags["nothing-to-block"]) args.push("--nothing-to-block");
 if (flags["ask-key"]) args.push("--ask-key", flags["ask-key"]);
+for (const n of flags["gates-pr"] ?? []) args.push("--gates-pr", n);
+for (const l of flags["gates-label"] ?? []) args.push("--gates-label", l);
+for (const l of flags["released-by"] ?? []) args.push("--released-by", l);
+if (flags["gates-repo"]) args.push("--gates-repo", flags["gates-repo"]);
 args.push("--json");
 
 const result = parseJson(mustRun(args, { quiet: true }).stdout, "ask raise");
@@ -49,5 +57,6 @@ if (flags.json) process.stdout.write(JSON.stringify(result) + "\n");
 else {
   process.stdout.write(`ask raised: ${id ?? "(no identifier returned)"}${flags.blocks ? ` — holds ${flags.blocks.join(", ")}` : " — holds nothing"}\n`);
   if (flags.default) process.stdout.write(`default if silent: ${flags.default}\n`);
+  if (flags["gates-pr"]) process.stdout.write(`answer ${flags["released-by"].join(" or ")} releases the hold on PR ${flags["gates-pr"].map((n) => `#${n}`).join(", ")}\n`);
 }
 process.exit(0);

package/skills/what-this-repo-needs/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   What environment variable names does this repository need, and where does each one come from? Scans the repository offline (no login, no network) and lists the names in three groups (build/test, deploy-only, bindings), each with where it was found, what uses it, and where a local value would come from. Never reads a value or prints one. Also checks the environment variable table in `.catalyst/catalyst.toml` offline. Use when someone asks "what does catalyst.env.json mean", "what env vars does this repo need", "why does the container need this", or before reviewing or writing the declaration.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.1 — written in this repository for customer accounts -->
 
 # What this repository needs
 

package/skills/whats-happening/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: whats-happening
 description: >-
-  Use for "what's happening?", "where are we?", "why is that stuck?", "what closed?", "what's next?", "how does this work?", "why did it do that?", "how does it prioritise?" and "what does this setting do, where is it set?" in Catalyst Cloud, or asks for something to be done rather than known. Reads the contract via catalyst CLI. Read-only: route work/decisions, never answer as the human.
+  Use for "what's happening?", "what machines do we have?", "how much capacity do we have?", "where are we?", "why is that stuck?", "what closed?", "what's next?", "how does this work?", "why did it do that?", "how does it prioritise?" and "what does this setting do, where is it set?" in Catalyst Cloud, or asks for something to be done rather than known. Reads the contract via catalyst CLI. Read-only: route work/decisions, never answer as the human.
 allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.15.6 — written in this repository for customer accounts -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.16.1 — written in this repository for customer accounts -->
 
 # What's happening
 
@@ -20,6 +20,7 @@ Comments/relations: catalyst-linear. PRs: catalyst-github. Readiness: catalyst-o
 
 | question | reference |
 | -- | -- |
+| machines or machine capacity? | references/machines.md |
 | status or stuck? | references/status-reply.md; schema assets/status-reply.json |
 | eligibility reason? | references/why-is-it-stuck.md |
 | order, capacity, WIP or routing? | references/what-runs-next.md |

package/skills/whats-happening/references/coding-accounts.md

@@ -1,6 +1,6 @@
 # Coding accounts
 
-snapshot.mjs --accounts omits credentials/emails. An owner/admin enrols, pauses, removes or replaces credentials at `<their cloud>/settings/coding-accounts`.
+snapshot.mjs --accounts omits credentials/emails. An owner/admin enrols, pauses, removes or replaces credentials at `<their cloud>/settings/coding-accounts`; no command does these yet. `catalyst accounts` reads them.
 
 Slots identify credentials, not emails. Claude/GLM/Qwen use Claude CLI, Codex uses Codex; GLM/Qwen also use OpenCode. Routing names the model.
 

package/skills/whats-happening/references/machines.md

@@ -0,0 +1,9 @@
+# Machines and capacity
+
+Run `catalyst hosts --json` when someone asks what machines their account has or how much capacity is available. Name `catalyst hosts` as the command behind the answer. The same read is available through the SDK's `client.hosts.list()`.
+
+List each machine's name, whether it is self-hosted or Catalyst's, its teams, slots in use and free, last check-in, and live or stale status. A self-hosted machine uses the name its customer chose. Catalyst's machines say Cloud followed by the server or service name.
+
+Use the response's capacity total. It already counts a cloud machine shared across teams once and excludes stale machines. A machine is stale when its runtime proof has expired or it has not checked in for 15 minutes. A stale machine stays in the list, with its last check-in, but contributes no live capacity. A missing check-in is unknown, not proof that a machine is live. A failed read is inconclusive; never report zero machines or zero capacity from a failure.
+
+For a requested change, an admin can run `catalyst hosts rename <name-or-id> <new-name>` or `catalyst hosts remove <name-or-id>`. Removal asks for confirmation; `--yes` records explicit consent for an unattended invocation. A member can read but cannot change machines. When a name matches more than one machine, use its ID. An admin choosing to run work on a new machine can name it during `catalyst setup`, or pass `--machine-name <name>`.

package/skills/whats-happening/references/settings-and-where-they-live.md

@@ -1,17 +1,17 @@
 # Settings
 
-Use live values and the person's cloud prefix. Owner/admin acts unless stated. Name screen, route, rule.
+Use live values and the person's cloud prefix. Owner/admin acts unless stated. Name screen, route, rule. Where a command does the change, offer to run it before naming the screen.
 
 | screen and route | rule |
 | -- | -- |
-| Integrations, /settings/connections | Connecting Linear needs admin browser session, which chooses the account. A workspace binds to exactly one account and vice versa; a conflict needs a decision, not retry. |
-| Profile, /settings/profile, then Connections | The personal GitHub grant comes first; missing identity or another person's installation refusal means grant personal GitHub first. |
+| Integrations, /settings/connections | Connecting Linear needs an admin's consent in their browser, which chooses the account; `catalyst onboard` starts it and prints the consent link. A workspace binds to exactly one account and vice versa; a conflict needs a decision, not retry. |
+| Profile, /settings/profile, then Connections | The personal GitHub grant comes first; missing identity or another person's installation refusal means grant personal GitHub first. Offer `catalyst connections personal github start` and hand over the link it prints. |
 | Connections | Removing the App on GitHub self-heals the registry; Catalyst unlink uninstalls upstream; neither needs support. |
-| Your projects, /settings/projects | Each Catalyst project pairs one Linear team with its registered GitHub repositories. Manage the project, attach repositories, and choose the team's default repository here. |
-| Merging, /settings/projects/$projectId/repositories/$repoId/merging | Merge policy is changed here; contract merge gives value/source; catalyst-github only reads. |
-| Code reviews, /settings/projects/$projectId/repositories/$repoId/code-reviews | Post review requests as selects a connected member. Strict policy without reviewer never earns ready label; configure reviewer or change policy. |
+| Your projects, /settings/projects | Each Catalyst project pairs one Linear team with its registered GitHub repositories. Attach a repository with `catalyst onboard --team <KEY> --repo <owner/name>`; choose the team's default repository here, with no command for that yet. |
+| Merging, /settings/projects/$projectId/repositories/$repoId/merging | Merge policy is the variable `CATALYST_MERGE_EVIDENCE_POLICY`: offer `catalyst var set CATALYST_MERGE_EVIDENCE_POLICY --repo <owner/name>`, or change it here. A policy declared in `.catalyst/catalyst.toml` wins over the variable: change it there in a pull request; contract merge gives value/source; catalyst-github only reads. |
+| Code reviews, /settings/projects/$projectId/repositories/$repoId/code-reviews | Post review requests as selects a connected member. Strict policy without reviewer never earns ready label; configure reviewer here (no command yet) or change policy. |
 | Merge queue, no Catalyst page | After ready label, the merge itself is whatever the repository's own setup does with it; the repo admin owns this. This bundle cannot identify its queue vendor; never guess. |
 | Repositories | Shows operator-set runner cap, default 20, paused effective zero; see what-runs-next.md. |
-| Secrets /settings/secrets and Environment /settings/environment, plus repository sections | Secrets write-only, variables readable; names are never both. Repository values override account values. Variables may reference vault secrets, expanded only in container. |
-| Repositories | Without a registered team nothing reaches a runner, and the failure is silent; raise admin/operator fix as ask. |
+| Secrets /settings/secrets and Environment /settings/environment, plus repository sections | Secrets write-only, variables readable; names are never both. Repository values override account values. Variables may reference vault secrets, expanded only in container. Offer `catalyst var set NAME [--repo <owner/name>]` or `catalyst secret set NAME --repo <owner/name>`; a workspace-wide secret has no command yet. |
+| Repositories | Without a registered team nothing reaches a runner, and the failure is silent; an owner or admin can register it with `catalyst onboard --team <KEY> --repo <owner/name>`, so offer that, otherwise raise the fix as an ask. |
 | Routing, no settings page for this | Global stage defaults and empty per-account table select default provider; never promise Codex-first. |

package/skills/whats-happening/references/stages-and-mapping.md

@@ -14,6 +14,6 @@ Order: dispatch, intake, research, plan, implement, remediate, verify, review, p
 
 Missing/wrong required mappings stop work; others warn. Dispatch/pr/done/canceled must be live. `teams[].gitAutomation` stores consent; nothing reads it.
 
-workflowMode: adopted means Catalyst-created, mapped means human-chosen, mixed means both. Configure at `<their cloud>/settings/linear-teams`, never catalyst.toml.
+workflowMode: adopted means Catalyst-created, mapped means human-chosen, mixed means both. Configure with `catalyst team map <KEY>` or `catalyst team adopt <KEY>` (offer to run it for an owner or admin), never catalyst.toml.
 
 stateId is authoritative; imports can replace ids but keep names. catalyst-linear resolves slots to ids. stateStillExists: false refuses the move; remap with `catalyst team map <KEY>`. Backlog is not a slot: parking resolves a live backlog-type state. catalyst-onboard explains readiness and who fixes it.