@catalyst-cloud/catalyst-skills 0.3.1 → 0.5.0

package/dist/release.js

@@ -0,0 +1,142 @@
+// release.ts — `catalyst-skills release`: a person's release of a parked or held ticket, or of every
+// ticket on one team parked under one failure class, through the contract's `ticket-release` and
+// `ticket-release-class` routes. The cloud reads every governor holding the ticket and either releases
+// all of them or releases nothing and names, per governor, the human action that does fix it; this verb
+// prints that answer and exits 1 on a refusal so a script can branch on it.
+//
+// ⛔ NOTHING IS RELEASED WITHOUT A REASON. `--because` (what changed) is required on a real release and
+// is recorded in the tenant's release audit; only `--dry-run` may omit it. `--retry-unchanged` is the
+// explicit statement that something the mirror cannot see changed — the cloud refuses an unchanged
+// cause without it.
+import { flagBool, flagString, positionals } from "./args.js";
+import { requireConfig } from "./config.js";
+import { loadContract } from "./contract.js";
+import { CliError, UsageError } from "./errors.js";
+import { needsNewerCloud } from "./execution.js";
+import { apiClient } from "./transport.js";
+/** One release written as a person reads it: "unparked implement", "cleared the validate hold". */
+export function describeAction(a) {
+    switch (a.op) {
+        case "unpark":
+            return `unparked ${a.phase ?? "a phase"}`;
+        case "clear_validate_hold":
+            return "cleared the validate hold";
+        case "clear_no_change_hold":
+            return "cleared the no-change hold";
+        case "grant_round_threshold_cycle":
+            return "bought one more repair cycle";
+        default:
+            return `${a.op}${a.phase ? ` at ${a.phase}` : ""}`;
+    }
+}
+const refusalLine = (r) => `  ${r.code}: ${r.humanAction}`;
+export function renderTicketRelease(ticket, r) {
+    if (r.error === "team_changed") {
+        return [`${ticket} moved from team ${r.expectedTeamKey ?? "(none)"} to ${r.teamKey ?? "(none)"} while the release was being checked — run it again`];
+    }
+    const lines = [];
+    const dry = r.dryRun === true;
+    if (r.outcome === "nothing-held") {
+        lines.push(`${ticket}: nothing holds this ticket — run \`catalyst-skills explain ${ticket}\` for why it is not running`);
+    }
+    else if (r.outcome === "refused") {
+        lines.push(dry ? `${ticket} (dry run): would be refused — nothing would be released:` : `${ticket}: refused — nothing was released:`);
+        for (const x of r.refused ?? [])
+            lines.push(refusalLine(x));
+        const blocked = r.releasable ?? [];
+        if (blocked.length > 0)
+            lines.push(`  (it would otherwise have ${blocked.map(describeAction).join(", ")})`);
+    }
+    else if (dry) {
+        lines.push(`${ticket} (dry run): would release — ${(r.releasable ?? []).map(describeAction).join(", ")}`);
+    }
+    else {
+        lines.push(`${ticket}: released — ${(r.released ?? []).map(describeAction).join(", ")}`);
+    }
+    for (const w of r.warnings ?? [])
+        lines.push(`warning: ${w}`);
+    return lines;
+}
+export function renderClassRelease(r) {
+    const released = r.released ?? [];
+    const refused = r.refused ?? [];
+    const nothing = r.nothingHeld ?? [];
+    const head = `${r.team ?? "?"} ${r.class ?? "?"}${r.dryRun ? " (dry run)" : ""}: released ${released.length}, refused ${refused.length}, nothing held ${nothing.length}${r.truncated ? " (more remain — run it again)" : ""}`;
+    const lines = [head];
+    for (const t of released) {
+        const actions = r.dryRun ? (t.releasable ?? []) : (t.released ?? []);
+        lines.push(`  ${r.dryRun ? "would release" : "released"} ${t.ticket ?? "?"}: ${actions.map(describeAction).join(", ")}`);
+    }
+    for (const t of refused) {
+        for (const x of t.refused ?? [])
+            lines.push(`  refused ${t.ticket ?? "?"} — ${x.code}: ${x.humanAction}`);
+    }
+    if (nothing.length > 0)
+        lines.push(`  nothing held: ${nothing.join(", ")}`);
+    return lines;
+}
+/** The contract's route by name, or the "your cloud is older" error when this tenant does not serve it. */
+function releaseRoute(doc, name, cfg) {
+    const route = doc.routes.find((r) => r.method === "POST" && r.path.split("/").filter(Boolean).at(-1) === name);
+    if (!route)
+        throw needsNewerCloud(`release (the tenant contract serves no "${name}" route)`, cfg);
+    return route.path;
+}
+export async function cmdRelease(args, ctx) {
+    const [ticket, ...extra] = positionals(args);
+    const failureClass = flagString(args, "class");
+    const team = flagString(args, "team");
+    const because = flagString(args, "because");
+    const dryRun = flagBool(args, "dry-run");
+    const retryUnchanged = flagBool(args, "retry-unchanged");
+    if (extra.length > 0)
+        throw new UsageError("release takes one ticket");
+    if (failureClass !== undefined && ticket !== undefined) {
+        throw new UsageError("release takes a ticket or --class with --team, not both");
+    }
+    if (failureClass === undefined && ticket === undefined) {
+        throw new UsageError("release needs a ticket, or --class <failure-class> --team <K>");
+    }
+    if (failureClass !== undefined && team === undefined)
+        throw new UsageError("release --class needs --team <K>");
+    if (because === undefined && !dryRun) {
+        throw new UsageError("release needs --because <what changed> (recorded in the release audit), or --dry-run to preview");
+    }
+    const limitRaw = flagString(args, "limit");
+    const limit = limitRaw === undefined ? undefined : Number(limitRaw);
+    if (limit !== undefined && !Number.isInteger(limit))
+        throw new UsageError("--limit must be an integer");
+    const cfg = requireConfig(ctx);
+    const { doc } = await loadContract(ctx, cfg);
+    const api = apiClient(cfg, ctx);
+    const common = { ...(because !== undefined ? { because } : {}), retryUnchanged, dryRun };
+    if (failureClass !== undefined) {
+        const path = releaseRoute(doc, "ticket-release-class", cfg);
+        const res = await api.postJson(path, {
+            team,
+            class: failureClass,
+            ...common,
+            ...(limit !== undefined ? { limit } : {}),
+        });
+        if (args.json)
+            ctx.stdout(JSON.stringify(res.body));
+        else
+            for (const line of renderClassRelease(res.body))
+                ctx.stdout(line);
+        // A real class release that refused any ticket exits 1, the same contract as a single refusal.
+        return res.body.dryRun !== true && (res.body.refused ?? []).length > 0 ? 1 : 0;
+    }
+    const id = ticket;
+    const path = releaseRoute(doc, "ticket-release", cfg);
+    const res = await api.postJson(path, { ticket: id, ...common }, { accept: [404, 409] });
+    if (res.status === 404) {
+        throw new CliError(`ticket ${id} is not in this tenant's mirror — check the identifier`, "ticket-unknown");
+    }
+    if (args.json)
+        ctx.stdout(JSON.stringify(res.body));
+    else
+        for (const line of renderTicketRelease(id, res.body))
+            ctx.stdout(line);
+    const refused = res.status === 409 || (res.body.outcome === "refused" && res.body.dryRun !== true);
+    return refused ? 1 : 0;
+}

