@catalyst-cloud/catalyst-skills 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.3.0
+
+You connect with your own personal key now, not the tenant's shared account key: mint it yourself at Settings → API keys in the Catalyst Cloud app (every member can; no admin needed), and `login` prints who you connected as beside which tenant. Your agent acts as you — an ask it raises names you, and "what needs me" means you: `ask list` (and the what-needs-me skill) keeps only the asks assigned to your Linear user by default, `--anyone` lists the whole tenant, and when your Linear identity is not matched yet it says so and shows everything rather than an empty list. `customer.json` gains a `user` block (id, label, role, your Linear user id); an older config is still read unchanged. Connecting with the account key still works — it is the right credential for a host or daemon — but `login` tells you it names no person. Every skill, reference and help line that said "account key", or said execution history and coding-account status were not readable, has been rewritten: `explain --history` and `accounts` read them, and the two things your key genuinely cannot do (release a park, read PR labels or reactions) are named instead. The catalyst-setup reference now lists all eleven team checks, including `environment_declared`. Needs a cloud that admits personal keys on the agent routes; on an older cloud the contract read says so by name, and the account key still works until it is updated.
+
+## 0.2.1
+
+Fixes five defects found by running 0.2.0's verbs against a live tenant. Three skills (catalyst-github, catalyst-setup, how-catalyst-works) carried a colon-and-space inside an unquoted description, which YAML reads as a nested map rather than text, so `npx skills add` skipped them and still reported success — every Codex, Cursor and OpenCode install of 0.2.0 quietly got five of the eight skills, and reinstalling with this version gives you all eight. `running` no longer asks for lease attributions it has no coordinates for, so the headline "what's happening?" verb works instead of failing for every tenant; the lease read is still available as `running --ticket T --phase P`. The CLI no longer truncates its own output at 64KB when a skill reads it through a pipe, which made `query issues --json` on a tenant past roughly eighty tickets return invalid JSON with a success code. `accounts` now actually reads your coding-account slots and renders them, `history <ticket>` (also `explain --history`) shows a ticket's execution history, and both say plainly when your cloud is older than this bundle rather than printing an empty success. `queue` with no `--team` reads every team on your tenant instead of being refused, as its help always promised. `query changes` works at all now: it reads the feed's NDJSON, where before it called any successful response a non-JSON body — nothing noticed because the documented `--since 0` is refused on any tenant whose feed has rotated, so a success was never reached. That refusal now names a cursor you can actually use, and `--since head` starts from now.
+
 ## 0.2.0
 
 Eight skills named from the executive's seat (whats-happening, what-needs-me, run-this-project, catalyst-setup, catalyst-linear, catalyst-github, how-catalyst-works, connect-me) replace the six; reads and the live event stream go through the Catalyst Cloud SDK and writes through the tenant's agent proxy, all behind catalyst-skills verbs (me, contract, query, replica, explain, running, queue, watch, write, ask, ready, accounts), with every stage id, label id, threshold and route read from the tenant contract; Node 22 is now required; installing the skills has moved to your agent's own command (the Claude Code plugin marketplace in this repository, or npx skills add for Codex, Cursor, OpenCode and the rest) and the CLI no longer copies them, leaving install only as a repair path; catalyst-skills login replaces join, which stays as a deprecated alias for one minor version, and login now prompts for the key without echoing it when no CATALYST_CLOUD_TOKEN is set; every SKILL.md declares allowed-tools scoped to this package's binary, so no skill needs a blanket shell grant; your existing customer.json is still read unchanged and gains the CLI path the next time you run catalyst-skills login, which also caches the tenant contract; run catalyst-skills ready to confirm.

package/README.md

@@ -4,9 +4,25 @@
 
 ## Install
 
-Two ways in. The plugin installs the set as a managed bundle that updates when we ship. `npx skills` copies editable files into your project. Pick one; installing both leaves you with every skill twice.
+Start by pasting one sentence into the coding agent you already use:
 
-<details><summary><strong>Claude Code</strong></summary>
+```
+Help me understand and set up Catalyst Cloud. Read https://staging.catalystcloud.dev/agent-guide.md first, then walk me through it step by step.
+```
+
+Your agent reads the guide, explains Catalyst Cloud in terms of your own repositories and tickets, finds out where it is running and what is already installed, and does the setup below itself — asking once before it writes to your machine. Everything else on this page is the reference it follows.
+
+Or by hand. One command, for every coding agent on the machine:
+
+```sh
+npx skills@latest add coalesce-labs/catalyst-cloud-skills --all
+```
+
+It installs all eight skills for each agent it detects (Claude Code, Codex, Cursor, OpenCode and the rest). Add `-g` to install into your home directory instead of the project. Skills installed this way do not auto-update; run `npx skills update -y` to refresh them.
+
+<details><summary><strong>Alternative for Claude Code: the plugin marketplace</strong></summary>
+
+The plugin installs the set as a managed bundle that updates when we ship. It needs a GitHub SSH key, and it does not load into the session you are already in — run `/reload-plugins` or restart afterwards. Pick one rail; installing both leaves you with every skill twice.
 
 ```
 /plugin marketplace add coalesce-labs/catalyst-cloud-skills
@@ -14,65 +30,59 @@ Two ways in. The plugin installs the set as a managed bundle that updates when w
 ```
 </details>
 
