@catalyst-cloud/cli 0.13.0 → 0.13.1

package/skills/run-this-project/scripts/watch-scope.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // watch-scope.mjs — subscribe to the tenant stream filtered to one scope and pass every in-scope
-// frame through, one JSON line each. This is `catalyst-skills watch` with the scope flags checked
+// frame through, one JSON line each. This is `catalyst watch` with the scope flags checked
 // up front; the CLI owns the socket, the cursor file, the replay and the reconnects.
 import { CHECK_FAILED_EXIT, execCli, parseFlags, requireConfigured, wantsHelp } from "./lib/cli.mjs";
 

package/skills/unstick/SKILL.md

@@ -1,32 +1,31 @@
 ---
 name: unstick
 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-skills 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.
-disable-model-invocation: true
-allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
+  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.13.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.1 — written in this repository for customer accounts -->
 
 # Unstick
 
-You get one stuck ticket, or one set of tickets stuck for the same reason, moving again. The cloud parks or holds a ticket when retrying would only repeat a failure: after repeated failures, when the repair-round cap is spent, when a repair changed nothing, when the same validate failure recurred. Each of those is a governor. Once its cause is fixed, the person's own key releases it; nothing here needs an operator.
+You get one stuck ticket, or one set of tickets stuck for the same reason, moving again. The cloud parks or holds a ticket when retrying would only repeat a failure: after repeated failures, when the repair-round cap is spent, when a repair changed nothing, when the same validate failure recurred. Each of those is a governor. Once its cause is fixed, the person's own key releases most of them. Two refuse that release: a round-threshold hold (a push the fleet did not make, or an answer to its ask, grants one more cycle) and a review that will not converge (a human comment on the ticket resumes it).
 
 ## Run first
 
-Scripts are run, never read. Each prints `--help`; exit 2 means this machine is not connected (run `catalyst-skills login`).
+Scripts are run, never read. Each prints `--help`; exit 2 means this machine is not connected (run `catalyst login`).
 
-- `node scripts/unstick.mjs <ticket>` — one JSON document: the eligibility explanation, the execution history (every governor holding the ticket with what releases it, and past releases), and a dry-run release showing what a release would clear and refuse. Changes nothing.
-- `node scripts/unstick.mjs <ticket> --because "<what changed>"` — the same, then the real release. Add `--retry-unchanged` only when you can say what changed outside what the cloud can see.
-- `node scripts/unstick.mjs --class <failure-class> --team <key> [--because "<what changed>"]` — the same for every ticket on one team parked under one failure class (at most 25 per call).
+- `node scripts/unstick.mjs <ticket>`: one JSON document: the eligibility explanation, the execution history (every governor holding the ticket with what releases it, and past releases), and a dry-run release showing what a release would clear and refuse. Changes nothing.
+- `node scripts/unstick.mjs <ticket> --because "<what changed>"`: the same, then the real release. Add `--retry-unchanged` only when you can say what changed outside what the cloud can see.
+- `node scripts/unstick.mjs --class <failure-class> --team <key> [--because "<what changed>"]`: the same for every ticket on one team parked under one failure class (at most 25 per call).
 
-The verbs underneath are `catalyst-skills explain <ticket>`, `catalyst-skills explain <ticket> --history` and `catalyst-skills release <ticket> --because <text> [--retry-unchanged] [--dry-run]`.
+The verbs underneath are `catalyst explain <ticket>`, `catalyst explain <ticket> --history` and `catalyst release <ticket> --because <text> [--retry-unchanged] [--dry-run]`.
 
 ## Load on demand
 
 | when | read |
 | -- | -- |
 | deciding whether to release, what a refusal means, when to ask a person | `references/playbook.md` |
-| what a reason in the explanation means | the `whats-happening` skill's why-is-it-stuck reference, or `how-catalyst-works` |
+| what a reason in the explanation means, or what clears each kind of hold | the `whats-happening` skill: its why-is-it-stuck and when-a-phase-fails references |
 | a refusal needs a decision or a person's action | the `what-needs-me` skill |
 | a refusal names a person's pull request or its review | the `catalyst-github` skill |
 