package/dist/replica.js

@@ -10,8 +10,10 @@ import { flagBool, flagInt, flagString, positionals } from "./args.js";
 import { apiBase, loadConfig, replicaDbPath } from "./config.js";
 import { detachSelf } from "./detach.js";
 import { CliError, UsageError } from "./errors.js";
-import { apiClient } from "./http.js";
+import { apiClient } from "./transport.js";
+import { authStrategyFor } from "./oauth.js";
 import { loadSdk } from "./sdk.js";
+import { createEventSync } from "./events.js";
 export const DEFAULT_STALE_MS = 15_000;
 export function pidfilePath(dbPath) {
     return `${dbPath}.pid`;
@@ -204,7 +206,7 @@ async function cmdStart(args, ctx, cfg, dbPath, deps) {
         baseUrl: apiBase(cfg),
         account: cfg.account,
         accountSource: "declared",
-        auth: { kind: "token", token: cfg.key },
+        auth: authStrategyFor(ctx, cfg),
         dbPath,
         engine,
         fetchImpl: ctx.fetch,
@@ -213,7 +215,11 @@ async function cmdStart(args, ctx, cfg, dbPath, deps) {
         onStatus: (s) => ctx.stderr(`[replica] status=${s}`),
     });
     await replica.start();
-    ctx.stdout(`replica live at ${dbPath} (cursor ${replica.cursor ?? "none"}) — Ctrl-C to stop`);
+    const eventSync = await createEventSync(ctx, { loadSdk: deps.loadEventsSdk });
+    void eventSync.start().catch((error) => {
+        ctx.stderr(`[events] sync failed: ${error instanceof Error ? error.message : String(error)}; replica remains live`);
+    });
+    ctx.stdout(`replica live at ${dbPath} (cursor ${replica.cursor ?? "none"}); event cache active — Ctrl-C to stop`);
     const wait = deps.waitForStop ??
         (() => new Promise((resolve) => {
             const done = () => resolve();
@@ -221,6 +227,7 @@ async function cmdStart(args, ctx, cfg, dbPath, deps) {
             process.once("SIGTERM", done);
         }));
     await wait();
+    await eventSync.stop();
     await replica.close();
     try {
         if (readPidfile(dbPath) === process.pid)

package/dist/{http.js → transport.js}

@@ -1,16 +1,22 @@
 import { normalizeBaseUrl } from "./config.js";
 import { CliError, MeError } from "./errors.js";
+import { bearerFor } from "./oauth.js";
 export const REQUEST_TIMEOUT_MS = 15_000;
 export class ApiClient {
-    cfg;
+    baseUrl;
+    credential;
     fetchImpl;
-    constructor(cfg, fetchImpl) {
-        this.cfg = cfg;
+    constructor(baseUrl, 
+    /** Resolves the current bearer FRESH per request — a personal key verbatim, or the OAuth access
+     *  token refreshed within 60s of expiry (CTC-2112). Never captured once. */
+    credential, fetchImpl) {
+        this.baseUrl = baseUrl;
+        this.credential = credential;
         this.fetchImpl = fetchImpl;
     }
     /** `path` is absolute under the origin (e.g. `/api/v1/issues`). */
     url(path, query) {
-        const u = new URL(`${normalizeBaseUrl(this.cfg.baseUrl)}${path}`);
+        const u = new URL(`${normalizeBaseUrl(this.baseUrl)}${path}`);
         for (const [k, v] of Object.entries(query ?? {}))
             if (v !== undefined)
                 u.searchParams.set(k, String(v));
@@ -18,7 +24,7 @@ export class ApiClient {
     }
     async getJson(path, opts = {}) {
         const headers = {
-            authorization: `Bearer ${this.cfg.key}`,
+            authorization: `Bearer ${await this.credential()}`,
             accept: "application/json",
         };
         if (opts.etag)
@@ -44,7 +50,7 @@ export class ApiClient {
         const url = this.url(path, opts.query);
         const res = await this.send(url, {
             method: "GET",
-            headers: { authorization: `Bearer ${this.cfg.key}`, accept: "application/x-ndjson, application/json" },
+            headers: { authorization: `Bearer ${await this.credential()}`, accept: "application/x-ndjson, application/json" },
         });
         if (opts.accept?.includes(res.status))
             return { status: res.status, body: [], headers: res.headers };
@@ -64,18 +70,21 @@ export class ApiClient {
         }
         return { status: res.status, body: rows, headers: res.headers };
     }
-    async postJson(path, body) {
+    /** `opts.accept` lists non-2xx statuses returned to the caller with their JSON body instead of thrown
+     *  — the release route answers a refusal as 409 with the refusals the caller has to print. */
+    async postJson(path, body, opts = {}) {
         const url = this.url(path);
         const res = await this.send(url, {
             method: "POST",
             headers: {
-                authorization: `Bearer ${this.cfg.key}`,
+                authorization: `Bearer ${await this.credential()}`,
                 accept: "application/json",
                 "content-type": "application/json",
             },
             body: JSON.stringify(body),
         });
-        await this.refuseIfNotOk(res, `POST ${path}`);
+        if (!opts.accept?.includes(res.status))
+            await this.refuseIfNotOk(res, `POST ${path}`);
         return { status: res.status, body: await this.parseBody(res, `POST ${path}`), headers: res.headers };
     }
     async send(url, init) {
@@ -121,8 +130,10 @@ export class ApiClient {
         throw new CliError(`${what} failed (${res.status})${reason ? `: ${reason}` : ""}`, "http", 2, res.status);
     }
 }
+/** Build the authenticated client for a config: the bearer resolves through {@link bearerFor}, so a
+ *  key config sends the key and an OAuth config sends a freshly-refreshed access token per request. */
 export function apiClient(cfg, ctx) {
-    return new ApiClient(cfg, ctx.fetch);
+    return new ApiClient(cfg.baseUrl, () => bearerFor(ctx, cfg), ctx.fetch);
 }
 /** GET /api/v1/me — how a key learns its own tenant. Unchanged contract from 0.1. */
 export async function fetchMe(baseUrl, key, fetchImpl, timeoutMs = REQUEST_TIMEOUT_MS) {

package/dist/watch/consumer.js

@@ -11,7 +11,7 @@ export function printFrame(frame) {
 }
 async function fetchHeadCursor(opts, signal) {
     const url = `${opts.baseUrl.replace(/\/+$/, "")}/snapshot?head=1`;
-    const res = await (opts.fetchImpl ?? fetch)(url, { headers: { authorization: `Bearer ${opts.token}` }, signal });
+    const res = await (opts.fetchImpl ?? fetch)(url, { headers: { authorization: `Bearer ${await opts.getToken()}` }, signal });
     if (!res.ok) {
         const body = (await res.text()).slice(0, 200);
         throw new Error(`head-only snapshot fetch failed: ${res.status} ${res.statusText} at ${url} — ${body}`);
@@ -111,7 +111,7 @@ export function createLiveEventsClient(sdk, opts) {
     const client = new sdk.LiveSyncClient({
         baseUrl: opts.baseUrl,
         accountId: opts.accountId,
-        auth: { kind: "token", token: opts.token },
+        auth: opts.auth,
         reseed: reseedHead,
         getCursor: () => state?.cursor ?? null,
         onChange: (frame) => {

package/dist/watch.js

@@ -7,7 +7,8 @@ import { flagList, flagString } from "./args.js";
 import { apiBase, requireConfig, watchCursorPathFor } from "./config.js";
 import { loadContract } from "./contract.js";
 import { CliError, UsageError } from "./errors.js";
-import { apiClient } from "./http.js";
+import { apiClient } from "./transport.js";
+import { authStrategyFor, bearerFor } from "./oauth.js";
 import { loadSdk } from "./sdk.js";
 import { createLiveEventsClient } from "./watch/consumer.js";
 import { CursorFileError } from "./watch/cursor-file.js";
@@ -135,7 +136,8 @@ export async function runWatch(ctx, cfg, opts, deps = {}) {
         return createLiveEventsClient(sdk, {
             baseUrl: apiBase(cfg),
             accountId: cfg.account,
-            token: cfg.key,
+            auth: authStrategyFor(ctx, cfg),
+            getToken: () => bearerFor(ctx, cfg),
             cursorFile: opts.cursorFile ?? watchCursorPathFor(ctx.home),
             fromHead: opts.fromHead,
             fetchImpl: ctx.fetch,

package/dist/write.js

@@ -6,7 +6,7 @@ import { flagBool, flagInt, flagList, flagString, positionals } from "./args.js"
 import { requireConfig } from "./config.js";
 import { bookkeepingPrefix, labelId, loadContract, routePath, stageIdForSlot, teamByKey, teamForTicket } from "./contract.js";
 import { CliError, UsageError } from "./errors.js";
-import { apiClient } from "./http.js";
+import { apiClient } from "./transport.js";
 /** A ticket identifier → its Linear id (and team/project) through GET /api/v1/issues/:identifier. */
 export async function resolveIssue(api, ticket) {
     const res = await api.getJson(`/api/v1/issues/${encodeURIComponent(ticket)}`, { accept: [404] });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@catalyst-cloud/catalyst-skills",
-  "version": "0.3.1",
-  "description": "Customer skill bundle for Catalyst Cloud: 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) plus the catalyst-skills CLI that reads through the Catalyst Cloud SDK, writes through the agent proxy, and connects your machine to your tenant with one command.",
+  "version": "0.5.0",
+  "description": "Customer skill bundle for Catalyst Cloud: nine skills named from the executive's seat (whats-happening, what-needs-me, run-this-project, unstick, catalyst-setup, catalyst-linear, catalyst-github, how-catalyst-works, connect-me) plus the catalyst-skills CLI that reads through the Catalyst Cloud SDK, writes through the agent proxy, and connects your machine to your tenant with one command.",
   "license": "MIT",
   "type": "module",
   "publishConfig": {
@@ -38,10 +38,11 @@
     "prepare": "tsc -p tsconfig.build.json",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
-    "version:sync": "node scripts/sync-plugin-version.mjs"
+    "version:sync": "node scripts/sync-plugin-version.mjs",
+    "skill-lib:sync": "node scripts/sync-skill-lib.mjs"
   },
   "dependencies": {
-    "@catalyst-cloud/sdk": "^0.8.49"
+    "@catalyst-cloud/sdk": "^0.10.0"
   },
   "devDependencies": {
     "@types/node": "^26.3.0",

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

@@ -8,9 +8,10 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
 export const PACKAGE = "@catalyst-cloud/catalyst-skills";
-export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE} login`;
+export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: ${CONNECT_COMMAND}`;
 
 /** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME before HOME. */
 export function configPath() {
@@ -32,7 +33,7 @@ export function requireCustomerConfig() {
     console.error(`${path} could not be read (${err instanceof Error ? err.message : String(err)}) — ${CONNECT_HINT}`);
     process.exit(2);
   }
-  if (!cfg || typeof cfg !== "object" || typeof cfg.key !== "string" || typeof cfg.baseUrl !== "string") {
+  if (!hasCredential(cfg) || typeof cfg.baseUrl !== "string") {
     console.error(`${path} is missing required fields — ${CONNECT_HINT}`);
     process.exit(2);
   }

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

@@ -6,9 +6,10 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
 export const PACKAGE = "@catalyst-cloud/catalyst-skills";
-export const CONNECT_HINT = `CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE} login`;
+export const CONNECT_HINT = CONNECT_COMMAND;
 
 /** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME (used by tests) over HOME. */
 export function configPath() {
@@ -22,8 +23,8 @@ export function loadConfig() {
   if (!existsSync(path)) return { ok: false, reason: `no config at ${path}` };
   try {
     const cfg = JSON.parse(readFileSync(path, "utf8"));
-    if (!cfg || typeof cfg.key !== "string" || typeof cfg.account !== "string") {
-      return { ok: false, reason: `${path} is missing the key or account` };
+    if (!hasCredential(cfg) || typeof cfg.account !== "string") {
+      return { ok: false, reason: `${path} is missing a key or login, or the account` };
     }
     return { ok: true, cfg, path };
   } catch (err) {

package/skills/catalyst-linear/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/catalyst-setup/SKILL.md

@@ -26,7 +26,7 @@ You answer one question with one verdict and one list. The verdict is READY or N
 - Report, never repair. No tenant-reachable repair verb exists for a key yet; the settings page is where a tenant owner or admin fixes a mapping, a connection or a label, and you say which one.
 - End every answer with the verdict and the who-can-click-what list, in that order.
 - A stale or absent replica is a note, never a failure: every skill reads the API meanwhile and says so. Do not tell the person to start it unless they want local SQL or cheaper repeated reads.
-- Not connected (exit 2) means the connect step, not a retry: `CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login`, with the person's own key from Settings → API keys. Never guess a tenant; the key is the only selector.
+- Not connected (exit 2) means the connect step, not a retry: `npx @catalyst-cloud/catalyst-skills login`, which logs the person in keyless in their browser; with a personal key from Settings → API keys instead, prefix it with `CATALYST_CLOUD_TOKEN=<your personal key>`. Never guess a tenant; the login (or the key) is the only selector.
 - Waiting is not failing. "No write observed", "no delivery observed" and "no host connected" clear themselves the first time the thing happens; say that instead of raising them.
 - Unknown is not a pass. A check the engine could not run is reported as such, never rounded up.
 - Never run a check in a loop. If the person wants to know when a waiting check clears, that is the project-running skill's watch.

package/skills/catalyst-setup/references/what-each-check-means.md

@@ -37,7 +37,7 @@ Three checks are informational by design (labels, event delivery, host currency)
 | id | proves | fix |
 | -- | -- | -- |
 | `node` | Node 22 or newer, which the SDK's built-in SQLite engine needs | install Node 22+ |
-| `config` | this machine is connected: `customer.json` exists and loads | `CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login`; the person mints the key at Settings → API keys |
+| `config` | this machine is connected: `customer.json` exists and loads | `npx @catalyst-cloud/catalyst-skills login` (keyless: the person approves in their browser); or, with a personal key minted at Settings → API keys, the same command prefixed with `CATALYST_CLOUD_TOKEN=<your personal key>` |
 | `contract` | the tenant contract is cached and its major version is one this bundle accepts | `catalyst-skills contract --refresh`; a version outside the range means update the bundle. A 403 naming an older cloud means the cloud has not yet deployed personal-key access |
 | `cliPath` | the CLI path recorded at login still exists, so skill scripts can spawn it | re-run login |
 | `skills` | every skill of this bundle is present where the CLI installed them | `catalyst-skills install` |
@@ -60,3 +60,7 @@ Three checks are informational by design (labels, event delivery, host currency)
 ## Who can click what
 
 The last block `check.mjs` prints groups every failure by the person it needs. Machine fixes name "you", the person at the keyboard. Tenant fixes name the owner or admin roles the contract lists (as Linear user ids, since that is how the cloud knows them), because the settings page that repairs a mapping, a connection or a label is theirs. A check the contract marks as not needing an answer names nobody: it is informational or self-clearing. This skill reports; it never repairs, because no key-reachable repair verb exists yet.
+
+## Setting up one team at a time
+
+A team starts receiving work only once its stages are saved, and that is done one team at a time: a tenant owner or admin opens Settings → Linear teams, picks the team and presses Map my stages (or Adopt the Catalyst workflow). No other team's stages or tickets change; only the labels Adopt creates are shared across the workspace. Before saving, the screen lists which of that team's tickets would start and which stay where they are. Once saved, the tickets in the team's dispatch stage start; tickets in other stages that Catalyst never worked on stay where they are. To pilot safely, pick a low-stakes team, move anything in its dispatch stage that should not start back to Backlog, and leave the other teams unmapped. `gitAutomation` in the contract plays no part: nothing reads it.

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

@@ -8,9 +8,10 @@ import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { CONNECT_COMMAND, hasCredential } from "./credential.mjs";
 
 export const PACKAGE = "@catalyst-cloud/catalyst-skills";
-export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: CATALYST_CLOUD_TOKEN=<your personal key> npx ${PACKAGE} login`;
+export const CONNECT_HINT = `this machine is not connected to a tenant yet — run: ${CONNECT_COMMAND}`;
 
 /** ~/.config/catalyst-cloud/customer.json, honouring CATALYST_SKILLS_HOME before HOME. */
 export function configPath() {
@@ -32,7 +33,7 @@ export function requireCustomerConfig() {
     console.error(`${path} could not be read (${err instanceof Error ? err.message : String(err)}) — ${CONNECT_HINT}`);
     process.exit(2);
   }
-  if (!cfg || typeof cfg !== "object" || typeof cfg.key !== "string" || typeof cfg.baseUrl !== "string") {
+  if (!hasCredential(cfg) || typeof cfg.baseUrl !== "string") {
     console.error(`${path} is missing required fields — ${CONNECT_HINT}`);
     process.exit(2);
   }

package/skills/catalyst-setup/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/catalyst-setup/scripts/replica-status.mjs

@@ -14,7 +14,7 @@ const HELP = `Usage: node scripts/replica-status.mjs [--probe] [--json]
 Exit codes, passed through from catalyst-skills replica status:
   0  fresh: a live writer, a young heartbeat, a cursor — skills read the replica
   1  stale: the file exists but the writer is gone or behind — skills read the API and say so
-  2  not connected to a tenant — run: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login
+  2  not connected to a tenant — run: npx @catalyst-cloud/catalyst-skills login (or, with a personal key: CATALYST_CLOUD_TOKEN=<your personal key> npx @catalyst-cloud/catalyst-skills login)
   3  absent: no replica file — optional; start one with: catalyst-skills replica start --detach`;
 
 const args = process.argv.slice(2);

package/skills/connect-me/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: connect-me
 description: >-
-  Connect this machine to the person's Catalyst Cloud tenant with their own personal key, cache the tenant contract, and verify. Use when a person is getting started, when their config is missing or broken, when they rotated their key, when a skill script exits 2 saying the machine is not connected, or when they ask which tenant this machine belongs to. The key names the tenant and the person, so nobody types an account id. Installing the skills is not this skill's job; the agent's own install command did that.
+  Connect this machine to the person's Catalyst Cloud tenant as themselves — keyless (a browser device-code login) or with their own personal key — cache the tenant contract, and verify. Use when a person is getting started, when their config is missing or broken, when their login expired or they rotated their key, when a skill script exits 2 saying the machine is not connected, or when they ask which tenant this machine belongs to. The login names the tenant and the person, so nobody types an account id. Installing the skills is not this skill's job; the agent's own install command did that.
 disable-model-invocation: true
 allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:*)
 ---
@@ -9,28 +9,36 @@ allowed-tools: Bash(catalyst-skills:*) Bash(npx @catalyst-cloud/catalyst-skills:
 
 # Connect me
 
-Connecting is one command. It asks the cloud who the key belongs to — which tenant, and which person — writes the config every skill and the CLI read, and caches the tenant contract beside it.
+Connecting is one command. Keyless is the preferred rail — with no key, `login` opens a browser device-code flow and logs the person in as themselves:
+
+```sh
+catalyst-skills login
+```
+
+It prints a short code and a URL; the person approves in a browser (or from a phone, on a machine with no browser) and this machine is connected as them. The short-lived session refreshes silently on every request, so they stay connected for months.
+
+A **personal key** still works for a script or an unattended shell — the environment form keeps it out of shell history; `--key <personal-key>` is the third form:
 
 ```sh
 CATALYST_CLOUD_TOKEN=<your-personal-key> catalyst-skills login
 ```
 
-With no environment variable and a terminal attached, `catalyst-skills login` prompts for the key without echoing it. `--key <personal-key>` is the third form, for a script. `npx @catalyst-cloud/catalyst-skills login` works when the package is not installed globally. A non-default cloud is pinned with `CATALYST_CLOUD_BASE_URL` or `--base-url`.
+`npx @catalyst-cloud/catalyst-skills login` works when the package is not installed globally. A non-default cloud is pinned with `CATALYST_CLOUD_BASE_URL` or `--base-url`.
 
 **This skill never installs skills.** You are already reading one, so the person's agent installed the set with its own command. Connecting is only about the credential and the contract.
 
-**What it writes.** `~/.config/catalyst-cloud/customer.json` (mode 0600) holding the key, the tenant it resolved, the person it resolved (`user`: id, label, role, Linear user id), and the absolute path of this CLI so skill scripts can spawn it; `~/.config/catalyst-cloud/contract.json`, the tenant contract with its ETag.
+**What it writes.** `~/.config/catalyst-cloud/customer.json` (mode 0600) holding the credential — a keyless login session (`auth`), or a personal key — the tenant it resolved, the person it resolved (`user`: id, label, role, Linear user id), and the absolute path of this CLI so skill scripts can spawn it; `~/.config/catalyst-cloud/contract.json`, the tenant contract with its ETag. A keyless session's token rotates on its own and the file is rewritten atomically each time.
 
 **The replica is optional and one command away.** Nothing has to be running for reads, writes, asks or explanations; the API is origin-fresh. `catalyst-skills replica start --detach` starts the local replica for cheap repeated reads and ad hoc SQL; `login --start-replica` does the same at the end. Every skill checks `catalyst-skills replica status` first and falls back to the API when the replica is absent or stale, saying so.
 
 ## What you do
 
-1. Ask the person to mint their **personal key** at Settings → API keys in the Catalyst Cloud web app (every active member can; no admin is needed) and hand it to the login command. It is shown once. Never put it in a file, a ticket, or this conversation beyond that one command. Do not ask an admin for the tenant's **account key** (`ctc_acct_`, Settings → Account keys): that is a host credential — runners, daemons, the host replica — and a person connected with it has no name on anything their agent writes, and "what needs me" cannot mean them. If they connect with one anyway, login says so on stderr and still works.
+1. Prefer keyless: run `catalyst-skills login` with no key and have the person approve the code in their browser (or from a phone). Nothing to mint, nothing to paste, nothing to keep out of the transcript. A **personal key** is the fallback for a script or unattended shell — they mint it at Settings → API keys (every active member can; no admin is needed) and hand it to the login command via `CATALYST_CLOUD_TOKEN`; it is shown once, so never put it in a file, a ticket, or this conversation beyond that one command. Either way, do not ask an admin for the tenant's **account key** (`ctc_acct_`, Settings → Account keys): that is a host credential — runners, daemons, the host replica — and a person connected with it has no name on anything their agent writes, and "what needs me" cannot mean them. If they connect with one anyway, login says so on stderr and still works.
 2. Run the login command. Its output names the tenant (`Connected to <name> (<slug>)`), the person (`Connected as <label> (<role>)`), the config path, and the cached contract version. If the person line says their Linear identity is not matched yet, tell them: an admin matches it in Settings → Members, and until then "what needs me" shows everyone's asks.
 3. Verify with `node scripts/verify-connection.mjs`: one line each for the tenant, the contract version, and the replica; exit 1 when the machine is not connected.
 4. Run `catalyst-skills ready` and read the verdict to them.
 5. Offer the replica: `catalyst-skills replica start --detach`, then `catalyst-skills replica status`. For keeping it alive across a reboot, load `references/keeping-the-replica-running.md`.
-6. If login fails: a `401` means a stale, mistyped or revoked key — mint a new one at Settings → API keys, never a retry loop; a network error names the URL, check `--base-url`. A `403` on the contract naming an older cloud means the cloud has not yet deployed personal-key access: update the cloud, or connect with the account key until it has. If login succeeds but prints a line naming two contract versions, the tenant serves a contract outside this bundle's range: update the bundle before using the other skills.
+6. If login fails: a keyless session that reports "your login expired or was revoked" needs one fresh `catalyst-skills login`, never a retry loop (it means the session was revoked or lapsed past the inactivity window — routine expiry refreshes silently and never surfaces). A `401` on the key rail means a stale, mistyped or revoked key — mint a new one at Settings → API keys, never a retry loop; a network error names the URL, check `--base-url`. A `403` on the contract naming an older cloud means the cloud has not yet deployed personal-key access: update the cloud, or connect with the account key until it has. If login succeeds but prints a line naming two contract versions, the tenant serves a contract outside this bundle's range: update the bundle before using the other skills.
 
 ## The verbs a session runs first
 
@@ -50,6 +58,6 @@ Every skill session opens with these, in this order, before doing anything else:
 
 ## Rules
 
-- **The key is a credential.** It goes into the login command or `CATALYST_CLOUD_TOKEN` and nowhere else: not into tickets, transcripts, or any file you write besides the one login writes.
-- **Never guess a tenant.** There is no `--account`; the key is the only tenant selector, on purpose. If the cloud names no tenant for the key, stop and say so.
+- **The credential is a secret.** Keyless is safest — nothing to handle. A key goes into the login command or `CATALYST_CLOUD_TOKEN` and nowhere else: not into tickets, transcripts, or any file you write besides the one login writes; and never read back the `auth` block a keyless session stores.
+- **Never guess a tenant.** There is no `--account`; the credential is the only tenant selector, on purpose. If the cloud names no tenant for the login, stop and say so.
 - **Read the update notice.** After a bundle update, the next command prints one line with the changelog entry and what to run; read it to the person if they are watching.