-<details><summary><strong>Codex</strong></summary>
+<details><summary><strong>One agent at a time</strong></summary>
 
-Run this command in your project:
+Codex:
 
 ```sh
 npx skills@latest add coalesce-labs/catalyst-cloud-skills -a codex
 ```
-</details>
 
-<details><summary><strong>Cursor</strong></summary>
-
-Run this command in your project:
+Cursor:
 
 ```sh
 npx skills@latest add coalesce-labs/catalyst-cloud-skills -a cursor
 ```
-</details>
-
-<details><summary><strong>OpenCode, Amp, Windsurf and the rest</strong></summary>
 
-Run this command in your project:
+OpenCode, Amp, Windsurf and the rest:
 
 ```sh
 npx skills@latest add coalesce-labs/catalyst-cloud-skills
 ```
 
-The installer asks which skills to take and which agents to install them on. Add `-g` to install into your home directory instead of the project. Skills installed this way do not auto-update; run `npx skills update -y` to refresh them.
+Without `--all` the installer asks which skills to take and which agents to install them on.
 </details>
 
 ### Then connect to your tenant
 
-The skills call one CLI, and the CLI holds your credential. Install it once and connect this machine with your account key:
+The skills call one CLI, and the CLI holds your credential. Install it once and connect this machine with your own **personal key** — mint it at Settings → API keys in the Catalyst Cloud app (every member can; no admin needed):
 
 ```sh
 npm install -g @catalyst-cloud/catalyst-skills
-CATALYST_CLOUD_TOKEN=<your-account-key> catalyst-skills login
+CATALYST_CLOUD_TOKEN=<your-personal-key> catalyst-skills login
 catalyst-skills ready
 ```
 
-Passing the key as an environment variable is the recommended form, because a key typed into a command line lands in your shell history. With no key in the environment and a terminal attached, `catalyst-skills login` prompts for it without echoing it; `--key <your-account-key>` is the third form, for a script. `npx @catalyst-cloud/catalyst-skills login` works without the global install, and `bunx` works in place of `npx`. A non-default cloud is set with `CATALYST_CLOUD_BASE_URL` or `--base-url <url>`.
+Passing the key as an environment variable is the recommended form, because a key typed into a command line lands in your shell history. With no key in the environment and a terminal attached, `catalyst-skills login` prompts for it without echoing it; `--key <your-personal-key>` is the third form, for a script. `npx @catalyst-cloud/catalyst-skills login` works without the global install, and `bunx` works in place of `npx`. A non-default cloud is set with `CATALYST_CLOUD_BASE_URL` or `--base-url <url>`.
 
 That is the whole setup. Everything below explains what you just installed.
 
 ## What this is
 
