@catalyst-cloud/cli 0.8.0

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

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: spawn the catalyst-skills 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.
+import { spawnSync } from "node:child_process";
+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 NOT_CONFIGURED_EXIT = 2;
+
+export function configPath() {
+  const home = process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? "/";
+  return join(home, ".config", "catalyst-cloud", "customer.json");
+}
+
+/** The connected-machine config, or exit 2 with the one line that says how to connect. */
+export function loadConfig() {
+  const path = configPath();
+  if (!existsSync(path)) notConfigured(`no config at ${path}`);
+  try {
+    const cfg = JSON.parse(readFileSync(path, "utf8"));
+    if (!hasCredential(cfg)) notConfigured(`config at ${path} has no key or login`);
+    return cfg;
+  } catch (err) {
+    if (err && err.exitCode === NOT_CONFIGURED_EXIT) throw err;
+    notConfigured(`config at ${path} is unreadable`);
+  }
+}
+
+function notConfigured(why) {
+  process.stderr.write(`not connected (${why}) — run: ${CONNECT_COMMAND}\n`);
+  process.exit(NOT_CONFIGURED_EXIT);
+}
+
+/**
+ * Run one catalyst-skills 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.
+ */
+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 res = spawnSync(cmd, argv, {
+    input: opts.stdin,
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+    shell: !useRecorded && process.platform === "win32",
+    env: process.env,
+  });
+  if (res.error) {
+    process.stderr.write(`could not run ${cmd}: ${res.error.message}\n`);
+    process.exit(NOT_CONFIGURED_EXIT);
+  }
+  const stdout = res.stdout ?? "";
+  const stderr = res.stderr ?? "";
+  if (res.status === NOT_CONFIGURED_EXIT && /not (joined|connected|configured)/i.test(stderr)) {
+    process.stderr.write(stderr);
+    process.exit(NOT_CONFIGURED_EXIT);
+  }
+  return { code: res.status ?? 1, stdout, stderr };
+}
+
+/** Run a verb and require success; on failure print the CLI's own stderr and exit with its code (or 1). */
+export function mustRun(args, opts = {}) {
+  const r = runCli(args, opts);
+  if (r.code !== 0) {
+    if (r.stderr) process.stderr.write(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
+    if (r.stdout && !opts.quiet) process.stdout.write(r.stdout.endsWith("\n") ? r.stdout : `${r.stdout}\n`);
+    process.exit(r.code === 0 ? 1 : r.code);
+  }
+  return r;
+}
+
+/** Parse the CLI's --json stdout; a non-JSON answer is a failed check, exit 1. */
+export function parseJson(stdout, what = "output") {
+  try {
+    return JSON.parse(stdout.trim());
+  } catch {
+    process.stderr.write(`could not parse ${what} as JSON: ${stdout.trim().slice(0, 200)}\n`);
+    process.exit(1);
+  }
+}
+
+/** Minimal flag parsing for the scripts: --name value, --name=value, --flag, repeated flags collect. */
+export function parseFlags(argv, spec) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") return { help: true, flags, positionals };
+    if (a.startsWith("--")) {
+      let name = a.slice(2);
+      let value;
+      const eq = name.indexOf("=");
+      if (eq !== -1) {
+        value = name.slice(eq + 1);
+        name = name.slice(0, eq);
+      }
+      const s = spec[name];
+      if (!s) {
+        process.stderr.write(`unknown option --${name} (try --help)\n`);
+        process.exit(1);
+      }
+      if (s.value) {
+        if (value === undefined) value = argv[++i];
+        if (value === undefined || value === "") {
+          process.stderr.write(`--${name} needs a value\n`);
+          process.exit(1);
+        }
+        if (s.repeat) (flags[name] ??= []).push(value);
+        else flags[name] = value;
+      } else flags[name] = true;
+      continue;
+    }
+    positionals.push(a);
+  }
+  return { help: false, flags, positionals };
+}
+
+export function printHelp(usage, spec, notes = []) {
+  const lines = [`Usage: ${usage}`, ""];
+  const names = Object.keys(spec);
+  if (names.length) {
+    lines.push("Options:");
+    for (const n of names) lines.push(`  --${n}${spec[n].value ? " <value>" : ""}  ${spec[n].help}`);
+    lines.push("");
+  }
+  lines.push(...notes, "", "Exit codes: 0 ok · 1 the check failed or the arguments were wrong · 2 this machine is not connected to a tenant");
+  process.stdout.write(lines.join("\n") + "\n");
+}

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

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// lib/credential.mjs — is this machine connected? The ONE place a skill script decides it, vendored
+// byte-identical into every skill's scripts/lib/ from skill-lib/credential.mjs at the package root
+// (`npm run skill-lib:sync`; a test fails on any drift). Skills install one directory at a time, so
+// each carries its own copy. This file is a library — run a sibling script with --help for usage.
+//
+// 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
+// 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)";
+
+/** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
+export function hasCredential(cfg) {
+  if (cfg === null || typeof cfg !== "object") return false;
+  const key = cfg["key"];
+  if (typeof key === "string" && key !== "") return true;
+  const login = cfg["auth"];
+  return (
+    login !== null &&
+    typeof login === "object" &&
+    login["kind"] === "oauth" &&
+    typeof login["refreshToken"] === "string" &&
+    login["refreshToken"] !== ""
+  );
+}

package/skills/unstick/scripts/unstick.mjs

@@ -0,0 +1,57 @@
+#!/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
+// 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";
+
+const SPEC = {
+  because: { value: true, help: "what changed since the ticket was held; runs the real release after the preview" },
+  "retry-unchanged": { value: false, help: "release even though nothing the cloud can see changed (say what did in --because)" },
+  class: { value: true, help: "release every ticket on --team parked under this failure class" },
+  team: { value: true, help: "with --class: the team key" },
+  limit: { value: true, help: "with --class: at most this many tickets (the cloud caps it at 25)" },
+};
+
+const { help, flags, positionals } = parseFlags(process.argv.slice(2), SPEC);
+const ticket = positionals[0];
+const byClass = typeof flags.class === "string";
+if (help || (!ticket && !byClass) || (byClass && (ticket || typeof flags.team !== "string"))) {
+  printHelp("node scripts/unstick.mjs <ticket> [--because <text>] [--retry-unchanged] [--help] | --class <c> --team <K> [--because <text>] [--retry-unchanged] [--limit N] [--help]", SPEC, [
+    "Without --because it changes nothing: it prints the explanation, the history (every governor holding the ticket",
+    "and past releases) and a dry-run release. With --because it then runs the real release. Read references/playbook.md",
+    "before passing --because. A refused release exits 1 with the refusals in the document.",
+  ]);
+  process.exit(help ? 0 : 1);
+}
+
+const releaseArgs = byClass ? ["release", "--class", flags.class, "--team", flags.team] : ["release", ticket];
+if (flags["retry-unchanged"]) releaseArgs.push("--retry-unchanged");
+if (byClass && typeof flags.limit === "string") releaseArgs.push("--limit", flags.limit);
+
+const out = {};
+if (!byClass) {
+  out.explain = parseJson(mustRun(["explain", ticket, "--json"]).stdout, "explain");
+  out.history = parseJson(mustRun(["explain", ticket, "--history", "--json"]).stdout, "history");
+}
+
+const preview = runCli([...releaseArgs, "--dry-run", "--json"]);
+if (preview.code !== 0 && preview.code !== 1) {
+  process.stderr.write(preview.stderr);
+  process.exit(preview.code);
+}
+out.preview = parseJson(preview.stdout, "the dry-run release");
+
+let exit = 0;
+if (typeof flags.because === "string") {
+  const real = runCli([...releaseArgs, "--because", flags.because, "--json"]);
+  if (real.code !== 0 && real.code !== 1) {
+    process.stderr.write(real.stderr);
+    process.exit(real.code);
+  }
+  out.release = parseJson(real.stdout, "the release");
+  exit = real.code;
+}
+
+process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+process.exit(exit);

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

@@ -0,0 +1,41 @@
+---
+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:*)
+---
+<!-- vendored-from: @catalyst-cloud/catalyst-skills@0.8.0 — written in this repository for customer tenants -->
+
+# 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.
+
+## 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.
+
+- `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.
+
+## Load on demand
+
+| when | read |
+| -- | -- |
+| about to file an ask, or unsure whether something is one | `references/raising-a-decision.md` |
+| presenting the inbox, or the person asks what "waiting on me" means | `references/reading-the-inbox.md` |
+| an answer arrived, anywhere | `references/settling-an-answer.md` |
+
+The `catalyst-linear` skill posts the comment that carries an answer given in chat and reads an ask's thread; `whats-happening` explains a held ticket that stays excluded after the answer.
+
+## Rules
+
+- **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.
+- **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.**

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

@@ -0,0 +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"
+  default_prompt: "Use $what-needs-me to show me what is waiting on my decision."
+policy:
+  allow_implicit_invocation: false

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

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

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

@@ -0,0 +1,41 @@
+# 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.
+
+## 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.
+
+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).
+
+## 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.
+
+`--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.
+
+## 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.
+
+## 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

@@ -0,0 +1,38 @@
+# 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:
+
+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);
+3. it is still **open**;
+4. what it **blocks** reaches open work: at least one ticket it holds is itself not done or canceled.
+
+A ticket that carries the ask marker label and is assigned to the person shows even with zero blocks. That is the **declared** ask. The four-part rule above is the **inferred** one, and the view offers both modes: asks only (the default) and everything the person is holding up, minus items an open unblock ask already covers.
+
+So an ask that holds nothing is real, but the person may never see it in their own view. `inbox.mjs` lists such asks last and marked, so you can attach the work they should block.
+
+## 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".
+
+## 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.
+- 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.
+
+## 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.

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

@@ -0,0 +1,37 @@
+# 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 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.
+
+**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.
+
+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.
+
+## Who settles
+
+The role that raised the ask, or the owner of the scope it belongs to. The desk settles asks that have no owner. The human never has to run anything; their part ends when they answer. Never settle another role's ask without saying so in the thread.
+
+## 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.
+
+## 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.

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

@@ -0,0 +1,56 @@
+#!/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.
+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" },
+};
+
+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",
+    "listed last with a marker so you can attach the work it should block (references/reading-the-inbox.md).",
+  ]);
+  process.exit(0);
+}
+
+const answer = parseJson(mustRun(["ask", "list", "--json", ...(flags.anyone ? ["--anyone"] : [])], { quiet: true }).stdout, "ask list");
+const rows = answer.asks;
+const scope = answer.scope;
+const wanted = flags.team ? rows.filter((r) => String(r.identifier).toUpperCase().startsWith(`${flags.team.toUpperCase()}-`)) : rows;
+if (flags.json) {
+  process.stdout.write(JSON.stringify({ scope, asks: wanted }) + "\n");
+  process.exit(0);
+}
+// 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");
+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.exit(0);
+}
+const holding = wanted.filter((r) => r.blocks.length > 0);
+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`);
+}
+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`);
+  for (const r of idle) process.stdout.write(`   ${r.identifier}  ${r.title}\n`);
+} else if (idle.length) {
+  process.stdout.write(`\n(${idle.length} more ask${idle.length === 1 ? "" : "s"} hold nothing; --all lists them)\n`);
+}
+process.exit(0);

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

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+// lib/cli.mjs — the one way a skill script reaches Catalyst Cloud: spawn the catalyst-skills 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.
+import { spawnSync } from "node:child_process";
+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 NOT_CONFIGURED_EXIT = 2;
+
+export function configPath() {
+  const home = process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? "/";
+  return join(home, ".config", "catalyst-cloud", "customer.json");
+}
+
+/** The connected-machine config, or exit 2 with the one line that says how to connect. */
+export function loadConfig() {
+  const path = configPath();
+  if (!existsSync(path)) notConfigured(`no config at ${path}`);
+  try {
+    const cfg = JSON.parse(readFileSync(path, "utf8"));
+    if (!hasCredential(cfg)) notConfigured(`config at ${path} has no key or login`);
+    return cfg;
+  } catch (err) {
+    if (err && err.exitCode === NOT_CONFIGURED_EXIT) throw err;
+    notConfigured(`config at ${path} is unreadable`);
+  }
+}
+
+function notConfigured(why) {
+  process.stderr.write(`not connected (${why}) — run: ${CONNECT_COMMAND}\n`);
+  process.exit(NOT_CONFIGURED_EXIT);
+}
+
+/**
+ * Run one catalyst-skills 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.
+ */
+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 res = spawnSync(cmd, argv, {
+    input: opts.stdin,
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+    shell: !useRecorded && process.platform === "win32",
+    env: process.env,
+  });
+  if (res.error) {
+    process.stderr.write(`could not run ${cmd}: ${res.error.message}\n`);
+    process.exit(NOT_CONFIGURED_EXIT);
+  }
+  const stdout = res.stdout ?? "";
+  const stderr = res.stderr ?? "";
+  if (res.status === NOT_CONFIGURED_EXIT && /not (joined|connected|configured)/i.test(stderr)) {
+    process.stderr.write(stderr);
+    process.exit(NOT_CONFIGURED_EXIT);
+  }
+  return { code: res.status ?? 1, stdout, stderr };
+}
+
+/** Run a verb and require success; on failure print the CLI's own stderr and exit with its code (or 1). */
+export function mustRun(args, opts = {}) {
+  const r = runCli(args, opts);
+  if (r.code !== 0) {
+    if (r.stderr) process.stderr.write(r.stderr.endsWith("\n") ? r.stderr : `${r.stderr}\n`);
+    if (r.stdout && !opts.quiet) process.stdout.write(r.stdout.endsWith("\n") ? r.stdout : `${r.stdout}\n`);
+    process.exit(r.code === 0 ? 1 : r.code);
+  }
+  return r;
+}
+
+/** Parse the CLI's --json stdout; a non-JSON answer is a failed check, exit 1. */
+export function parseJson(stdout, what = "output") {
+  try {
+    return JSON.parse(stdout.trim());
+  } catch {
+    process.stderr.write(`could not parse ${what} as JSON: ${stdout.trim().slice(0, 200)}\n`);
+    process.exit(1);
+  }
+}
+
+/** Minimal flag parsing for the scripts: --name value, --name=value, --flag, repeated flags collect. */
+export function parseFlags(argv, spec) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") return { help: true, flags, positionals };
+    if (a.startsWith("--")) {
+      let name = a.slice(2);
+      let value;
+      const eq = name.indexOf("=");
+      if (eq !== -1) {
+        value = name.slice(eq + 1);
+        name = name.slice(0, eq);
+      }
+      const s = spec[name];
+      if (!s) {
+        process.stderr.write(`unknown option --${name} (try --help)\n`);
+        process.exit(1);
+      }
+      if (s.value) {
+        if (value === undefined) value = argv[++i];
+        if (value === undefined || value === "") {
+          process.stderr.write(`--${name} needs a value\n`);
+          process.exit(1);
+        }
+        if (s.repeat) (flags[name] ??= []).push(value);
+        else flags[name] = value;
+      } else flags[name] = true;
+      continue;
+    }
+    positionals.push(a);
+  }
+  return { help: false, flags, positionals };
+}
+
+export function printHelp(usage, spec, notes = []) {
+  const lines = [`Usage: ${usage}`, ""];
+  const names = Object.keys(spec);
+  if (names.length) {
+    lines.push("Options:");
+    for (const n of names) lines.push(`  --${n}${spec[n].value ? " <value>" : ""}  ${spec[n].help}`);
+    lines.push("");
+  }
+  lines.push(...notes, "", "Exit codes: 0 ok · 1 the check failed or the arguments were wrong · 2 this machine is not connected to a tenant");
+  process.stdout.write(lines.join("\n") + "\n");
+}

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

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// lib/credential.mjs — is this machine connected? The ONE place a skill script decides it, vendored
+// byte-identical into every skill's scripts/lib/ from skill-lib/credential.mjs at the package root
+// (`npm run skill-lib:sync`; a test fails on any drift). Skills install one directory at a time, so
+// each carries its own copy. This file is a library — run a sibling script with --help for usage.
+//
+// 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
+// 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)";
+
+/** True when `cfg` (parsed customer.json) holds a usable credential of either kind. Never throws. */
+export function hasCredential(cfg) {
+  if (cfg === null || typeof cfg !== "object") return false;
+  const key = cfg["key"];
+  if (typeof key === "string" && key !== "") return true;
+  const login = cfg["auth"];
+  return (
+    login !== null &&
+    typeof login === "object" &&
+    login["kind"] === "oauth" &&
+    typeof login["refreshToken"] === "string" &&
+    login["refreshToken"] !== ""
+  );
+}