@@ -38,4 +37,5 @@ The verbs underneath are `catalyst-skills explain <ticket>`, `catalyst-skills ex
 - **One release per cause.** If the history shows a release for the same failure and nothing has changed since, a second release buys the same failure. Raise an ask instead.
 - **A refusal names its fix.** Do the fix when it is yours to do; everything else is one ask through `what-needs-me`, attached to an existing ask for the same decision. Never close or merge a person's pull request, and never answer an ask as the person.
 - **A shared cause is one note.** Several tickets parked by one outage or one bad image are one class release and one line in your reply, never one ask per ticket.
-- **Their tenant, as them.** Every read and write goes through the CLI and the person's own login. You never name another tenant.
+- **What a release costs.** A release is a write: it is recorded against the person's name with your `--because`, shown to everyone who reads the ticket's history, and it spends a round of work the cloud will run again. The dry run is free; run it first.
+- **Their account, as them.** Every read and write goes through the CLI and the person's own login. You never name another account.

package/skills/unstick/agents/openai.yaml

@@ -3,4 +3,4 @@ interface:
   short_description: "Find out why a Catalyst ticket is parked or held and release it once its cause is fixed; asks only for what needs a person"
   default_prompt: "Use $unstick to find out why <ticket> is stuck and get it moving again."
 policy:
-  allow_implicit_invocation: false
+  allow_implicit_invocation: true

package/skills/unstick/agents/portability.yaml

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

package/skills/unstick/references/playbook.md

@@ -1,18 +1,18 @@
 # The unstick playbook
 
-This reference restates how a person's release of a stuck ticket works and the order you follow. The cloud does the deciding: it reads every governor holding the ticket and either releases all of them or releases nothing and names, for each one it refuses, the action that does fix it. Your job is to read, judge whether the cause is fixed, and say so honestly.
+The cloud does the deciding: it reads every governor holding the ticket and either releases all of them or releases nothing and names, for each one it refuses, the action that does fix it. Your job is to read, judge whether the cause is fixed, and say so honestly.
 
 ## The order
 
-1. **Why is nothing running?** `catalyst-skills explain <ticket>`. If the reason is not a park or a hold (for example `blocked`, `not_at_dispatch_stage`, an ask, a missing environment check, `scope_overlap`), there is nothing to release: follow the `whats-happening` skill's why-is-it-stuck reference instead and stop here.
-2. **What holds it, and has it been released before?** `catalyst-skills explain <ticket> --history`. Read three things: the "Held by" lines (each governor and what releases it), the last failure (its class and summary), and the "Releases" lines (who released it before, why, and what happened).
+1. **Why is nothing running?** `catalyst explain <ticket>`. If the reason is not a park or a hold (for example `blocked`, `not_at_dispatch_stage`, an ask, a missing environment check, `scope_overlap`), there is nothing to release: follow the `whats-happening` skill's why-is-it-stuck reference instead and stop here.
+2. **What holds it, and has it been released before?** `catalyst explain <ticket> --history`. Read three things: the "Held by" lines (each governor and what releases it), the last failure (its class and summary), and the "Releases" lines (who released it before, why, and what happened).
 3. **Is the cause fixed?** Decide from evidence, in this order:
-   - a push to the ticket's branch, a comment on the ticket that says what to change, or main moving on since the park: the cloud can see these, and a release goes through;
-   - a change the cloud cannot see (a provider outage that ended, a rotated secret, a re-enrolled coding account, a fixed tenant setting): release with `--retry-unchanged`, and the reason you give names that change;
+   - a push to the ticket's branch, a comment on the ticket that says what to change, or main moving on since the park: the cloud can see these, and a release goes through. A validate-budget hold needs exactly this (a push or a comment since the hold), or `--retry-unchanged` with the change named;
+   - a change the cloud cannot see (a provider outage that ended, a rotated secret, a re-enrolled coding account, a fixed account setting): release with `--retry-unchanged`, and the reason you give names that change;
    - nothing changed: do not release. Tell the person what failed and what would have to change.
    If a previous release in the history named the same failure and nothing has changed since, the next release will fail the same way. Do not release again; raise an ask.
-4. **Preview.** `catalyst-skills release <ticket> --dry-run`. It prints what a release would clear and what it would refuse, and changes nothing.
-5. **Release.** `catalyst-skills release <ticket> --because "<the change>"`. Report what it released, verbatim, with the ticket id. A warning line (for example, that a released repair round runs again at the escalated tier and a second cap parks it again) goes in your reply too.
+4. **Preview.** `catalyst release <ticket> --dry-run`. It prints what a release would clear and what it would refuse, and changes nothing.
+5. **Release.** `catalyst release <ticket> --because "<the change>"`. Report what it released, verbatim, with the ticket id. A warning line (for example, that a released repair round runs again at the escalated tier and a second cap parks it again) goes in your reply too.
 6. **Act on each refusal.** A refusal is terminal for that attempt: nothing was released. Each names its fix; the table below says who does it.
 
 ## What a refusal means and who fixes it
@@ -23,10 +23,10 @@ This reference restates how a person's release of a stuck ticket works and the o
 | `lease_held` | a phase is running on the ticket right now | nobody; wait for the phase's outcome comment, then look again |
 | `branch_still_missing` | the ticket's branch was never pushed | it releases itself when the branch appears; check the earlier phases through `catalyst-linear` |
 | `human_owned_pr` | a person opened the pull request this ticket would work on | that person closes or merges it, or hands it to Catalyst; never close a person's pull request yourself |
-| `review_not_converging` | review and repair kept finding new problems | a person reads the findings (`catalyst-github`) and comments on the ticket to resume; raise an ask for that read |
-| `round_threshold` | the ticket spent its lifetime repair budget | a person answers the ask the cloud already raised, or pushes a fix; point at that ask, do not raise a second one |
-| `base_revision_lost` | the ticket's base commit is gone | whoever administers the tenant re-pins it; raise one ask |
-| `remediate_cap` | this tenant keeps the repair-round cap for an administrator | whoever administers the tenant; raise one ask |
+| `review_not_converging` | validate and repair cycles kept finding new problems | a person reads the findings (`catalyst-github`) and comments on the ticket: the comment resumes at validate, and `catalyst: resume implement` resumes at implement. A push alone does not clear it, and it has no ask and no default. Raise an ask for that read |
+| `round_threshold` | the ticket spent its lifetime repair budget | a person answers the ask the cloud already raised, or pushes a fix the fleet did not make; each grants one more cycle, and a comment does not. After 48 hours unanswered, the ask's default (re-plan) applies. Point at that ask; do not raise a second one |
+| `base_revision_lost` | the ticket's base commit is gone | an operator re-pins it; raise one ask |
+| `remediate_cap` | this account keeps the repair-round cap for an administrator | a workspace owner or admin; raise one ask |
 | `unknown_park` | a park this bundle does not know | raise one ask with the ticket id and the park name, verbatim |
 | `held_beyond_class` | a class release reached a ticket held by more than that class | release that ticket on its own, from step 1 |
 | `team_changed` (the ticket moved teams during the check) | the release was checked for one team and the ticket is now on another | run the release again |
@@ -37,8 +37,8 @@ Raise an ask only through `what-needs-me`, with the stuck ticket in what it bloc
 
 When several tickets on one team are parked for the same failure class (the explanation and the history show the same class, typically an outage or a runner problem that has since ended):
 
-1. `catalyst-skills release --class <failure-class> --team <key> --dry-run` to see which tickets it reaches.
-2. `catalyst-skills release --class <failure-class> --team <key> --because "<the change>" --retry-unchanged` when the change is one the cloud cannot see.
+1. `catalyst release --class <failure-class> --team <key> --dry-run` to see which tickets it reaches.
+2. `catalyst release --class <failure-class> --team <key> --because "<the change>" --retry-unchanged` when the change is one the cloud cannot see.
 3. Report one line: how many released, which were refused and why, and whether more remain (run it again for the next batch).
 
 A ticket the class release refuses is listed and left alone; take it through the single-ticket order above.

package/skills/unstick/scripts/lib/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: spawn the catalyst-skills CLI.
+// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: spawn the catalyst CLI.
 // The CLI holds the SDK and the key; this file holds neither. It reads customer.json only
 // to learn where the CLI lives, and it exits 2 with one line when the machine is not connected.
 // Run any script beside this one with --help; this file is a library and is never run directly.
@@ -8,7 +8,9 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
-export const PACKAGE = "@catalyst-cloud/catalyst-skills";
+export const PACKAGE = "@catalyst-cloud/cli";
+/** The package ships two commands, so npx needs the one to run named: `npx -p <package> catalyst`. */
+export const NPX_ARGS = ["-p", PACKAGE, "catalyst"];
 export const NOT_CONFIGURED_EXIT = 2;
 
 export function configPath() {
@@ -36,7 +38,7 @@ function notConfigured(why) {
 }
 
 /**
- * Run one catalyst-skills verb and return {code, stdout, stderr}. Uses the CLI path the login
+ * Run one catalyst verb and return {code, stdout, stderr}. Uses the CLI path the login
  * recorded when it still exists, else `npx <package>`. A CLI exit of 2 with a "not joined" or
  * "not connected" line is turned into this script's own exit 2, so every caller sees one contract.
  */
@@ -44,7 +46,7 @@ export function runCli(args, opts = {}) {
   const cfg = loadConfig();
   const useRecorded = typeof cfg.cliPath === "string" && existsSync(cfg.cliPath);
   const cmd = useRecorded ? process.execPath : "npx";
-  const argv = useRecorded ? [cfg.cliPath, ...args] : [PACKAGE, ...args];
+  const argv = useRecorded ? [cfg.cliPath, ...args] : [...NPX_ARGS, ...args];
   const res = spawnSync(cmd, argv, {
     input: opts.stdin,
     encoding: "utf8",

package/skills/unstick/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/unstick/scripts/unstick.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // unstick.mjs — "why is this stuck, and can it be released?" in one JSON document. Runs
-// `catalyst-skills explain`, `explain --history` and a dry-run `release` for one ticket (or a dry-run
+// `catalyst explain`, `explain --history` and a dry-run `release` for one ticket (or a dry-run
 // class release for one team), and only with --because runs the real release. Reaches the cloud only
 // by spawning the CLI.
 import { mustRun, parseFlags, parseJson, printHelp, runCli } from "./lib/cli.mjs";

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

@@ -1,23 +1,22 @@
 ---
 name: what-needs-me
 description: >-
-  The human's decision inbox on a Catalyst Cloud tenant, 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 what each answer releases, files an ask through the cloud's ask route with the tenant's own template, and records the answer so the held work releases. Never answers as the human, never duplicates an open ask.
-disable-model-invocation: true
-allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
+  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.13.0 — written in this repository for customer tenants -->
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.13.1 — written in this repository for customer accounts -->
 
 # What needs me
 
-An ask is one decision only the human can make, filed as a ticket in their own Linear so that question, options, default, answer and who answered are one record. This skill reads that inbox ranked by blast radius, raises a new ask when work is gated, and settles the answer so the held work releases. The cloud renders the ask body from the tenant's template, applies the ask labels and creates the blocking relations; you pass fields, never headings.
+An ask is one decision only the human can make, filed as a ticket in their own Linear so that question, options, default, answer and who answered are one record. This skill reads that inbox ranked by how much open work each ask holds, raises a new ask when work is gated, and settles the answer so the held work releases. The cloud renders the ask body from the account's template, applies the ask labels and creates the blocking relations; you pass fields, never headings.
 
 ## Run first
 
-Scripts are run, never read. Each prints `--help`; exit 2 means this machine is not connected (run the `connect-me` skill), exit 1 means the check itself failed or an argument was missing.
+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, ranked by the priority-weighted work each holds; `--anyone` for the whole tenant; `--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/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.
+- `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/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
 
@@ -33,9 +32,8 @@ The `catalyst-linear` skill posts the comment that carries an answer given in ch
 
 - **File before proceeding on the default.** Work may run on a default only after the ask exists; a default with no ticket behind it is a guess, not a decision.
 - **One ask per decision.** Read the inbox first; attach new held tickets to an open ask rather than filing a twin. Duplicates split one decision's urgency across rows.
-- **Every ask names what it blocks.** The ranking the human sees is by held work weighted by priority, never by age; an ask that holds nothing does not reach Waiting on me unless you chose `--nothing-to-block` on purpose.
-- **Never answer as the human.** You do not pick an option, close an ask on their behalf, or post in their voice. Their answer is quoted into the ask as the app actor and recorded with its comment id.
-- **A free-text reply is recorded, never interpreted into an option.** If it does not answer the question, ask the one clarification in the thread and leave the ask open.
+- **Every ask names what it blocks.** The ranking the human sees is by the count of open tickets each ask holds, then the oldest ask; priority is not a weight. An ask that holds nothing does not reach Waiting on me unless you chose `--nothing-to-block` on purpose.
+- **A write is visible.** Filing an ask puts a ticket in the person's Linear, assigns it to them, holds every ticket it names, and spends the daily write budget; settling posts a comment on the ask and on every held ticket. Read the inbox before you file.
+- **The human answers for themselves.** Their answer is quoted into the ask as the app actor and recorded with its comment id; a free-text reply is recorded as written, never turned into an option.
 - **Escalate inward.** A project owner raises asks for its scope; the desk raises what has no owner; a single stuck ticket or a provider outage is never an ask.
-- **Tenant facts come from the contract.** Team keys, label names, the option cap and the template are read live by the CLI; never restate them.
-- **Cite an identifier only after the create call returned it.**
+- **Account facts come from the contract.** Team keys, label names, the option cap and the template are read live by the CLI. Cite an identifier only after the create call returned it.

package/skills/what-needs-me/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "What needs me"
-  short_description: "Your decision inbox on Catalyst Cloud, ranked by what each answer releases; raises and settles asks"
+  short_description: "Your decision inbox on Catalyst Cloud, ranked by how much open work each ask holds; raises and settles asks"
   default_prompt: "Use $what-needs-me to show me what is waiting on my decision."
 policy:
-  allow_implicit_invocation: false
+  allow_implicit_invocation: true

package/skills/what-needs-me/agents/portability.yaml

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

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

@@ -1,41 +1,33 @@
 # Raising a decision
 
-This reference restates invariants: what an ask is, when it is filed, and what it must carry. The body text, the headings, the option format and the cap on options are tenant facts served by the contract's `askTemplate` block and rendered by the cloud itself; `node scripts/raise.mjs` passes fields and never composes a heading.
-
-## What an ask is
-
-An ask is one decision only the human can make, filed as a ticket in the tenant's own Linear so that the question, the options, the default, the answer and who answered are one record the next agent can read. The cloud labels it as an ask, excludes it from dispatch (a question is never work), and holds every ticket it blocks until it is answered. It appears in the human's Waiting-on-me view when it is assigned to them and blocks open work.
+The body, headings, option format and option cap come from the contract's `askTemplate` and are rendered by the cloud; `node scripts/raise.mjs` passes fields. The cloud labels the ask, keeps it out of dispatch, and holds every ticket it blocks until it is answered.
 
 ## 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 physically take (a click in settings, a credential, a payment). File it **before** proceeding on the default, never after, and never only as a TODO line, a board row, a handoff note or a chat question. Those may point at the ask's identifier; they 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 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.
 
-Do not file one for brainstorming, a design back-and-forth, a question the human asked first, a retry-or-abandon call a project owner can make, or a system-level failure (a provider down, out of capacity, rate-limited: that is one status line, and the affected tickets retry on their own).
+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.
 
 ## What it carries
 
 1. **The question**, one sentence, as the title (`--title`).
 2. **Context** the human needs to answer without opening anything else (`--context`), short.
 3. **Options**, each one line, realistic, at most the number the contract allows (`--option`, repeated). The cloud letters and formats them.
-4. **The default if silent** (`--default`): what proceeds and after how long. It must be sane enough to actually run. Note that nothing in the cloud applies the default on a timer; the raising agent applies it, after the ask exists, and records that it did.
-5. **What it blocks** (`--blocks`, repeated): every ticket held until the answer lands. The cloud creates the blocking relations atomically with the ticket. An ask that holds nothing is refused unless you say `--nothing-to-block` on purpose, because an ask with no blocking relation never surfaces in Waiting on me and is indistinguishable from ordinary work.
+4. **The default if silent** (`--default`): what proceeds and after how long. It must be sane enough to actually run. The raising agent applies it, after the ask exists, and records that it did; the cloud applies no default on a timer for the asks you raise. The exception is the ask a validate-budget or round-threshold hold raises: the cloud applies its default (re-plan) after 48 hours unanswered.
+5. **What it blocks** (`--blocks`, repeated): every ticket held until the answer lands, related atomically with the ask. An ask that holds nothing is refused unless you pass `--nothing-to-block` on purpose, because it never surfaces in Waiting on me. Name every held ticket: the inbox ranks by that count (`references/reading-the-inbox.md`), so an ask that names one ticket when it really holds a project sinks below one holding two chores.
 
 `--ask-key` is an idempotency key: a re-run with the same key does not file a second ask.
 
 ## One ask per decision
 
-Run `node scripts/inbox.mjs` first and read the titles. When the same decision is already open, attach the new held tickets to it rather than filing again (the `catalyst-linear` skill adds the relation or a comment naming them). Duplicates split one decision's urgency across several rows and sink it below trivia in the ranking.
+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.
 
 ## Who raises, and where
 
 - A decision inside a project scope is raised by that project's owner; the desk raises what has no owner.
-- The ask is filed on the team the held work belongs to (`--team`), from the contract's team list. An approvals team, when the contract names one, is where an approval with no natural team goes.
-- Never raise an ask on someone else's behalf about their own scope, and never answer one for the human.
+- The ask goes on the held work's team (`--team`); an approval with no natural team goes to the approvals team when the contract names one.
+- Each scope's owner raises its own asks, and the human answers them.
 
 ## After filing
 
 Cite the identifier the script printed, and only that. Proceed on the default if the work allows it, and say so in the ask's thread (a bookkeeping comment) so the record shows the default was taken. When the answer arrives, `references/settling-an-answer.md`.
-
-## Ranking
-
-The human sees asks ranked by how much open work each holds, weighted by that work's priority (urgent counts most), never by age. That is why `--blocks` must be complete: an ask that names one held ticket when it really holds a project sinks below a chore.

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

@@ -1,10 +1,8 @@
 # Reading the inbox
 
-This reference restates invariants: what "waiting on me" means, how declared and inferred asks differ, and how to present the queue. The label that marks an ask, its prefix, and the release label are the contract's `vocabulary`; `node scripts/inbox.mjs` reads them from the CLI and never from prose.
-
 ## What waiting-on-me means
 
-The tenant's own Waiting-on-me view lists a ticket for a person when all four hold:
+The account's own Waiting-on-me view lists a ticket for a person when all four hold:
 
 1. it is **assigned** to that person;
 2. it has **no delegate** (a ticket delegated to an agent is the agent's, not the human's);
@@ -17,16 +15,15 @@ So an ask that holds nothing is real, but the person may never see it in their o
 
 ## What the script reads
 
-`catalyst-skills ask list` reads every page of the tenant's issues, not a windowed sample, so an empty list means nothing is assigned to you rather than that the read stopped early. It reads the open tickets carrying the team's ask label (by the label ids and prefix the contract serves), follows each one's blocking relations to the tickets it holds, drops held tickets that are already terminal, and scores the rest by priority weight: urgent 4, high 3, medium 2, low 1, none 1. It filters to **the connected person** by default: `login` recorded who they are and their Linear user id, and the list keeps only asks assigned to that id. `--anyone` lists the whole tenant. The JSON answer carries a `scope` — `mine` (with the label and Linear id), `anyone`, `unmatched` (the person's Linear identity is not matched yet: an admin does that in Settings → Members, and until then the whole list is shown with a stderr line saying so), or `no-person` (the machine is connected with the tenant's account key, which names nobody: the whole list, with a line saying to log in with a personal key). Read the scope before presenting the list, and say which you got: "what needs me" is the `mine` list, "what needs anyone" is `--anyone`, and an empty `mine` list names the wider count so it never reads as "nothing needs anyone".
+`catalyst ask list` reads every page, so an empty list is real. It follows each open ask's blocking relations, drops held tickets already terminal, and ranks by the count of open tickets each ask holds (its `score`), then the oldest ask, then the identifier: the cloud's own Waiting-on-me order. Priority is not a weight; age only breaks a tie. It keeps the connected person's asks by default (`--anyone` for everyone's) and reports a `scope`: `mine`, `anyone`, `unmatched` (the Linear identity is not matched, so everyone's list is shown with a stderr line), or `no-person` (connected with the account key, which names nobody). Say which scope you got, and give the wider count beside an empty `mine` list so it never reads as "nothing needs anyone".
 
 ## The identity is not the same as the personal Linear grant
 
-Two different stored facts can disagree, and when asks are not reaching someone this is the first thing to check, before the grant. The **identity** is who you are in Linear: resolved automatically by an email match, or picked by an admin at Settings → Members when it is not. The **personal Linear grant** is proven by connecting Linear yourself — a person action, not an admin one. Connecting Linear personally does **not** set the identity; the two are separate, and the identity is checked first, then the grant. An identity that resolved automatically cannot be re-pointed by the member themselves — that needs an operator; a manual pick by an admin is refused if another member already claims that Linear user. Everything that notifies or assigns a human needs a resolved identity: with no identity there is no ask and no push, and nothing is assigned to that person — even for someone who has connected Linear themselves. Do not report that as an empty queue. `what needs me` does not go quiet in that state: the scope comes back `unmatched`, the whole tenant's open asks are listed, and a line says the identity is not matched yet (*What the script reads*, above). The honest answer is "nothing is assigned to you yet, so this is everyone's list, not yours — an admin matches your identity at Settings → Members".
+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".
 
 ## Presenting the queue
 
-- Ranked by score, highest first. Never by age, never by identifier. An ask that holds a project outranks one that holds a chore, whatever their dates.
-- One line per ask: rank, identifier, what it holds (identifiers), the question. The human decides from the question and the held work, so both must be on the line.
+- In the script's order, one line per ask: rank, identifier, what it holds (identifiers), the question.
 - Asks that hold nothing come after a break, marked as not visible in Waiting on me until they block something.
 - When the list is empty, say "nothing needs you" and stop. Do not pad it with suspected asks.
 - A ticket `explain` flagged as `ask_shape_suspected` (its text reads as a decision but it carries no ask label) is mentioned separately with a question mark: it is either an ask the human should label, or a false positive they release with the release label the contract names.
@@ -34,9 +31,5 @@ Two different stored facts can disagree, and when asks are not reaching someone
 ## What the inbox is not
 
 - It is not the dispatch queue. Held tickets are excluded from dispatch by their blocking relation; answering the ask releases them into the ordinary order.
-- It is not a place to answer. Nothing in this skill picks an option, closes an ask on the human's behalf, or posts in their voice. When they answer in chat, `references/settling-an-answer.md`.
-- It is not a stall detector. A ticket parked by repeated failures, a merge hold, or a coding-account wall is a status question for `whats-happening`, not a decision until someone makes it one by raising an ask.
-
-## Free-text and interpreted replies
-
-A human reply that names no option is recorded by the cloud and interpreted for display, but never auto-applied and never written back to Linear as a decision. Treat it the same way: read it, ask the human to confirm which option it means if that is unclear, and settle only once a comment on the ask states the answer.
+- It is not a place to answer; an answer goes through `references/settling-an-answer.md`.
+- It is not a stall detector. A park, a merge hold or a coding-account wall is a status question for `whats-happening` until someone raises an ask.

package/skills/what-needs-me/references/settling-an-answer.md

@@ -1,24 +1,20 @@
 # Settling an answer
 
-This reference restates invariants: where an answer is posted, how it is recorded, and how held work is released. The routes and the bookkeeping marker are the contract's; `node scripts/settle.mjs` reads them through the CLI.
-
-## The rule
-
-The answer lives on the ask. Wherever it arrived (a comment on the ask, a comment on a held ticket, a chat message, a call), it ends as a comment on the ask ticket, and that comment is recorded as the accepted answer. Question, options, default, answer and who answered are then one record.
+The answer lives on the ask. Wherever it arrived (the ask's thread, a held ticket, chat, a call), it ends as a comment on the ask, recorded as the accepted answer, so question, options, default, answer and who answered are one record.
 
 ## The three steps
 
-**1. Post the answer where it should live.** If the human answered in the ask's thread, nothing to do. If they answered anywhere else, post a comment on the ask that states the answer, as the app actor, never as the human, and attribute it in the text ("the owner answered in chat: option B"). Use the `catalyst-linear` skill's comment script; it returns the comment id. Do not paraphrase into a different option; quote what they said.
+**1. Post the answer where it should live.** An answer given anywhere but the ask's thread becomes a comment on the ask, as the app actor, quoting them and attributing it ("the owner answered in chat: option B"), through the `catalyst-linear` skill's comment script, which returns the comment id.
 
 **2. Record it.** `node scripts/settle.mjs <ask> --answer <commentId> --role <role>` calls the cloud's ask-accept with the ask, the answering comment and the role doing the recording. The script first checks the comment is really on the ask (an id from a different ticket is refused before anything is written), then records, then reads the ask's blocking relations.
 
-**3. Release the held work.** For every open ticket the ask blocks, the script posts one bookkeeping comment naming the ask, the comment id and the first line of the answer, so the next phase or agent on that ticket reads the decision without opening the ask. The comment carries the contract's bookkeeping prefix, which means the cloud's comment-wake trigger ignores it: a record, not a turn in a conversation. Pass `--no-release-note` to skip this when the held tickets are about to be canceled anyway.
+**3. Release the held work.** On every open ticket the ask blocks, the script posts one bookkeeping comment naming the ask, the comment id and the answer's first line, so the next agent there reads the decision; the marker keeps it from waking anyone. `--no-release-note` skips this for tickets about to be canceled.
 
 With `--close`, the script also moves the ask to its team's done slot. The blocking relations stay on the record; a done ticket does not block anything, so the held tickets become dispatchable on the cloud's next pass. Close only when the answer is complete; an answer that raises a follow-up question keeps the ask open and the follow-up goes in the same thread.
 
 ## Free-text replies
 
-A reply that names no option ("do whichever is cheaper", "ask me again Thursday") is recorded exactly as written. Nothing in the cloud or in this skill turns it into an option. Read it, decide whether it answers the question, and if it does not, reply in the thread with the one clarification needed and leave the ask open. If it does, settle with that comment as the answer and let the release note carry the quoted line.
+A reply that names no option ("do whichever is cheaper", "ask me again Thursday") is recorded exactly as written; nothing turns it into an option. If it answers the question, settle with it and let the release note quote it. If it does not, reply in the thread with the one clarification needed and leave the ask open.
 
 ## Who settles
 
@@ -26,12 +22,10 @@ The role that raised the ask, or the owner of the scope it belongs to. The desk
 
 ## After settling
 
-- Tell the human, in one line, what was recorded and what it released.
-- The held tickets need no further action from you: their exclusion reason was the blocking relation, and the queue recomputes on the cloud's next pass. If one stays excluded, `whats-happening` explains why.
-- If the answer changes priorities or scope, that is a routing change for the project owner, not a second ask.
+Tell the human in one line what was recorded and what it released. The held tickets rejoin the queue on the cloud's next pass; if one stays excluded, `whats-happening` explains why. An answer that changes priorities or scope is a routing change for the project owner, not a second ask.
 
 ## When it cannot be settled
 
 - The comment id is not on the ask: post the answer on the ask first, then settle with the new id.
 - The write budget for the day is spent: the CLI names the budget from the contract and exits 2. Say so; the record waits, the human's answer is not lost.
-- The ask is on a team the contract does not list: the tenant admin maps the team in settings; the `catalyst-setup` skill reads readiness.
+- The ask is on a team the contract does not list: a workspace owner or admin maps the team (`catalyst team map <KEY>`); the `catalyst-onboard` skill reads readiness.

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

@@ -1,23 +1,24 @@
 #!/usr/bin/env node
-// inbox.mjs — "what needs me?": the open asks on this tenant, ranked by what each answer releases.
-// A thin wrapper over `catalyst-skills ask list`, which reads the open tickets carrying the team's
-// ask label (from the contract), follows each one's blocking relations, and weights held work by
-// priority. By default the CLI keeps only the asks assigned to the connected person; --anyone widens
-// to the whole tenant. Prints the ranked list; --json prints the CLI's {scope, asks} unchanged.
+// inbox.mjs — "what needs me?": the open asks in this cloud account, ranked by what each answer releases.
+// A thin wrapper over `catalyst ask list`, which reads the open tickets carrying the team's
+// ask label (from the contract), follows each one's blocking relations, and ranks by the count of
+// open tickets held, then the oldest ask. By default the CLI keeps only the asks assigned to the
+// connected person; --anyone widens to the whole account. Prints the ranked list; --json prints the
+// CLI's {scope, asks} unchanged.
 import { mustRun, parseFlags, parseJson, printHelp } from "./lib/cli.mjs";
 
 const SPEC = {
   json: { value: false, help: "print the CLI's answer as JSON: {scope, asks: [{identifier, title, state, blocks[], score, assigneeId}]}" },
   team: { value: true, help: "only asks whose identifier carries this team key" },
   all: { value: false, help: "include asks that hold nothing (by default they are listed last, marked)" },
-  anyone: { value: false, help: "every open ask in the tenant, not only the ones assigned to you" },
+  anyone: { value: false, help: "every open ask in the account, not only the ones assigned to you" },
 };
 
 const { help, flags } = parseFlags(process.argv.slice(2), SPEC);
 if (help) {
   printHelp("node scripts/inbox.mjs [--json] [--team K] [--all] [--anyone] [--help]", SPEC, [
-    "Rank: the sum over held open tickets of a priority weight (urgent 4 ... low 1, none 1), highest first.",
-    "An ask that holds nothing is real but will not appear in the tenant's Waiting-on-me view; it is",
+    "Rank: most open tickets blocked first, then the oldest ask; priority is not a weight.",
+    "An ask that holds nothing is real but will not appear in the Waiting-on-me view; it is",
     "listed last with a marker so you can attach the work it should block (references/reading-the-inbox.md).",
   ]);
   process.exit(0);
@@ -33,11 +34,11 @@ if (flags.json) {
 }
 // Say whose list this is before the list, so an empty "mine" never reads as "nothing needs anyone".
 if (scope.kind === "mine") process.stdout.write(`asks assigned to ${scope.label}:\n`);
-else if (scope.kind === "anyone") process.stdout.write("every open ask in the tenant:\n");
-else if (scope.kind === "unmatched") process.stdout.write(`every open ask (your Linear identity is not matched yet — an admin matches it in Settings → Members):\n`);
-else process.stdout.write("every open ask (connected with the tenant's account key, which names no person — log in with your personal key to see only yours):\n");
+else if (scope.kind === "anyone") process.stdout.write("every open ask in the account:\n");
+else if (scope.kind === "unmatched") process.stdout.write(`every open ask (your Linear identity is not matched yet; match it with: catalyst identity linear set):\n`);
+else process.stdout.write("every open ask (connected with the account key, which names no person — log in with your personal key to see only yours):\n");
 if (wanted.length === 0) {
-  process.stdout.write(scope.kind === "mine" ? "nothing needs you: no open asks assigned to you (--anyone lists the tenant's)\n" : "nothing needs anyone: no open asks\n");
+  process.stdout.write(scope.kind === "mine" ? "nothing needs you: no open asks assigned to you (--anyone lists everyone's)\n" : "nothing needs anyone: no open asks\n");
   process.exit(0);
 }
 const holding = wanted.filter((r) => r.blocks.length > 0);
@@ -45,7 +46,7 @@ const idle = wanted.filter((r) => r.blocks.length === 0);
 let n = 0;
 for (const r of holding) {
   n += 1;
-  process.stdout.write(`${n}. ${r.identifier}  holds ${r.blocks.length} (weight ${r.score}): ${r.blocks.join(", ")}\n   ${r.title}\n`);
+  process.stdout.write(`${n}. ${r.identifier}  holds ${r.blocks.length}: ${r.blocks.join(", ")}\n   ${r.title}\n`);
 }
 if (idle.length && (flags.all || holding.length === 0)) {
   process.stdout.write(`${holding.length ? "\n" : ""}asks that hold nothing (not shown in Waiting on me until they block something):\n`);

package/skills/what-needs-me/scripts/lib/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: spawn the catalyst-skills CLI.
+// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: spawn the catalyst CLI.
 // The CLI holds the SDK and the key; this file holds neither. It reads customer.json only
 // to learn where the CLI lives, and it exits 2 with one line when the machine is not connected.
 // Run any script beside this one with --help; this file is a library and is never run directly.
@@ -8,7 +8,9 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
-export const PACKAGE = "@catalyst-cloud/catalyst-skills";
+export const PACKAGE = "@catalyst-cloud/cli";
+/** The package ships two commands, so npx needs the one to run named: `npx -p <package> catalyst`. */
+export const NPX_ARGS = ["-p", PACKAGE, "catalyst"];
 export const NOT_CONFIGURED_EXIT = 2;
 
 export function configPath() {
@@ -36,7 +38,7 @@ function notConfigured(why) {
 }
 
 /**
- * Run one catalyst-skills verb and return {code, stdout, stderr}. Uses the CLI path the login
+ * Run one catalyst verb and return {code, stdout, stderr}. Uses the CLI path the login
  * recorded when it still exists, else `npx <package>`. A CLI exit of 2 with a "not joined" or
  * "not connected" line is turned into this script's own exit 2, so every caller sees one contract.
  */
@@ -44,7 +46,7 @@ export function runCli(args, opts = {}) {
   const cfg = loadConfig();
   const useRecorded = typeof cfg.cliPath === "string" && existsSync(cfg.cliPath);
   const cmd = useRecorded ? process.execPath : "npx";
-  const argv = useRecorded ? [cfg.cliPath, ...args] : [PACKAGE, ...args];
+  const argv = useRecorded ? [cfg.cliPath, ...args] : [...NPX_ARGS, ...args];
   const res = spawnSync(cmd, argv, {
     input: opts.stdin,
     encoding: "utf8",

package/skills/what-needs-me/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/what-needs-me/scripts/raise.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // raise.mjs — file one decision for the human as an ask ticket, through the cloud's own ask route.
-// Wraps `catalyst-skills ask raise`. You pass fields (question, options, default, what it blocks);
+// Wraps `catalyst ask raise`. You pass fields (question, options, default, what it blocks);
 // the cloud renders the body from the tenant's ask template, applies the ask labels, and creates the
 // blocking relations in one atomic write. Headings are never composed here.
 import { mustRun, parseFlags, parseJson, printHelp } from "./lib/cli.mjs";

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

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // settle.mjs — record the human's answer on an ask and release the work it held.
-// 1. `catalyst-skills ask accept <ask> --answer <commentId> --role <role>` records which comment is
+// 1. `catalyst ask accept <ask> --answer <commentId> --role <role>` records which comment is
 //    the accepted answer, as the app actor.
 // 2. Every open ticket the ask blocks gets one bookkeeping comment naming the ask and the answer,
 //    so the next agent on that ticket reads the decision without opening the ask.