-Eight skills that let your coding agent run your own Catalyst Cloud tenant (https://catalystcloud.dev) from your seat: what is happening, what needs you, and what to do about it. They read your tenant through the Catalyst Cloud SDK, write to it through the tenant's agent proxy, and never compose a URL or run a tool of their own; every read, write and subscription is a `catalyst-skills` verb with `--help`. Every skill is plain Markdown under `skills/<name>/SKILL.md` in this repository, and the account key from your tenant admin is the only credential.
+Eight skills that let your coding agent run your own Catalyst Cloud tenant (https://staging.catalystcloud.dev) from your seat: what is happening, what needs you, and what to do about it. They read your tenant through the Catalyst Cloud SDK, write to it through the tenant's agent proxy, and never compose a URL or run a tool of their own; every read, write and subscription is a `catalyst-skills` verb with `--help`. Every skill is plain Markdown under `skills/<name>/SKILL.md` in this repository, and your own personal key is the only credential. Your agent acts as you: the asks it raises and the comments it posts carry your name, and "what needs me" means you.
 
 ## What connecting does
 
-`login` does three things: it calls `GET /api/v1/me` with your key, which discovers your tenant from the key alone; it writes `~/.config/catalyst-cloud/customer.json` with file mode `0600`, holding your key and the absolute path of the CLI so every skill script can spawn the same binary; and it fetches the tenant contract (`GET /api/v1/agent/contract`) and caches it at `~/.config/catalyst-cloud/contract.json` with its ETag, so stage names and ids, label ids, the ask template, thresholds and the route table come from your tenant, live, and no skill restates them.
+`login` does three things: it calls `GET /api/v1/me` with your key, which discovers your tenant and who you are from the key alone; it writes `~/.config/catalyst-cloud/customer.json` with file mode `0600`, holding your key, who you are (id, label, role, your Linear user id) and the absolute path of the CLI so every skill script can spawn the same binary; and it fetches the tenant contract (`GET /api/v1/agent/contract`) and caches it at `~/.config/catalyst-cloud/contract.json` with its ETag, so stage names and ids, label ids, the ask template, thresholds and the route table come from your tenant, live, and no skill restates them.
 
-`login` does not install skills; the install command above did that. Re-running `login` after a key rotation rewrites the config. `catalyst-skills status` prints which tenant this machine is connected to, `catalyst-skills ready` prints one READY or NOT READY verdict with the fix for each failure and who can apply it, and `catalyst-skills --version` prints the package version and its pinned tenant contract range.
+`login` does not install skills; the install command above did that. Re-running `login` after a key rotation rewrites the config. `catalyst-skills status` prints which tenant this machine is connected to and as whom, `catalyst-skills ready` prints one READY or NOT READY verdict with the fix for each failure and who can apply it, and `catalyst-skills --version` prints the package version and its pinned tenant contract range.
 
-The setup skill Catalyst seeds into your repository ends by pointing at this same command. That served skill lives in the Catalyst Cloud application, not here; this is the only connect step a customer runs, and the credential is called the account key in both places.
+The setup skill Catalyst seeds into your repository ends by pointing at this same command. That served skill lives in the Catalyst Cloud application, not here; this is the only connect step a customer runs. The tenant's **account key** (Settings → Account keys, admin-minted) is a different credential — for a host or daemon that runs unattended — and is not what a person connects their own agent with: it would strip your name from everything your agent writes, and `login` says so if you use one.
 
 ## Requirements
 
 - Node 22 or newer. The bundle uses Node's built-in SQLite module for the optional local replica, so there is no native dependency to build; if `better-sqlite3` resolves on the machine it is used instead. `catalyst-skills ready` names the exact reason when an older Node is found.
-- An account key from your tenant admin. The key is the only tenant selector: you never type a tenant or account id.
+- Your personal key, minted by you at Settings → API keys. The key is the only tenant selector: you never type a tenant or account id. If your Linear identity is not matched yet, `login` says so; an admin matches it in Settings → Members, and until then "what needs me" shows everyone's asks.
 - An agent that discovers skills. Claude Code loads the plugin; Codex, Cursor, OpenCode and the rest read the `skills/<name>/SKILL.md` files the `npx skills` installer writes.
 - Bun is optional, only if you prefer `bunx` over `npx`.
 
@@ -110,16 +120,16 @@ Nothing rotates. The replica is upserts and deletes into one file, the cursor is
 | `catalyst-linear` | "Show me the ticket, the history, what Catalyst wrote on it." | Reads a ticket with its comments, relations, labels, linked pull requests and agent sessions inline, from the replica when fresh and the API otherwise, always naming the source; writes comments, card moves, labels and new tickets as the app actor; knows what a ticket accumulates as Catalyst works it. | [`SKILL.md`](skills/catalyst-linear/SKILL.md) |
 | `catalyst-github` | "Show me the PR, the checks, the review, the queue." | A ticket's pull request with its checks, reviews and review threads; whether it is mergeable under the repository's policy; what a PR accumulates as the ticket moves (the branch, the draft, the rewrite, the force-pushes, the labels, the queue). | [`SKILL.md`](skills/catalyst-github/SKILL.md) |
 | `how-catalyst-works` | "How does this work? Why did it do that? How does it prioritise?" | The execution model as references loaded on demand: the eight-phase ladder, the eleven board slots and this team's live stage map, what happens when a phase fails, how the queue is ordered and routed, every exclusion reason, and the coding-account model. Scripts explain one ticket's eligibility in plain English. | [`SKILL.md`](skills/how-catalyst-works/SKILL.md) |
-| `connect-me` | "Connect this machine to my tenant." | Connects the machine to the tenant with the account key, caches the tenant contract, verifies, and offers to start the replica. | [`SKILL.md`](skills/connect-me/SKILL.md) |
+| `connect-me` | "Connect this machine to my tenant." | Connects the machine to the tenant with your own personal key, caches the tenant contract, verifies, and offers to start the replica. | [`SKILL.md`](skills/connect-me/SKILL.md) |
 
 Four skills only read (`whats-happening`, `catalyst-setup`, `catalyst-github`, `how-catalyst-works`). The four that write anything (`catalyst-linear`, `what-needs-me`, `run-this-project`, `connect-me`) are marked so an agent cannot invoke them on its own; the person asks for them. Every skill declares `allowed-tools` scoped to this package's own binary, so none of them needs a blanket shell grant.
 
 ## What a key cannot see yet
 
-Two facts have no tenant-facing route today, and the skills say so by name rather than guess:
+Your personal key reads everything the skills need — tickets, pull requests, the eligibility explainer, the dispatch queue, fleet activity, per-ticket execution history (`catalyst-skills explain --history <ticket>`: phase attempts, remediation rounds, park state) and coding-account status (`catalyst-skills accounts`: provider, declared and observed state, window usage, walls, quarantine — never a credential; enrolling or pausing one is `<your cloud>/settings/coding-accounts`). Two things it cannot do, and the skills say so by name rather than guess:
 
-- Coding-account status (provider, declared and observed state, window usage, walls, quarantine). `catalyst-skills accounts` prints "not visible to an account key yet" and points at `<your cloud>/settings/coding-accounts`, where the tenant's settings page shows it.
-- Per-ticket execution history (phase attempts, remediation rounds, park state). `catalyst-skills explain --history <ticket>` prints the same kind of line and points at `<your cloud>/settings`. What a key can see is the eligibility explainer, the dispatch queue, fleet activity, agent sessions and lease attributions, which is what `explain`, `running` and `queue` read.
+- Release a park. When a ticket is parked after repeated failures, an operator releases it; the skill names the park and points at `<your cloud>/settings`.
+- Read pull-request labels or the reviewer's reaction. The mirror does not carry them; GitHub's own page does.
 
 ## Versions and origins
 
@@ -127,11 +137,11 @@ The package pins the tenant contract range `1.x`, recorded in `package.json` und
 
 ## What it writes on your machine
 
-- `~/.config/catalyst-cloud/customer.json`, written with mode `0600`, holding your account key and the CLI path.
+- `~/.config/catalyst-cloud/customer.json`, written with mode `0600`, holding your personal key, who you are, and the CLI path.
 - `~/.config/catalyst-cloud/contract.json`, the cached tenant contract.
 - Only if you start them: `~/.config/catalyst-cloud/replica.db` with its `.pid` and `.writer.lock` sidecars, and `~/.config/catalyst-cloud/watch-cursor.json`.
 
-The skill files themselves are written by whichever install command you ran, in that tool's own location. Your account key goes into that one config file and nowhere else.
+The skill files themselves are written by whichever install command you ran, in that tool's own location. Your personal key goes into that one config file and nowhere else.
 
 ## Updating
 
@@ -156,11 +166,11 @@ npm uninstall -g @catalyst-cloud/catalyst-skills
 
 ## If login fails
 
-- `catalyst-skills: GET /me failed (401): credential not accepted — ask your tenant admin for a valid account key` — the key is stale or mistyped. Ask your tenant admin for a valid account key, then run `login` again.
+- `catalyst-skills: GET /me failed (401): credential not accepted — mint a personal key at Settings → API keys and log in again` — the key is stale, mistyped or revoked. Mint a new one, then run `login` again.
 - `catalyst-skills: GET /me failed (403): account-not-operational` — the tenant is suspended. This is an admin conversation on the tenant, not a local fix.
 - `catalyst-skills: could not reach <url>: <detail>` — the machine cannot reach the cloud. The URL is named in the message; check `CATALYST_CLOUD_BASE_URL` or `--base-url`.
 - A line naming two contract versions after `Connected to` — the tenant serves a contract outside this bundle's `1.x` range. The config is written; update the bundle before using the other skills.
-- `[catalyst-skills] GET /api/v1/agent/contract refused (403): the contract needs an account key` on stderr — the key is a workstation key, which connects but cannot read the contract or the machine-only routes. Ask your tenant admin for an account key for the full set.
+- `[catalyst-skills] GET /api/v1/agent/contract refused (403): this cloud is older than the bundle …` on stderr — the cloud has not yet deployed personal-key access to the contract. Update the cloud, or connect with the tenant's account key until it has.
 
 ## License
 

package/bin/catalyst-skills.js

@@ -1,10 +1,50 @@
 #!/usr/bin/env node
 // Thin ESM launcher for @catalyst-cloud/catalyst-skills (CTC-1926). tsc does not carry a shebang
 // through emit, so the bin is this two-line wrapper and the program lives in dist/cli.js.
+//
+// ⛔ NEVER `process.exit(code)` STRAIGHT AFTER A WRITE. When stdout is a PIPE — which is how every
+// skill script spawns this CLI — writes are asynchronous, so `process.exit` severs whatever is
+// still in flight AND STILL REPORTS THE ORIGINAL EXIT CODE. The caller then reads a truncated body
+// with a success code and has no way to tell it from a complete one: `query issues --json` on a
+// tenant with ~80+ tickets came back as 65,528 bytes of invalid JSON, exit 0 (0.2.0). Interactive
+// use hid it, because a tty gives stdout a synchronous write path.
+//
+// So: park the code on `process.exitCode`, wait for both streams to drain, and only then exit. The
+// explicit exit stays — `fetch`'s keep-alive sockets can hold the event loop open for seconds after
+// the work is done, and a CLI that lingers is its own defect — but by then nothing is buffered.
 import("../dist/cli.js")
   .then((m) => m.main(process.argv.slice(2)))
-  .then((code) => process.exit(code))
+  .then((code) => finish(code))
   .catch((err) => {
     console.error(`catalyst-skills: failed to load: ${err instanceof Error ? err.message : String(err)}`);
-    process.exit(1);
+    finish(1);
   });
+
+/**
+ * Resolve once every byte already handed to `stream` has reached the other end. The empty write is
+ * ordered behind the real ones, so its callback is the drain signal; a destroyed or errored stream
+ * (a reader that hung up) resolves immediately rather than hanging the process forever.
+ */
+function drained(stream) {
+  return new Promise((resolve) => {
+    if (!stream || stream.destroyed || stream.writableEnded) return resolve();
+    let settled = false;
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      resolve();
+    };
+    stream.once("error", done);
+    try {
+      stream.write("", done);
+    } catch {
+      done();
+    }
+  });
+}
+
+async function finish(code) {
+  process.exitCode = code;
+  await Promise.all([drained(process.stdout), drained(process.stderr)]);
+  process.exit(code);
+}

package/dist/args.js

@@ -3,7 +3,7 @@
 // error naming the verb, and every verb's --help is generated from its own table.
 import { UsageError } from "./errors.js";
 const GLOBAL_FLAGS = {
-    key: { value: true, help: "account key (or CATALYST_CLOUD_TOKEN)" },
+    key: { value: true, help: "your personal key (or CATALYST_CLOUD_TOKEN)" },
     "base-url": { value: true, help: "Catalyst Cloud origin (or CATALYST_CLOUD_BASE_URL)" },
     "skills-dir": { value: true, help: "where the skills are copied (default ~/.claude/skills)" },
     force: { value: false, help: "replace a skill directory this package did not install" },
@@ -38,11 +38,15 @@ export const FLAG_TABLES = {
         "stale-ms": { value: true, help: "status: heartbeat age that counts as stale (default 15000)" },
     },
     explain: {
-        history: { value: false, help: "per-ticket execution history (not visible to an account key yet)" },
+        history: { value: false, help: "per-ticket execution history instead of the eligibility reason" },
+    },
+    history: {},
+    running: {
+        ticket: { value: true, help: "with --phase: also the lease attributions for this (ticket, phase)" },
+        phase: { value: true, help: "with --ticket: the phase whose lease attributions to read" },
     },
-    running: {},
     queue: {
-        team: { value: true, help: "team key" },
+        team: { value: true, help: "team key (default: every team the tenant contract names)" },
     },
     watch: {
         team: { value: true, help: "scope: a team key" },
@@ -81,6 +85,7 @@ export const FLAG_TABLES = {
         default: { value: true, help: "raise: the default if silent" },
         blocks: { value: true, repeat: true, help: "raise: a ticket this decision blocks (repeatable)" },
         "nothing-to-block": { value: false, help: "raise: declare that nothing is blocked" },
+        anyone: { value: false, help: "list: every open ask in the tenant, not only the ones assigned to you" },
         "ask-key": { value: true, help: "raise: idempotency key" },
         answer: { value: true, help: "accept: the answering comment id" },
         role: { value: true, help: "accept: the role recording the answer" },
@@ -95,16 +100,17 @@ export const VERB_USAGE = {
     notice: "notice",
     me: "me [--json]",
     contract: "contract [--refresh] [--path <a.b.c>] [--json]",
-    query: "query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <n>> [--team K] [--project P] [--state S] [--limit N] [--source replica|api] [--json]",
+    query: "query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <cursor|head>> [--team K] [--project P] [--state S] [--limit N] [--source replica|api] [--json]",
     replica: "replica <start [--detach]|stop|status [--probe] [--json]|sql \"<select>\"|schema [table]> [--db <path>]",
     explain: "explain <ticket> [--history] [--json]",
-    running: "running [--json]",
+    history: "history <ticket> [--json]",
+    running: "running [--ticket T --phase P] [--json]",
     queue: "queue [--team K] [--json]",
     watch: "watch [--team K] [--ticket T]... [--project P] [--exec CMD] [--cursor-file <path>] [--from cursor|head]",
     write: "write <comment <ticket> --body|--stdin [--parent] [--bookkeeping] [--as-user] | state <ticket> --slot|--state-id|--state-type | label <ticket> --add... --remove... | create --team --title [--label] [--priority] | reaction <ticket>|--comment <id> --emoji <e> | attachment <ticket> --title --url | session <ticket> [--title] [--plan-file] [--activity]>",
-    ask: "ask <raise --team --title [--context] [--option]... [--default] --blocks <ticket>...|--nothing-to-block [--ask-key] | accept <askTicket> --answer <commentId> --role <role> | list [--json]>",
+    ask: "ask <raise --team --title [--context] [--option]... [--default] --blocks <ticket>...|--nothing-to-block [--ask-key] | accept <askTicket> --answer <commentId> --role <role> | list [--anyone] [--json]>",
     ready: "ready [--json]",
-    accounts: "accounts",
+    accounts: "accounts [--json]",
 };
 export function parseArgs(argv) {
     const out = {

package/dist/ask.js

@@ -24,7 +24,7 @@ export async function cmdAsk(args, ctx) {
         case "accept":
             return accept(args, ctx, doc, api, rest);
         case "list":
-            return list(args, ctx, doc, api);
+            return list(args, ctx, doc, api, cfg);
         default:
             throw new UsageError(`unknown ask subcommand: ${sub}`);
     }
@@ -74,6 +74,18 @@ async function accept(args, ctx, doc, api, rest) {
     ctx.stdout(args.json ? JSON.stringify(result) : `ask ${ask.identifier}: answer ${answer} recorded by ${role}`);
     return 0;
 }
+/** Decide the inbox scope from the connected identity and the `--anyone` flag. A personal key with a
+ *  matched Linear identity reads "mine" by default; `--anyone` widens; an unmatched identity or a
+ *  host key cannot mean "me" and says so rather than filtering to nothing. */
+export function inboxScope(cfg, anyone) {
+    if (anyone)
+        return { kind: "anyone" };
+    if (!cfg.user)
+        return { kind: "no-person" };
+    if (!cfg.user.linearUserId)
+        return { kind: "unmatched", label: cfg.user.label };
+    return { kind: "mine", linearUserId: cfg.user.linearUserId, label: cfg.user.label };
+}
 /** Rank open asks by the priority-weighted count of open tickets each one blocks. Priority 1 (urgent)
  *  weighs 4, 4 (low) weighs 1, 0 (none) weighs 1. */
 export function rankAsks(issues, doc, openState) {
@@ -113,22 +125,31 @@ export function rankAsks(issues, doc, openState) {
             state: String(issue.state ?? ""),
             blocks: blocked,
             score: blocked.reduce((sum, id) => sum + weight(byIdentifier.get(id)), 0),
+            assigneeId: typeof issue.assignee_id === "string" && issue.assignee_id !== "" ? issue.assignee_id : null,
         });
     }
     return out.sort((a, b) => b.score - a.score || a.identifier.localeCompare(b.identifier));
 }
-async function list(args, ctx, doc, api) {
+async function list(args, ctx, doc, api, cfg) {
     const [issuesRes, states] = await Promise.all([api.getJson("/api/v1/issues", { query: { limit: 500 } }), fetchWorkflowStates(api)]);
     const issues = rowsOf(issuesRes.body);
     const terminal = new Set(states.filter((s) => ["completed", "canceled", "cancelled"].includes(s.type.toLowerCase())).map((s) => s.name.toLowerCase()));
     const openState = (issue) => !terminal.has(String(issue.state ?? "").toLowerCase());
-    const ranked = rankAsks(issues, doc, openState);
+    const all = rankAsks(issues, doc, openState);
+    const scope = inboxScope(cfg, flagBool(args, "anyone"));
+    const ranked = scope.kind === "mine" ? all.filter((a) => a.assigneeId === scope.linearUserId) : all;
     if (args.json) {
-        ctx.stdout(JSON.stringify(ranked));
+        ctx.stdout(JSON.stringify({ scope, asks: ranked }));
         return 0;
     }
+    if (scope.kind === "unmatched") {
+        ctx.stderr(`[catalyst-skills] your Linear identity is not matched yet (an admin matches it in Settings → Members), so this is every open ask, not only yours`);
+    }
+    else if (scope.kind === "no-person") {
+        ctx.stderr(`[catalyst-skills] connected with the tenant's account key, which names no person — this is every open ask; log in with your personal key to see only yours`);
+    }
     if (ranked.length === 0) {
-        ctx.stdout("no open asks");
+        ctx.stdout(scope.kind === "mine" ? `no open asks assigned to ${scope.label} (${all.length} open in the tenant — add --anyone to see them)` : "no open asks");
         return 0;
     }
     for (const a of ranked)

package/dist/cli.js

@@ -6,7 +6,7 @@ import { CONFIG_MODE, DEFAULT_BASE_URL, PACKAGE_NAME, cliPath, configPathFor, co
 import { loadContract, pickPath } from "./contract.js";
 import { CliError, MeError, UsageError } from "./errors.js";
 import { fetchMe } from "./http.js";
-import { cmdAccounts, cmdExplain, cmdQueue, cmdRunning } from "./execution.js";
+import { cmdAccounts, cmdExplain, cmdHistory, cmdQueue, cmdRunning } from "./execution.js";
 import { cmdQuery } from "./query.js";
 import { cmdReady } from "./ready.js";
 import { cmdReplica } from "./replica.js";
@@ -37,14 +37,14 @@ export function usageText() {
         `${PACKAGE_NAME} — the Catalyst Cloud customer CLI: connect to your tenant, read through the SDK, write through the agent proxy`,
         "",
         "Usage:",
-        "  catalyst-skills login [--key <account-key>] [--base-url <url>] [--start-replica]",
+        "  catalyst-skills login [--key <personal-key>] [--base-url <url>] [--start-replica]",
         "  catalyst-skills join ...   (deprecated alias of login; removed in the next minor version)",
         "  catalyst-skills install [--skills-dir <dir>] [--force]   (repair path; your agent's own command installs the skills)",
         "  catalyst-skills status | notice | me | ready | accounts",
         "  catalyst-skills contract [--refresh] [--path <a.b.c>]",
-        "  catalyst-skills query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <n>>",
+        "  catalyst-skills query <issues|issue <id>|pulls|pull <id>|projects|cycles|search <terms>|changes --since <cursor|head>>",
         "  catalyst-skills replica <start [--detach]|stop|status [--probe]|sql \"<select>\"|schema [table]>",
-        "  catalyst-skills explain <ticket> | running | queue [--team K]",
+        "  catalyst-skills explain <ticket> | history <ticket> | running [--ticket T --phase P] | queue [--team K]",
         "  catalyst-skills watch [--team K] [--ticket T]... [--project P] [--exec CMD]",
         "  catalyst-skills write <comment|state|label|create|reaction|attachment|session> ...",
         "  catalyst-skills ask <raise|accept|list> ...",
@@ -148,6 +148,8 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
                 return await cmdReplica(args, ctx, deps.replica);
             case "explain":
                 return await cmdExplain(args, ctx);
+            case "history":
+                return await cmdHistory(args, ctx);
             case "running":
                 return await cmdRunning(args, ctx);
             case "queue":
@@ -161,7 +163,7 @@ export async function main(argv, ctx = defaultCtx(), deps = {}) {
             case "ready":
                 return await cmdReady(args, ctx, { skillNames: CUSTOMER_SKILLS, loadSdk: deps.loadSdk });
             case "accounts":
-                return cmdAccounts(ctx);
+                return await cmdAccounts(args, ctx);
             default:
                 ctx.stderr(`unknown command: ${args.command}`);
                 ctx.stderr(usageText());
@@ -190,10 +192,10 @@ async function cmdLogin(args, ctx, deps) {
     const manifest = readManifest();
     let key = (args.key ?? ctx.env.CATALYST_CLOUD_TOKEN ?? "").trim();
     if (!key && (deps.isTty ?? stdinIsTty)()) {
-        key = (await (deps.promptSecret ?? promptSecret)("Account key (not echoed): ")).trim();
+        key = (await (deps.promptSecret ?? promptSecret)("Personal key (not echoed): ")).trim();
     }
     if (!key)
-        throw new UsageError("login needs an account key: pass --key <account-key> or set CATALYST_CLOUD_TOKEN");
+        throw new UsageError("login needs your personal key: pass --key <personal-key> or set CATALYST_CLOUD_TOKEN");
     const baseUrl = normalizeBaseUrl(args.baseUrl ?? ctx.env.CATALYST_CLOUD_BASE_URL ?? DEFAULT_BASE_URL);
     const me = await fetchMe(baseUrl, key, ctx.fetch);
     let existing;
@@ -213,6 +215,7 @@ async function cmdLogin(args, ctx, deps) {
         name: me.name,
         permissions: me.permissions,
         principal: me.principal,
+        ...(me.user ? { user: me.user } : {}),
         joinedAt: ctx.now().toISOString(),
         lastSkillBundleVersion: manifest.version,
         skillsDir,
@@ -221,6 +224,12 @@ async function cmdLogin(args, ctx, deps) {
     };
     const written = writeConfig(ctx.home, config);
     ctx.stdout(`Connected to ${me.name} (${me.slug}) — account ${me.account}`);
+    if (me.user) {
+        ctx.stdout(`Connected as ${me.user.label} (${me.user.role})${me.user.linearUserId ? "" : " — your Linear identity is not matched yet, so \"what needs me\" will show everyone's asks until an admin matches it in Settings"}`);
+    }
+    else {
+        ctx.stderr(`[catalyst-skills] this is the tenant's account key (a host credential), not your own — the skills work, but nothing your agent writes will carry your name and "what needs me" cannot mean you. Mint a personal key at Settings → API keys and log in with that.`);
+    }
     ctx.stdout(`Config written to ${written.path} (mode ${formatMode(written.mode)}, holds your key and the CLI path)${written.mode === CONFIG_MODE ? "" : ` — expected ${formatMode(CONFIG_MODE)}; chmod it by hand`}`);
     ctx.stdout(`Tenant contract range: ${manifest.tenantContractRange}`);
     try {
@@ -271,11 +280,12 @@ function cmdStatus(ctx) {
     const manifest = readManifest();
     const cfg = loadConfig(ctx.home);
     if (!cfg) {
-        ctx.stdout(`Not connected yet — run: CATALYST_CLOUD_TOKEN=<your account key> npx ${PACKAGE_NAME} login`);
+        ctx.stdout(`Not connected yet — run: CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE_NAME} login`);
         return 0;
     }
     ctx.stdout(`Tenant: ${cfg.name} (${cfg.slug}) — account ${cfg.account}`);
     ctx.stdout(`API: ${cfg.baseUrl} (principal: ${cfg.principal})`);
+    ctx.stdout(cfg.user ? `As: ${cfg.user.label} (${cfg.user.role})` : "As: the tenant's account key (a host credential — no person)");
     ctx.stdout(`Bundle: ${PACKAGE_NAME} ${manifest.version} (tenant contract range: ${manifest.tenantContractRange})`);
     if (cfg.cliPath)
         ctx.stdout(`CLI: ${cfg.cliPath}${existsSync(cfg.cliPath) ? "" : " (missing — re-run login)"}`);
@@ -290,6 +300,8 @@ async function cmdMe(args, ctx) {
     else {
         ctx.stdout(`${me.name} (${me.slug}) — account ${me.account}`);
         ctx.stdout(`principal: ${me.principal}; permissions: ${me.permissions ? me.permissions.join(", ") : "unrestricted"}`);
+        if (me.user)
+            ctx.stdout(`user: ${me.user.label} (${me.user.role}); linear: ${me.user.linearUserId ?? "unmatched"}`);
     }
     return 0;
 }

package/dist/config.js

@@ -70,7 +70,7 @@ export function loadConfig(home) {
 export function requireConfig(ctx) {
     const cfg = loadConfig(ctx.home);
     if (!cfg) {
-        throw new CliError(`not connected yet — run: CATALYST_CLOUD_TOKEN=<account key> npx ${PACKAGE_NAME} login`, "not-configured");
+        throw new CliError(`not connected yet — run: CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE_NAME} login`, "not-configured");
     }
     return cfg;
 }

package/dist/contract.js

@@ -52,7 +52,7 @@ export function assertContractRange(version, range) {
  * Load the contract per the cloud's own cache policy: a cache younger than `doc.cache.maxAgeSeconds`
  * is used as-is; otherwise a conditional GET revalidates it (304 refreshes `fetchedAt`, 200 replaces
  * the document). A network failure on a cache older than `staleRefusalSeconds` refuses; a 403 (a
- * workstation key) refuses naming the account key; a major version outside the bundle's range refuses
+ * personal key on an older cloud) refuses naming the cloud version; a major version outside the bundle's range refuses
  * naming both versions.
  */
 export async function loadContract(ctx, cfg, opts = {}) {
@@ -79,7 +79,7 @@ export async function loadContract(ctx, cfg, opts = {}) {
     }
     catch (err) {
         if (err instanceof CliError && err.status === 403) {
-            throw new CliError(`GET ${CONTRACT_ROUTE} refused (403): the contract needs an account key (ctc_acct_…); this key is a workstation key — ask your tenant admin for an account key`, "contract-forbidden", 2, 403);
+            throw new CliError(`GET ${CONTRACT_ROUTE} refused (403): this cloud is older than the bundle and does not yet admit a personal key on the contract — update the cloud, or log in with the tenant's account key until it is`, "contract-forbidden", 2, 403);
         }
         if (err instanceof MeError && err.kind === "network" && cached) {
             if (ageSeconds >= cached.doc.cache.staleRefusalSeconds) {