@catalyst-cloud/cli 0.9.5 → 0.13.1

package/skills/catalyst-github/scripts/is-it-mergeable.mjs

@@ -2,7 +2,7 @@
 // is-it-mergeable.mjs — the three legs of merge evidence for one PR (checks, reviewer signal,
 // unresolved threads) judged under the policy the tenant contract resolves for its repository, plus
 // the prerequisites a queue applies before any leg counts (open, not a draft, no conflict). Every
-// input comes from `catalyst-skills query`, `contract` and, when fresh, `replica sql`.
+// input comes from `catalyst query`, `contract` and, when fresh, `replica sql`.
 // Exit 0 no leg is red, 1 a leg or prerequisite is red, 2 this machine is not connected.
 import { parseJson, runCli, runCliOrExit } from "./lib/cli.mjs";
 import { resolvePull, truthy } from "./lib/pull.mjs";
@@ -34,7 +34,7 @@ if (!target) {
 const { ticket, detail } = resolvePull(target);
 const merge = parseJson(runCliOrExit(["contract", "--path", "merge", "--json"]).stdout);
 if (!merge || !Array.isArray(merge.policies)) {
-  console.error("the contract's merge block did not parse; run: catalyst-skills contract --refresh");
+  console.error("the contract's merge block did not parse; run: catalyst contract --refresh");
   process.exit(1);
 }
 
@@ -103,7 +103,7 @@ if (replica && replica.verdict === "fresh") {
   else if (unknown > 0) add("threads", "inconclusive", `${unknown} thread(s) with no resolved flag mirrored`);
   else add("threads", "pass", `${count(1)} thread(s), all resolved (ancestry against force-pushes is judged by the cloud, not here)`);
 } else {
-  add("threads", "inconclusive", `the PR detail carries no thread count and the replica is ${replica?.verdict ?? "unavailable"}; start it (catalyst-skills replica start --detach) for a local read`);
+  add("threads", "inconclusive", `the PR detail carries no thread count and the replica is ${replica?.verdict ?? "unavailable"}; start it (catalyst replica start --detach) for a local read`);
 }
 
 const failed = legs.filter((l) => l.state === "fail");

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // lib/cli.mjs — the one way a skill script reaches the Catalyst Cloud SDK and API: by spawning the
-// catalyst-skills CLI this bundle installed. It reads customer.json to find that CLI and nothing
+// catalyst CLI this bundle installed. It reads customer.json to find that CLI and nothing
 // else; it never holds the key itself. This file is a library — run a sibling script with
 // --help for usage. Identical in every skill of this bundle on purpose (skills install one directory
 // at a time, so nothing shared outside the skill would ever be installed).
@@ -10,7 +10,9 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 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 CONNECT_HINT = `this machine is not connected to a tenant yet — run: ${CONNECT_COMMAND}`;
 
 /** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME before HOME. */
@@ -41,15 +43,15 @@ export function requireCustomerConfig() {
 }
 
 /**
- * Run one catalyst-skills verb and return {code, stdout, stderr}. Spawns the CLI whose path the
- * connect step recorded in customer.json; falls back to `npx @catalyst-cloud/catalyst-skills` when
+ * Run one catalyst verb and return {code, stdout, stderr}. Spawns the CLI whose path the
+ * connect step recorded in customer.json; falls back to `npx -p @catalyst-cloud/cli catalyst` when
  * no path is recorded or it no longer exists. Exits 2 when the machine is not connected.
  */
 export function runCli(args, opts = {}) {
   const cfg = requireCustomerConfig();
   const recorded = typeof cfg.cliPath === "string" && existsSync(cfg.cliPath);
   const command = recorded ? process.execPath : process.platform === "win32" ? "npx.cmd" : "npx";
-  const argv = recorded ? [cfg.cliPath, ...args] : [PACKAGE, ...args];
+  const argv = recorded ? [cfg.cliPath, ...args] : [...NPX_ARGS, ...args];
   const res = spawnSync(command, argv, {
     encoding: "utf8",
     input: opts.stdin,
@@ -58,7 +60,7 @@ export function runCli(args, opts = {}) {
     shell: !recorded && process.platform === "win32",
   });
   if (res.error) {
-    console.error(`could not run ${recorded ? cfg.cliPath : `npx ${PACKAGE}`}: ${res.error.message}`);
+    console.error(`could not run ${recorded ? cfg.cliPath : `npx -p ${PACKAGE} catalyst`}: ${res.error.message}`);
     process.exit(2);
   }
   return { code: res.status ?? 1, stdout: res.stdout ?? "", stderr: res.stderr ?? "" };
@@ -72,7 +74,7 @@ export function runCli(args, opts = {}) {
 export function runCliOrExit(args, opts = {}) {
   const res = runCli(args, opts);
   if (res.code === 0) return res;
-  const why = res.stderr.trim() || res.stdout.trim() || `catalyst-skills ${args.join(" ")} exited ${res.code}`;
+  const why = res.stderr.trim() || res.stdout.trim() || `catalyst ${args.join(" ")} exited ${res.code}`;
   console.error(why);
   process.exit(res.code === 2 ? 2 : 1);
 }

package/skills/catalyst-github/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-github/scripts/read-pr.mjs

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 // read-pr.mjs — one ticket's pull request (or one PR by node id) as the mirror holds it: state,
 // branch, head, base, linked ticket and its stage, GitHub's own mergeable verdict, every check,
-// review and commit status. Reads through `catalyst-skills query`; composes no URL.
+// review and commit status. Reads through `catalyst query`; composes no URL.
 import { linkedPulls, resolvePull, truthy } from "./lib/pull.mjs";
 
 const HELP = `Usage: node scripts/read-pr.mjs <ticket | pr-node-id> [--all] [--json]
 
   <ticket>       a ticket identifier such as ABC-123: its open PR is shown (else the merged one, else the newest)
-  <pr-node-id>   a GitHub pull-request node id, as printed by "catalyst-skills query pulls"
+  <pr-node-id>   a GitHub pull-request node id, as printed by "catalyst query pulls"
   --all          for a ticket: list every PR that names it instead of one detail
   --json         print the raw detail document instead of the summary
 

package/skills/catalyst-linear/SKILL.md

@@ -1,26 +1,25 @@
 ---
 name: catalyst-linear
 description: >-
-  Catalyst's view of Linear on the customer's own tenant. Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the local replica when it is fresh and the origin-fresh API otherwise, always naming the source; searches tickets, PRs, projects and initiatives; writes comments, card moves, labels and new tickets through the tenant's agent proxy as the app actor, with every route, stage id, label id and marker read from the tenant contract. Knows what a ticket accumulates as Catalyst works it (phase-outcome comments, the document per phase, the agent session, the labels, the single blocks relation, the bookkeeping marker, the eyes acknowledgement). Use when a person says "show me the ticket", "what did Catalyst write on it", "comment on it", "move it", "label it" or "file a ticket". Not for raising a decision for a human (what-needs-me) and not for pull requests (catalyst-github).
-allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
-disable-model-invocation: true
+  Catalyst's view of Linear on the customer's own cloud account. Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the local replica when it is fresh and the origin-fresh API otherwise, always naming the source; searches tickets, PRs, projects and initiatives; writes comments, card moves, labels and new tickets through the account's agent proxy as the app actor, with every route, stage id, label id and marker read from the account's contract. Knows what a ticket accumulates as Catalyst works it (phase-outcome comments, the document per phase, the agent session, the labels, the single blocks relation, the bookkeeping marker, the eyes acknowledgement). Use when a person says "show me the ticket", "what did Catalyst write on it", "comment on it", "move it", "label it" or "file a ticket". Not for raising a decision for a human (what-needs-me) and not for pull requests (catalyst-github).
+allowed-tools: Bash(catalyst:*) Bash(npx -p @catalyst-cloud/cli catalyst:*)
 ---
-<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.9.5 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.1 — written in this repository for customer accounts -->
 
 # Catalyst Linear
 
-You read tickets and write to them on the customer's tenant, as Catalyst. Reads come from the replica when it is fresh, else from the API, and every read names its source. Writes go through the tenant's agent proxy as the app actor, with routes, stage ids, label ids and the bookkeeping marker resolved from the tenant contract by the `catalyst-skills` CLI. You never compose a URL, never name a stage by its display name, and never quote a label id or marker from memory.
+You read tickets and write to them in the person's cloud account, as Catalyst. Reads come from the replica when it is fresh, else the API, and name their source. Writes go out as the app actor, with routes, stage ids, label ids and the bookkeeping marker resolved from the contract by the `catalyst` CLI.
 
 ## Run first
 
-Run each with `--help` first; scripts are executed, never read.
+Scripts are run, never read; each prints `--help`.
 
-- `node scripts/read-ticket.mjs <ticket> [--comments]` — one ticket, everything inline, source line on stderr.
-- `node scripts/search.mjs <terms>` — tickets, PRs, projects, initiatives matching the terms.
-- `node scripts/comment.mjs <ticket> --body <text> [--parent <id>] [--bookkeeping]` — a comment as the app actor; a machine record takes `--bookkeeping`.
-- `node scripts/move.mjs <ticket> --slot <slot>` — a card move by slot (`--state-type backlog` parks).
-- `node scripts/label.mjs <ticket> --add <name> --remove <name>` — labels, resolved through the contract.
-- `node scripts/create-ticket.mjs --team <key> --title <text> [--description <text> | --stdin]` — a new ticket; cite its identifier only after it prints.
+- `node scripts/read-ticket.mjs <ticket> [--comments]`: one ticket, everything inline, source line on stderr.
+- `node scripts/search.mjs <terms>`: tickets, PRs, projects, initiatives matching the terms.
+- `node scripts/comment.mjs <ticket> --body <text> [--parent <id>] [--bookkeeping]`: a comment as the app actor.
+- `node scripts/move.mjs <ticket> --slot <slot>`: a card move by slot (`--state-type backlog` parks).
+- `node scripts/label.mjs <ticket> --add <name> --remove <name>`: labels, resolved through the contract.
+- `node scripts/create-ticket.mjs --team <key> --title <text> [--description <text> | --stdin]`: a new ticket; cite its identifier only after it prints.
 
 Exit codes: 0 done, 1 not found or a usage error, 2 this machine is not connected or the write was refused (budget spent, slot unmapped, label absent; the one line printed says which).
 
@@ -34,10 +33,9 @@ Exit codes: 0 done, 1 not found or a usage error, 2 this machine is not connecte
 
 ## Rules
 
-- **Read before acting.** Never summarise a ticket from its title; read the description and the thread. Cite identifiers and comment ids only after a script printed them.
-- **Name the source.** Quote the source line when freshness matters; a stale replica is never read silently, because the CLI falls back to the API and says so.
-- **Reply where it arrived, as Catalyst.** Thread under the comment you answer (`--parent`); never post as the human.
-- **Records carry the marker.** A merge note, a state-move log, a chain summary: `--bookkeeping`, so it never reads as a human turn. A real question is not bookkeeping.
-- **Move by slot, label by contract.** A stage name is display; the id is the authority, and the CLI resolves both. Moving to `dispatch` dispatches; the backlog-type state parks.
-- **A decision is an ask, not a ticket.** Raise it through `what-needs-me` with options, a default and what it blocks; a question filed as a ticket is held out of dispatch by shape.
-- **One write per need, no loops.** Writes spend a daily budget the contract names; batch, and report a refusal rather than retrying.
+- **Read before acting.** Read the description and the thread, never just the title. Cite identifiers and comment ids only after a script printed them, and quote the source line when freshness matters.
+- **Reply where it arrived, as Catalyst.** Thread under the comment you answer (`--parent`); the human speaks for themselves.
+- **Records carry the marker.** A merge note, a state-move log, a chain summary: `--bookkeeping`. A real question is not bookkeeping.
+- **Move by slot, label by contract.** Moving to `dispatch` dispatches; the backlog-type state parks.
+- **A decision is an ask, not a ticket.** Raise it through `what-needs-me`; a question filed as a ticket is held out of dispatch by shape.
+- **One write per need.** Every write is visible in the person's Linear and spends the contract's daily budget; batch, and report a refusal once. A move into dispatch starts paid work on a coding account.

package/skills/catalyst-linear/agents/openai.yaml

@@ -3,4 +3,4 @@ interface:
   short_description: "Read a ticket and what Catalyst wrote on it; comment, move, label and file tickets as the app actor"
   default_prompt: "Use $catalyst-linear to show me the ticket, its history, and what Catalyst wrote on it."
 policy:
-  allow_implicit_invocation: false
+  allow_implicit_invocation: true

package/skills/catalyst-linear/agents/portability.yaml

@@ -1,5 +1,5 @@
 identity: { pack: catalyst-cloud-skills, skill: catalyst-linear }
 effects: [external-write]
 mutating: true
-invocation: explicit
+invocation: implicit
 exposure: [catalog]

package/skills/catalyst-linear/references/reading-a-ticket.md

@@ -1,24 +1,20 @@
 # Reading a ticket: freshness first, then the row
 
-This reference restates invariants about how a read is made and reported. Nothing in it is a tenant value.
-
 ## Freshness first
 
 Every `query` verb, and therefore `node scripts/read-ticket.mjs` and `node scripts/search.mjs`, prints one stderr line before the answer:
 
-- `source: replica (cursor N)` — the local replica was fresh (its writer heartbeat is young and its cursor non-empty), so the answer is local and cheap. N is the position it had applied.
-- `source: api (replica stale)`, `source: api (replica absent)` or `source: api (replica not configured)` — the answer came from the tenant API, which is origin-fresh: it reflects the mirror's latest ingest, not a cached copy.
-- `source: api (<verb> is api-only)` — search, cycles, pull detail and change feeds are never served from the replica.
+- `source: replica (cursor N)`: the local replica was fresh, so the answer is local and cheap.
+- `source: api (replica stale|absent|not configured)`: the answer came from the origin-fresh cloud API; a stale replica always falls back.
+- `source: api (<verb> is api-only)`: search, cycles, pull detail and change feeds never come from the replica.
 
-Read that line every time. A fresh replica is a preference; the API is the fallback and it is never wrong to read it. What is wrong is silently reading a stale replica, and the CLI does not let that happen: a stale replica falls back to the API and says so. Quote the source in your answer when the freshness of a fact matters ("as of the replica at cursor N" or "from the API just now").
+Quote the source when a fact's freshness matters ("as of the replica at cursor N", "from the API just now").
 
 `--source replica` or `--source api` forces one. Forcing the replica when it is absent or stale is refused.
 
 ## Then the row
 
-One ticket read returns the whole record: the fields, the description, `labels[]`, `relations[]`, `linked_pulls[]`, `comments[]`, `activity[]` and `agent_sessions[]` inline, plus the project, cycle, team, delegate and parent fields. One call answers "what is this ticket, what happened on it, what is it waiting on, which PR is it". There is no second call to make for the comments.
-
-The summary the script prints puts the counts first and the description last; `--comments` prints every comment with its id, author, time and whether the author is a bot. A comment with a `reply-to` marker is threaded under another; reply under the same parent when you answer it.
+One read returns the whole record inline: fields, description, `labels[]`, `relations[]`, `linked_pulls[]`, `comments[]`, `activity[]` and `agent_sessions[]`, plus project, cycle, team, delegate and parent. `--comments` prints every comment with its id, author, time and bot flag; a comment with a `reply-to` marker is threaded, so reply under the same parent.
 
 ## Reading Catalyst's own writes
 
@@ -28,25 +24,12 @@ The comment shapes in `references/what-a-ticket-accumulates.md` tell you which c
 2. Remediate-attempt comments give the failure class each round repaired.
 3. The projection-link comments name the documents; open the document (it is attached to the ticket) to read what a phase actually concluded. A fallback comment carries the body inline instead.
 4. `linked_pulls[]` names the PR; `catalyst-github` reads it.
-5. For "what will it do next", leave this skill: `how-catalyst-works` explains the eligibility row.
-
-## When to read a transcript
-
-A phase's transcript (the full session log) exists in the cloud per ticket, but this bundle has no verb for it yet. Read the artifact document first; it is the phase's own account of what it did. Reach for the transcript only when the document leaves the question open, and say that the bundle cannot fetch it so the human opens it from the ticket's attachments.
+5. For "what will it do next", leave this skill: `whats-happening` explains the eligibility row.
 
-## What the ledger adds to the comments
+The attempt ledger, the round count against the cap, and park state come from `catalyst explain --history <ticket>`; read the count there rather than reconstructing it from comments. A phase's full transcript has no verb in this bundle: read the artifact document first, and if it leaves the question open, say the human can open the transcript from the ticket.
 
-Per-ticket execution history beyond the comments (the attempt ledger, the remediation round count against the cap, park state and what releases it) is `catalyst-skills explain --history <ticket>`, read from the cloud's own relay ledger. Do not reconstruct a round count from comments and present it as the cap's count; read it.
-
-## How to cite
-
-- Cite a ticket by its identifier (`KEY-123`), never by title alone, and only after you read it back from a script's output.
-- Cite a comment by its id when you refer to it or reply under it.
-- Cite a document by the title the projection comment gave it.
-- Never summarise a ticket from its title. Read the description and the thread.
+Cite a ticket by its identifier (`KEY-123`), a comment by its id, and a document by the title its projection comment gave it.
 
 ## Searching and listing
 
-`node scripts/search.mjs <terms>` matches ticket identifiers and titles, PR titles, project and initiative names and returns a few of each. It is the only search; a list read with a filter is not a search and will hand back the ordinary first page, which reads as a false "not found". Lists (`catalyst-skills query issues --team <key>`, `query projects`, `query cycles`) are for a board view, not for finding one ticket.
-
-A list verb now says when the cloud cut it short: without `--all`, `query issues`/`query pulls` print `truncated at N of M` on stderr the moment a scope holds more than one page. `query issues --all` and `query pulls --all` follow the cloud's page cursor to the end of the scope instead of stopping at the first page — use `--all` when the count, not just a sample, has to be right.
+`node scripts/search.mjs <terms>` matches identifiers, titles, PR titles, and project and initiative names. It is the only search: a filtered list hands back its first page, which reads as a false "not found". Lists (`catalyst query issues --team <key>`, `query projects`, `query cycles`) are board views. A list cut short prints `truncated at N of M` on stderr; `query issues --all` and `query pulls --all` follow the page cursor to the end, for when the count has to be right.

package/skills/catalyst-linear/references/what-a-ticket-accumulates.md

@@ -1,6 +1,6 @@
 # What a ticket accumulates as Catalyst works it
 
-This reference restates invariants: the shapes of what the cloud writes onto a ticket. The one live value it needs — the bookkeeping marker and the label names — is on the contract under `vocabulary` and `teams[].labels`; print them with `catalyst-skills contract --path vocabulary` and `catalyst-skills contract --path teams`. Never quote a marker or a label id from memory.
+The shapes of what the cloud writes onto a ticket are the same for every account. The live values (the bookkeeping marker and the label names) are on the contract under `vocabulary` and `teams[].labels`; print them with `catalyst contract --path vocabulary` and `catalyst contract --path teams`. Never quote a marker or a label id from memory.
 
 ## Comments the cloud posts
 
@@ -18,7 +18,7 @@ Every one of these is posted by the app actor and is skipped by the comment-wake
 
 ## One document per phase, attached
 
-Each artifact-bearing phase (research, plan, implement, validate, pr, remediate) projects its artifact into Linear as a document at a deterministic id, titled `<TICKET> · <phase> · attempt <n> · <YYYY-MM-DD>`, attached to the ticket, and announced by the projection-link comment above. Research and plan documents on a ticket that belongs to a project are also linked from the project. The same body is committed into the tenant's thoughts repository when one is configured. Reading the document is how you read what a phase concluded; the phase-outcome comment only summarises it.
+Each artifact-bearing phase (research, plan, implement, validate, pr, remediate) projects its artifact into Linear as a document at a deterministic id, titled `<TICKET> · <phase> · attempt <n> · <YYYY-MM-DD>`, attached to the ticket, and announced by the projection-link comment above. Research and plan documents on a ticket that belongs to a project are also linked from the project. The same body is committed into the account's thoughts repository when one is configured. Reading the document is how you read what a phase concluded; the phase-outcome comment only summarises it.
 
 ## The agent session
 

package/skills/catalyst-linear/references/writing-to-linear.md

@@ -1,6 +1,6 @@
 # Writing to Linear: identity, budget, slots, labels
 
-This reference restates the write mechanism. The live values it depends on — the route table, the daily write budget, the stage map, the label ids — are read by the CLI from the contract (`routes`, `thresholds`, `teams[].stages`, `teams[].labels`) on every write. Nothing here is a literal to copy.
+The CLI reads the route table, write budget, stage map and label ids from the contract on every write; nothing here is a literal to copy.
 
 ## Every write is one script
 
@@ -12,21 +12,19 @@ This reference restates the write mechanism. The live values it depends on — t
 | a new ticket | `node scripts/create-ticket.mjs --team <key> --title <text> [--description <text> \| --stdin]` |
 | a decision for a human | not here: the `what-needs-me` skill raises an ask with options, a default and what it blocks |
 
-Each script wraps one `catalyst-skills write` verb, which posts to the route the contract names, as the tenant's app actor, with the personal key this machine connected with — so the write carries the person's identity for attribution, and an ask names them. No script composes a URL, and none needs a Linear credential of its own.
+Each script wraps one `catalyst write` verb, which posts to the contract's route as the app actor with this machine's personal key, so the write is attributed to the person.
 
 ## App actor versus personal identity
 
-Every write goes out as the tenant's Catalyst app actor by default. That identity is what the cloud's own comment-wake trigger recognises as "not a human", so an app-actor comment never wakes an agent to reply to it, never needs the bookkeeping marker to be safe, and reads to the human as Catalyst speaking. `--as-user` switches a comment or a new ticket to the personal identity behind the key; use it only when the human asked for that attribution, and then mark any machine record with `--bookkeeping`, because on that path the record is indistinguishable from the human typing it.
-
-Reply where the message arrived: a comment inside a thread is answered with `--parent <commentId>`, in that thread, and never as a new ticket. Never post as the human; you speak as Catalyst, or as yourself by role.
+Writes go out as the app actor by default, which the comment-wake trigger recognises as not human, so an app-actor comment never wakes an agent and reads as Catalyst speaking. `--as-user` switches a comment or new ticket to the person's identity; use it only when they asked for that attribution, and then mark any machine record with `--bookkeeping`, because it is otherwise indistinguishable from them typing it. Answer a thread in that thread with `--parent <commentId>`.
 
 ## The daily write budget
 
-Every write route spends one unit of a per-host daily budget the contract publishes as `thresholds.hostDailyWriteBudget`; a label call spends one unit whatever the label count; reads spend none. When the budget is spent, the CLI refuses with exit 2 and a line that names the budget and the retry time. Do not retry in a loop; report it, and batch what you can into fewer writes (one comment, not five).
+Every write spends one unit of the per-host daily budget (`thresholds.hostDailyWriteBudget`), a label call one unit whatever its count; reads spend none. A spent budget exits 2 naming the retry time: report it, and batch into fewer writes.
 
 ## State moves are by slot, never by name
 
-`--slot <slot>` names one of the eleven slots; the CLI resolves it to this team's live state id from the contract. It refuses when the slot is unmapped for the team, and when the mapped state no longer exists in Linear (the map needs fixing in tenant settings first). Moving to `dispatch` is how work is dispatched; nothing is offered from any other column. Backlog is not a slot: `--state-type backlog` resolves the team's first backlog-type state from its live workflow states, and moving a card there parks it and stops remediation rounds. A move never fabricates a state id, and a move by stage name is not offered because names are display fields that survive re-imports while ids do not.
+`--slot <slot>` resolves to the team's live state id from the contract, and refuses when the slot is unmapped or its state is gone (re-map first: `catalyst team map <KEY>`). Moving to `dispatch` dispatches work. `--state-type backlog` resolves the team's first backlog-type state and parks the card, stopping remediation rounds. Names are display fields that survive re-imports while ids do not, so there is no move by name.
 
 ## Labels are by contract id
 
@@ -36,8 +34,8 @@ Two labels are a human's, not yours: the release label (which frees a ticket the
 
 ## A new ticket takes the team key
 
-`create-ticket.mjs --team <key>` names the team by the prefix its identifiers carry; the CLI resolves the team id from the contract and the cloud fences the write to your tenant on the team, not only on the credential. A ticket's body goes in `--description`, or on stdin with `--stdin` when it runs to several lines; a title with no body gives whoever picks the ticket up nothing to act on. Cite the identifier only after the script prints it; a guessed number is usually a real, unrelated ticket. Do not file a question for a human this way: a ticket whose text reads as a decision request is held out of dispatch by shape until someone releases it, and it would never reach the human's inbox with what it blocks.
+`create-ticket.mjs --team <key>` takes the identifier prefix; the CLI resolves the team from the contract. Give it a body (`--description`, or `--stdin` for several lines), since a bare title leaves nothing to act on. Cite the identifier only after the script prints it; a guessed number is usually a real, unrelated ticket. A question for a human filed this way is held out of dispatch by shape and never reaches their inbox; raise it through `what-needs-me`.
 
 ## What is never offered
 
-Delegation (assigning a ticket to an agent) is an operator action, not a tenant write. Answering an ask on the human's behalf is not a write you make; the human answers, and `what-needs-me` records the acceptance. Editing another actor's comment is not available.
+Delegating a ticket to an agent is an operator action. The human answers their own asks (`what-needs-me` records the acceptance). Another actor's comment cannot be edited.

package/skills/catalyst-linear/scripts/comment.mjs

@@ -7,7 +7,7 @@ import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wants
 
 const HELP = `Usage: node scripts/comment.mjs <ticket> (--body <text> | --stdin) [--parent <commentId>] [--bookkeeping] [--as-user] [--json]
 
-Posts one comment on a ticket. Wraps: catalyst-skills write comment. Spends one unit of the tenant's
+Posts one comment on a ticket. Wraps: catalyst write comment. Spends one unit of the tenant's
 daily write budget.
 
   <ticket>               the Linear identifier, e.g. KEY-123

package/skills/catalyst-linear/scripts/create-ticket.mjs

@@ -7,7 +7,7 @@ import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wants
 
 const HELP = `Usage: node scripts/create-ticket.mjs --team <key> --title <text> [--description <text> | --stdin] [--label <name|id>]... [--priority <0-4>] [--as-user] [--json]
 
-Creates one ticket. Wraps: catalyst-skills write create. Spends one unit of the daily write budget.
+Creates one ticket. Wraps: catalyst write create. Spends one unit of the daily write budget.
 
   --team <key>          the team key (the prefix of its ticket identifiers)
   --title <text>        the ticket title

package/skills/catalyst-linear/scripts/label.mjs

@@ -5,7 +5,7 @@ import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wants
 
 const HELP = `Usage: node scripts/label.mjs <ticket> [--add <name|id>]... [--remove <name|id>]... [--json]
 
-Adds and/or removes labels. Wraps: catalyst-skills write label. One write-budget unit per call
+Adds and/or removes labels. Wraps: catalyst write label. One write-budget unit per call
 direction (add, remove), whatever the label count.
 
   <ticket>              the Linear identifier, e.g. KEY-123

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: it spawns the catalyst-skills CLI
+// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: it spawns the catalyst CLI
 // this machine connected with (the path recorded in customer.json, else npx) and hands back its
 // output. Scripts import it; a person runs it with --help to see what it does. No dependencies.
 import { spawnSync } from "node:child_process";
@@ -8,7 +8,9 @@ import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 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 CONNECT_HINT = CONNECT_COMMAND;
 
 /** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME (used by tests) over HOME. */
@@ -39,8 +41,8 @@ export function notConfigured(reason) {
 }
 
 /**
- * Run one catalyst-skills verb. Returns { code, stdout, stderr }. The CLI is `node <cliPath>` when
- * the config recorded one that still exists, else `npx @catalyst-cloud/catalyst-skills`.
+ * Run one catalyst verb. Returns { code, stdout, stderr }. The CLI is `node <cliPath>` when
+ * the config recorded one that still exists, else `npx -p @catalyst-cloud/cli catalyst`.
  * Exits 2 (not configured) before spawning anything when the config is absent or unreadable.
  */
 export function runCli(args, { stdin } = {}) {
@@ -55,7 +57,7 @@ export function runCli(args, { stdin } = {}) {
     argv = [cfg.cliPath, ...args];
   } else {
     cmd = process.platform === "win32" ? "npx.cmd" : "npx";
-    argv = [PACKAGE, ...args];
+    argv = [...NPX_ARGS, ...args];
     shell = process.platform === "win32";
   }
   const r = spawnSync(cmd, argv, {
@@ -152,8 +154,8 @@ if (runDirectly) {
       [
         "lib/cli.mjs — shared helper for this skill's scripts (not a command of its own)",
         "",
-        "Reads ~/.config/catalyst-cloud/customer.json and runs the catalyst-skills CLI recorded there",
-        `(or npx ${PACKAGE} when no path is recorded). Exit 2 when the machine is not connected.`,
+        "Reads ~/.config/catalyst-cloud/customer.json and runs the catalyst CLI recorded there",
+        `(or npx -p ${PACKAGE} catalyst when no path is recorded). Exit 2 when the machine is not connected.`,
         "",
         `Connect first with: ${CONNECT_HINT}`,
         `Config in use: ${configPath()}`,

package/skills/catalyst-linear/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-linear/scripts/move.mjs

@@ -5,7 +5,7 @@ import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wants
 
 const HELP = `Usage: node scripts/move.mjs <ticket> (--slot <slot> | --state-type <type>) [--json]
 
-Moves a ticket's card. Wraps: catalyst-skills write state. Spends one unit of the daily write budget.
+Moves a ticket's card. Wraps: catalyst write state. Spends one unit of the daily write budget.
 
   <ticket>              the Linear identifier, e.g. KEY-123
   --slot <slot>         one of the eleven slots: dispatch, intake, research, plan, implement,

package/skills/catalyst-linear/scripts/read-ticket.mjs

@@ -6,7 +6,7 @@ import { parseFlags, parseJson, relayStderr, runCli, usage, wantsHelp } from "./
 
 const HELP = `Usage: node scripts/read-ticket.mjs <ticket> [--comments] [--source replica|api] [--json]
 
-Reads one ticket record. Wraps: catalyst-skills query issue.
+Reads one ticket record. Wraps: catalyst query issue.
 
   <ticket>               the Linear identifier, e.g. KEY-123
   --comments             also print every comment (id, author, time, body)

package/skills/catalyst-linear/scripts/search.mjs

@@ -6,7 +6,7 @@ import { exitOnFailure, parseFlags, parseJson, relayStderr, runCli, usage, wants
 const HELP = `Usage: node scripts/search.mjs <terms...> [--limit <n>] [--json]
 
 Searches your tenant for tickets, pull requests, projects and initiatives matching the terms.
-Wraps: catalyst-skills query search.
+Wraps: catalyst query search.
 
   <terms>       one or more words; matched against identifiers, titles and names
   --limit <n>   max rows (default 50)