@catalyst-cloud/catalyst-skills 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+First published customer skill bundle: vendored customer editions of concierge, steward, ask and linearis plus the new join and setup skills, one-command tenant discovery via GET /api/v1/me, config written to ~/.config/catalyst-cloud/customer.json, and a placeholder 0.x tenant contract range (CTC-1924 in flight).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Coalesce Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @catalyst-cloud/catalyst-skills
+
+The customer skill bundle for **catalyst-cloud**: install the concierge, steward, ask, linearis, join and setup skills from npm and join your tenant in one documented step. Customer zero needs no Coalesce Labs repository — everything the customer touches is this package and their tenant's cloud.
+
+## Requirements
+
+| piece | minimum |
+| -- | -- |
+| Claude Code | 2.0 (skills are discovered from `~/.claude/skills`) |
+| Node | 18.17 (20+ recommended; ships the `npx` used below) |
+| Bun | 1.0 — optional, only if you prefer `bunx` over `npx` |
+
+You also need an **account key** from your tenant admin. The key is the only credential and the only tenant selector — you never type a tenant or account id.
+
+## Install and join — one step
+
+```sh
+npx @catalyst-cloud/catalyst-skills join --key <your-account-key>
+```
+
+That single command does everything:
+
+1. **Installs the skills** where Claude Code discovers them (`~/.claude/skills/`): `concierge`, `steward`, `ask`, `linearis`, `join`, `setup`.
+2. **Discovers your tenant from the key** — it calls `GET /api/v1/me` on the cloud, which answers `{account, slug, name, permissions, principal}` for exactly whoever the key already proves you to be. No tenant is ever typed, guessed, or defaulted.
+3. **Writes config** to `~/.config/catalyst-cloud/customer.json` (mode `0600` — it holds your key; nothing else ever reads or copies it).
+4. Prints the tenant it joined (`Joined <name> (<slug>)`), so you can see you landed in the right place.
+
+Open a new Claude Code session and just talk to the concierge — it answers about **your own tenant**, reading it with the config the join wrote.
+
+### Plain global-install form
+
+```sh
+npm install -g @catalyst-cloud/catalyst-skills
+catalyst-skills join --key <your-account-key>
+```
+
+`bunx @catalyst-cloud/catalyst-skills join --key …` works identically. The key may also be provided via `CATALYST_CLOUD_TOKEN`; a non-default cloud via `CATALYST_CLOUD_BASE_URL` or `--base-url`. Re-running join after a key rotation rewrites the config; `catalyst-skills status` shows which tenant this machine belongs to.
+
+### If join fails
+
+- `401 credential not accepted` — stale or mistyped key; ask your tenant admin. Never retry in a loop.
+- `403 account-not-operational` — the tenant is suspended; an admin conversation, not a local fix.
+- Network error — the URL is named in the message; check `--base-url`.
+
+## What comes from where
+
+This package is **self-contained: nothing in it is a hard dependency on any Coalesce Labs repository**, and you never need to read one to find a second step.
+
+- **`concierge`, `steward`, `ask`, `linearis`** are vendored, customer-adapted editions of skills that originate in the **catalyst repository's `catalyst-dev` Claude Code plugin** (`coalesce-labs/catalyst`, `plugins/dev/skills/…`). That repository is private and its plugin marketplace (`/plugin marketplace add coalesce-labs/catalyst`) is **not installable by customers today**, so the bundle vendors the four skills at publish time instead of depending on the marketplace. Each vendored `SKILL.md` carries a `vendored-from:` provenance line. Upstream, CTL-2299 and CTL-2300 are removing the fleet-owner defaults from those skills; until they land, this package's copies carry the customer adaptation.
+- **`join` and `setup`** are written here, against the public cloud API surface (`GET /api/v1/me`).
+
+## Version contract
+
+This package is versioned against the **tenant contract** route. That route is still in flight (CTC-1924), so until it lands the package pins a **placeholder contract range `0.x`** — recorded in `package.json` under `catalystCloud.tenantContractRange` and echoed by `catalyst-skills --version` and `join`. When CTC-1924 lands, the placeholder is replaced with the real range and a mismatch becomes a loud, actionable error rather than a silent guess.
+
+## Updates (one-line notice)
+
+After you update the package (`npm update -g @catalyst-cloud/catalyst-skills`, or just run any `npx @catalyst-cloud/catalyst-skills@latest …` command), the **next session** — the next `catalyst-skills` command or skill that runs — prints exactly one line:
+
+```
+[catalyst-skills] updated 0.1.0 → 0.2.0: <that version's changelog entry> · update with: npm update -g @catalyst-cloud/catalyst-skills (or: npx @catalyst-cloud/catalyst-skills@latest join)
+```
+
+and never prints it again for that version. `catalyst-skills notice` is the skill-facing entry point for that line.
+
+The same run also **refreshes the copied skills** under your skills directory (the one `join` recorded in `customer.json`, `~/.claude/skills` by default) to the new bundle before the new version is recorded — `npm update -g` replaces the package, not the copies `join` made, so without this step a published skill fix would never reach an existing install. A skill directory you wrote yourself is left alone and named in the output (`catalyst-skills install --force` replaces it). If the refresh fails, the old version stays recorded and the next command tries again, telling you to run `catalyst-skills install`.
+
+## For the package maintainers
+
+Published **only** by the `skills-bundle publish` GitHub Actions workflow on a `skills-bundle-v*` tag — never from a laptop. The workflow runs this package's smoke test (pack the tarball, install it into a clean directory, run `join` against a fixture `/me` server) before `npm publish`, so a broken publish cannot ship. The npm credential is the repository secret **`NPM_PUBLISH_TOKEN`** — an automation-token grant on the `@catalyst-cloud` scope.

package/bin/catalyst-skills.js

@@ -0,0 +1,10 @@
+#!/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.
+import("../dist/cli.js")
+  .then((m) => m.main(process.argv.slice(2)))
+  .then((code) => process.exit(code))
+  .catch((err) => {
+    console.error(`catalyst-skills: failed to load: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  });

package/dist/cli.js

@@ -0,0 +1,424 @@
+// cli.ts — CTC-1926: the `catalyst-skills` customer installer/joiner (npm: @catalyst-cloud/catalyst-skills).
+import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const PACKAGE_NAME = "@catalyst-cloud/catalyst-skills";
+export const DEFAULT_BASE_URL = "https://staging.catalystcloud.dev";
+export const PROVENANCE_MARKER = "vendored-from: @catalyst-cloud/catalyst-skills";
+export const CUSTOMER_SKILLS = [
+    "ask",
+    "concierge",
+    "join",
+    "linearis",
+    "setup",
+    "steward",
+];
+export class UsageError extends Error {
+}
+export class CliError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+    }
+}
+export class MeError extends Error {
+    kind;
+    status;
+    constructor(message, kind, status) {
+        super(message);
+        this.kind = kind;
+        this.status = status;
+    }
+}
+export function parseArgs(argv) {
+    const out = { command: null, force: false, help: false, version: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "-h" || a === "--help")
+            out.help = true;
+        else if (a === "-V" || a === "--version")
+            out.version = true;
+        else if (a === "--key")
+            out.key = requireValue(argv, ++i, "--key");
+        else if (a === "--base-url")
+            out.baseUrl = requireValue(argv, ++i, "--base-url");
+        else if (a === "--skills-dir")
+            out.skillsDir = requireValue(argv, ++i, "--skills-dir");
+        else if (a === "--force")
+            out.force = true;
+        else if (a.startsWith("--"))
+            throw new UsageError(`unknown option: ${a}`);
+        else if (out.command === null)
+            out.command = a;
+        else
+            throw new UsageError(`unexpected argument: ${a}`);
+    }
+    return out;
+}
+function requireValue(argv, i, flag) {
+    const v = argv[i];
+    if (v === undefined || v === "")
+        throw new UsageError(`${flag} requires a value`);
+    return v;
+}
+let manifestCache = null;
+export function readManifest() {
+    if (manifestCache)
+        return manifestCache;
+    const raw = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    manifestCache = {
+        version: raw.version,
+        tenantContractRange: raw.catalystCloud?.tenantContractRange ?? "unpinned",
+    };
+    return manifestCache;
+}
+export function configPathFor(home) {
+    return join(home, ".config", "catalyst-cloud", "customer.json");
+}
+export function defaultSkillsDirFor(home) {
+    return join(home, ".claude", "skills");
+}
+export function loadConfig(home) {
+    const path = configPathFor(home);
+    if (!existsSync(path))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new CliError(`config at ${path} is not valid JSON — re-run join to rewrite it`, "config-corrupt");
+    }
+    const cfg = parsed;
+    if (typeof cfg.account !== "string" ||
+        typeof cfg.key !== "string" ||
+        typeof cfg.baseUrl !== "string") {
+        throw new CliError(`config at ${path} is missing required fields — re-run join to rewrite it`, "config-corrupt");
+    }
+    return cfg;
+}
+export const CONFIG_MODE = 0o600;
+/**
+ * Write the config and return its path plus the mode the file ACTUALLY carries afterwards.
+ *
+ * Codex round 1 (P1): Node honours `mode` only when it creates the file, so a rewrite of an existing
+ * `customer.json` (key rotation, the corrupt-config repair, the update stamp) left a pre-existing
+ * 0644 file world-readable while the CLI claimed 0600. The chmod runs on every write, and the
+ * reported mode is read back from the file rather than asserted.
+ */
+export function saveConfig(home, cfg) {
+    return writeConfig(home, cfg).path;
+}
+export function writeConfig(home, cfg) {
+    const path = configPathFor(home);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(cfg, null, 2) + "\n", { mode: CONFIG_MODE });
+    chmodSync(path, CONFIG_MODE);
+    return { path, mode: statSync(path).mode & 0o777 };
+}
+export function formatMode(mode) {
+    return "0" + mode.toString(8);
+}
+export function normalizeBaseUrl(url) {
+    return url.replace(/\/+$/, "");
+}
+export async function fetchMe(baseUrl, key, fetchImpl, timeoutMs = 15_000) {
+    const url = `${normalizeBaseUrl(baseUrl)}/api/v1/me`;
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            headers: { authorization: `Bearer ${key}`, accept: "application/json" },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (err) {
+        throw new MeError(`could not reach ${url}: ${err instanceof Error ? err.message : String(err)}`, "network");
+    }
+    if (!res.ok) {
+        let reason;
+        try {
+            const body = (await res.json());
+            reason = body.reason ?? body.error ?? "";
+        }
+        catch {
+            reason = "";
+        }
+        const detail = res.status === 401
+            ? "credential not accepted — ask your tenant admin for a valid account key"
+            : reason || `HTTP ${res.status}`;
+        throw new MeError(`GET /me failed (${res.status}): ${detail}`, "http", res.status);
+    }
+    let body;
+    try {
+        body = (await res.json());
+    }
+    catch {
+        throw new MeError("GET /me returned a non-JSON body", "shape");
+    }
+    if (typeof body.account !== "string" ||
+        typeof body.slug !== "string" ||
+        typeof body.name !== "string" ||
+        (body.permissions !== null && !Array.isArray(body.permissions)) ||
+        (body.principal !== "service" && body.principal !== "session")) {
+        throw new MeError("GET /me returned an unexpected shape", "shape");
+    }
+    return {
+        account: body.account,
+        slug: body.slug,
+        name: body.name,
+        permissions: body.permissions,
+        principal: body.principal,
+    };
+}
+export function parseChangelogEntry(changelog, version) {
+    const lines = changelog.split("\n");
+    const heading = `## ${version}`;
+    const start = lines.findIndex((l) => l.trim() === heading);
+    if (start === -1)
+        return null;
+    for (const line of lines.slice(start + 1)) {
+        const t = line.trim();
+        if (t === "")
+            continue;
+        if (t.startsWith("#"))
+            break;
+        return t;
+    }
+    return null;
+}
+export function readChangelog() {
+    return readFileSync(new URL("../CHANGELOG.md", import.meta.url), "utf8");
+}
+export function updateNoticeLine(previous, current, entry) {
+    const summary = entry ?? "see CHANGELOG.md";
+    return `[catalyst-skills] updated ${previous} → ${current}: ${summary} · update with: npm update -g ${PACKAGE_NAME} (or: npx ${PACKAGE_NAME}@latest join)`;
+}
+export function skillsSourceDir() {
+    return fileURLToPath(new URL("../skills", import.meta.url));
+}
+export function installSkills(targetDir, opts, sourceDir = skillsSourceDir()) {
+    const result = { installed: [], skipped: [] };
+    const names = readdirSync(sourceDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => e.name)
+        .sort();
+    for (const name of names) {
+        const src = join(sourceDir, name);
+        if (!existsSync(join(src, "SKILL.md")))
+            continue;
+        const dst = join(targetDir, name);
+        const existingMd = join(dst, "SKILL.md");
+        if (existsSync(existingMd) && !opts.force) {
+            const existing = readFileSync(existingMd, "utf8");
+            if (!existing.includes(PROVENANCE_MARKER)) {
+                result.skipped.push({ name, reason: "foreign-skill-dir" });
+                continue;
+            }
+        }
+        mkdirSync(dst, { recursive: true });
+        cpSync(src, dst, { recursive: true });
+        result.installed.push(name);
+    }
+    return result;
+}
+export function usageText() {
+    return [
+        `${PACKAGE_NAME} — install the customer skill bundle and join your catalyst-cloud tenant`,
+        "",
+        "Usage:",
+        "  catalyst-skills join --key <account-key> [--base-url <url>] [--skills-dir <dir>]",
+        "  catalyst-skills install [--skills-dir <dir>] [--force]",
+        "  catalyst-skills notice",
+        "  catalyst-skills status",
+        "",
+        "The key may also come from CATALYST_CLOUD_TOKEN; the base URL defaults to",
+        `CATALYST_CLOUD_BASE_URL or ${DEFAULT_BASE_URL}.`,
+        "",
+        "join installs the skills (default ~/.claude/skills), calls GET /api/v1/me to discover",
+        "your tenant from the key alone, and writes ~/.config/catalyst-cloud/customer.json (0600).",
+    ].join("\n");
+}
+export function defaultCtx() {
+    return {
+        env: process.env,
+        home: process.env.CATALYST_SKILLS_HOME ?? process.env.HOME ?? "/",
+        stdout: (line) => console.log(line),
+        stderr: (line) => console.error(line),
+        fetch: fetch,
+        now: () => new Date(),
+    };
+}
+export function resolveSkillsDir(args, ctx, cfg) {
+    return (args.skillsDir ??
+        ctx.env.CATALYST_SKILLS_CLAUDE_DIR ??
+        cfg?.skillsDir ??
+        defaultSkillsDirFor(ctx.home));
+}
+/**
+ * The Tier-2 update path. When the bundle on disk is newer than the version the config last
+ * recorded, the copies under the skills dir are still the OLD bundle's — `npm update -g` and a newer
+ * `npx` replace the package, not the copies join made (Codex round 1, P2). So the copies are
+ * refreshed FIRST and the new version is recorded only once that succeeded; a failed refresh leaves
+ * the old stamp in place so the next command tries again instead of silencing the notice forever.
+ */
+function maybePrintUpdateNotice(args, ctx) {
+    let cfg;
+    try {
+        cfg = loadConfig(ctx.home);
+    }
+    catch {
+        return;
+    }
+    if (!cfg)
+        return;
+    const manifest = readManifest();
+    if (cfg.lastSkillBundleVersion === manifest.version)
+        return;
+    const previous = cfg.lastSkillBundleVersion;
+    if (previous) {
+        const entry = parseChangelogEntry(readChangelog(), manifest.version);
+        ctx.stdout(updateNoticeLine(previous, manifest.version, entry));
+    }
+    const skillsDir = resolveSkillsDir(args, ctx, cfg);
+    let refreshed;
+    try {
+        refreshed = installSkills(skillsDir, { force: false });
+    }
+    catch (err) {
+        ctx.stderr(`[catalyst-skills] could not refresh the skills at ${skillsDir} (${err instanceof Error ? err.message : String(err)}) — the ${manifest.version} skills are not installed yet; run: catalyst-skills install`);
+        return;
+    }
+    if (refreshed.installed.length > 0) {
+        ctx.stdout(`[catalyst-skills] refreshed ${refreshed.installed.join(", ")} at ${skillsDir} to ${manifest.version}`);
+    }
+    for (const s of refreshed.skipped) {
+        ctx.stdout(`[catalyst-skills] left "${s.name}" alone: ${skillsDir}/${s.name} was not installed by this package (catalyst-skills install --force to replace)`);
+    }
+    cfg.lastSkillBundleVersion = manifest.version;
+    cfg.skillsDir = skillsDir;
+    saveConfig(ctx.home, cfg);
+}
+export async function main(argv, ctx = defaultCtx()) {
+    let args;
+    try {
+        args = parseArgs(argv);
+    }
+    catch (err) {
+        ctx.stderr(err instanceof Error ? err.message : String(err));
+        ctx.stderr(usageText());
+        return 1;
+    }
+    const manifest = readManifest();
+    if (args.version) {
+        ctx.stdout(`${PACKAGE_NAME} ${manifest.version} (tenant contract range: ${manifest.tenantContractRange})`);
+        return 0;
+    }
+    if (args.help || args.command === null) {
+        ctx.stdout(usageText());
+        return 0;
+    }
+    try {
+        maybePrintUpdateNotice(args, ctx);
+        switch (args.command) {
+            case "join":
+                return await cmdJoin(args, ctx, manifest);
+            case "install":
+                return cmdInstall(args, ctx);
+            case "notice":
+                return 0;
+            case "status":
+                return cmdStatus(ctx, manifest);
+            default:
+                ctx.stderr(`unknown command: ${args.command}`);
+                ctx.stderr(usageText());
+                return 1;
+        }
+    }
+    catch (err) {
+        if (err instanceof UsageError) {
+            ctx.stderr(err.message);
+            ctx.stderr(usageText());
+            return 1;
+        }
+        if (err instanceof MeError || err instanceof CliError) {
+            ctx.stderr(`catalyst-skills: ${err.message}`);
+            return 2;
+        }
+        throw err;
+    }
+}
+async function cmdJoin(args, ctx, manifest) {
+    const key = (args.key ?? ctx.env.CATALYST_CLOUD_TOKEN ?? "").trim();
+    if (!key) {
+        throw new UsageError("join needs an account key: pass --key <account-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;
+    try {
+        existing = loadConfig(ctx.home);
+    }
+    catch {
+        existing = null;
+    }
+    const previous = existing?.lastSkillBundleVersion ?? null;
+    const skillsDir = resolveSkillsDir(args, ctx, existing);
+    const result = installSkills(skillsDir, { force: args.force });
+    const config = {
+        baseUrl,
+        key,
+        account: me.account,
+        slug: me.slug,
+        name: me.name,
+        permissions: me.permissions,
+        principal: me.principal,
+        joinedAt: ctx.now().toISOString(),
+        lastSkillBundleVersion: manifest.version,
+        skillsDir,
+    };
+    const written = writeConfig(ctx.home, config);
+    ctx.stdout(`Joined ${me.name} (${me.slug}) — account ${me.account}`);
+    ctx.stdout(`Config written to ${written.path} (mode ${formatMode(written.mode)}, holds your key)${written.mode === CONFIG_MODE ? "" : ` — expected ${formatMode(CONFIG_MODE)}; chmod it by hand`}`);
+    ctx.stdout(result.installed.length > 0
+        ? `Skills installed to ${skillsDir}: ${result.installed.join(", ")}`
+        : `No skills installed — ${skillsDir} already had them`);
+    for (const s of result.skipped) {
+        ctx.stdout(`Skipped "${s.name}": ${skillsDir}/${s.name} exists and was not installed by this package (use --force to replace)`);
+    }
+    ctx.stdout(`Tenant contract range: ${manifest.tenantContractRange} (placeholder until the tenant contract route lands — CTC-1924)`);
+    if (previous && previous !== manifest.version) {
+        const entry = parseChangelogEntry(readChangelog(), manifest.version);
+        ctx.stdout(updateNoticeLine(previous, manifest.version, entry));
+    }
+    return 0;
+}
+function cmdInstall(args, ctx) {
+    let cfg;
+    try {
+        cfg = loadConfig(ctx.home);
+    }
+    catch {
+        cfg = null;
+    }
+    const skillsDir = resolveSkillsDir(args, ctx, cfg);
+    const result = installSkills(skillsDir, { force: args.force });
+    ctx.stdout(result.installed.length > 0
+        ? `Skills installed to ${skillsDir}: ${result.installed.join(", ")}`
+        : `No skills installed — ${skillsDir} already had them`);
+    for (const s of result.skipped) {
+        ctx.stdout(`Skipped "${s.name}": ${skillsDir}/${s.name} exists and was not installed by this package (use --force to replace)`);
+    }
+    return 0;
+}
+function cmdStatus(ctx, manifest) {
+    const cfg = loadConfig(ctx.home);
+    if (!cfg) {
+        ctx.stdout(`Not joined yet — run: npx ${PACKAGE_NAME} join --key <your account key>`);
+        return 0;
+    }
+    ctx.stdout(`Tenant: ${cfg.name} (${cfg.slug}) — account ${cfg.account}`);
+    ctx.stdout(`API: ${cfg.baseUrl} (principal: ${cfg.principal})`);
+    ctx.stdout(`Bundle: ${PACKAGE_NAME} ${manifest.version} (tenant contract range: ${manifest.tenantContractRange})`);
+    return 0;
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@catalyst-cloud/catalyst-skills",
+  "version": "0.1.0",
+  "description": "Customer skill bundle for catalyst-cloud: install the concierge, steward, ask, linearis, join and setup skills from npm and join your tenant with one command. No catalyst repository checkout required.",
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "bin": {
+    "catalyst-skills": "bin/catalyst-skills.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "catalystCloud": {
+    "tenantContractRange": "0.x"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage && bun ../../scripts/coverage-per-file.ts"
+  },
+  "devDependencies": {
+    "@catalyst-cloud/typescript-config": "workspace:*",
+    "@types/node": "^26.3.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.11"
+  }
+}

package/skills/ask/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: ask
+description:
+  Record a decision request to the human on the customer's catalyst-cloud tenant. Use when active work is gated on a decision only the human can make — a product/priority/approval call or an action only they can take. The ask carries the question, concrete options, a default that fires if they are silent, and what it blocks. Never use for brainstorming or questions the human asked first.
+---
+
+<!-- vendored-from: @catalyst-cloud/catalyst-skills — adapted from the catalyst repository's catalyst-dev plugin (plugins/dev/skills/ask) for customer tenants -->
+
+# Ask — one decision, one record
+
+An ask is a decision request with a deadline-shaped default. It exists so that a question the human must answer is **one record they can find**, not a TODO line, a chat message, or a hope.
+
+## Shape of an ask
+
+An ask always carries, verbatim:
+
+1. **The question** — one sentence, as its title.
+2. **Options** — the realistic choices, each one line.
+3. **Default if silent** — what proceeds, and after how long. The default must be sane enough to actually run.
+4. **Blocks** — what work is held until it is answered, named by ticket or scope.
+
+## Where an ask lives
+
+An ask is a **ticket in the tenant's own Linear**, labelled `catalyst-ask`, written through the same Linear write access the `linearis` skill uses (the customer's own Linear tooling and credential — never a credential you improvised). The tenant's mirror recognises that label and holds the ticket out of the dispatchable pool, so a question is never mistaken for work. Cite the ask's identifier only after the create call returned it.
+
+## Rules
+
+- **File the ask BEFORE proceeding on the default.** Work may continue on the default only after the ask ticket exists; it may never run gated on an unasked question, and it may never run on a default that has no ticket behind it.
+- **One ask per decision.** Search for an existing ask first (`/api/v1/search?q=<terms>` through the `linearis` skill) — a duplicate splits one decision's urgency across two records.
+- **The human answers in the ask**, and when the answer arrives elsewhere (chat), post it back to the ask so question, options, default, answer, and who answered are one record.
+- **Never answer another role's ask**, and never answer as the human.
+- **Not everything is an ask.** Brainstorming, design back-and-forth, and questions the human asked first need no ticket. Operational retries, provider outages, and anything another agent can decide are never asks.
+- **Rank by blast radius**, not age: an ask that blocks a whole project outranks one that blocks a chore.
+
+## When no ticket can be filed
+
+If the tenant has no Linear write access wired up (the `linearis` skill reports none), the ask **cannot be filed, so the default does not fire**. Stop the gated work, and say so in your reply to the human with all four fields spelled out and the one action that unblocks everything: wire the Linear write path (or file the ask ticket by hand and tell you its identifier). Do not record the ask in a status summary, a TODO, or a handoff as a substitute — those are pointers to an ask, never the ask — and do not proceed on the default while no ticket exists.

package/skills/concierge/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: concierge
+description:
+  The one agent a human talks to on their own catalyst-cloud tenant. Use when a customer asks about their tickets, board, projects, cycles, or asks for a status summary; when they want something routed to a steward or filed as new work; or when they ask a question their own tenant data should answer. Reads only their tenant, via the config written by `catalyst-skills join`.
+---
+
+<!-- vendored-from: @catalyst-cloud/catalyst-skills — adapted from the catalyst repository's catalyst-dev plugin (plugins/dev/skills/concierge) for customer tenants -->
+
+# Concierge — one door for your tenant
+
+You are the customer's single desk for their catalyst-cloud tenant. Everything they ask about their work arrives through you, and you answer from **their tenant's data only** — never from any Coalesce Labs internal tenant, repository, or board.
+
+## First, know the tenant
+
+Read `~/.config/catalyst-cloud/customer.json` (written by `catalyst-skills join`). It holds `baseUrl`, `key`, `account`, `slug`, `name`, and `permissions`. Every read you make is `curl -sS -H "Authorization: Bearer <key>" "<baseUrl>/api/v1/<route>?account=<account>"`. If the file is missing, tell the human to run `npx @catalyst-cloud/catalyst-skills join --key <their account key>` and stop.
+
+Real read routes on the tenant: `/api/v1/issues`, `/api/v1/issues/<id>`, `/api/v1/search?q=`, `/api/v1/projects`, `/api/v1/cycles`, `/api/v1/initiatives`, `/api/v1/pulls`, `/api/v1/freshness`, `/api/v1/changes?since=`, and `/api/v1/me` (who the key belongs to). `/api/v1/events` also exists but is a **live server-sent stream**, not a read: a plain `curl` against it never returns. Do not invent routes; if a route 404s, say so plainly.
+
+## What changed recently — a bounded read, never the stream
+
+"What changed since this morning?" is answered from the mirror's change log, in **one bounded request**:
+
+1. `GET /api/v1/freshness?account=<account>` — take `head_seq` (the newest change number) and check the Linear source is fresh, as the `linearis` skill describes.
+2. `GET /api/v1/changes?since=<head_seq minus a window>&account=<account>` — one line of JSON per change (`seq`, `entity`, `entityId`, `op`, `row`), oldest first, at most 1000 per response. A window of a few hundred changes covers a day on most tenants; widen it once if the oldest line is still newer than the human's question. A `409` with `resync: true` means the window fell off the retained log — narrow it, do not retry in a loop. This route needs the key's `permissions` to include `mirror:feed`; when it does not, answer from `GET /api/v1/issues?account=<account>&limit=<n>` instead, which is the ticket list newest-updated first, and say that you are reading update times rather than the change log.
+
+Never open `/api/v1/events` for this: without `since` it starts at the current head and emits only what happens next, and it stays open until the connection drops.
+
+## What you do
+
+- **Answer questions about their own tenant**: what is in flight, what is blocked, what changed recently (the bounded read above), what a project's status is. Summarize, cite ticket ids.
+- **Route work**: when the human asks for something to be done rather than known, hand it to the `steward` skill — you hold no authority over stewards, you route and scaffold.
+- **Surface decisions**: anything only the human can decide becomes an ask — see the `ask` skill. You never answer an ask for them.
+- **Protect the key**: it is a credential. Never paste it into tickets, logs, or web pages; never send it anywhere except as the Authorization header against their own `baseUrl`.
+
+## Invariants
+
+- **One door.** If the human needs two surfaces to know where things stand, you are doing it wrong — summarize in one reply.
+- **Their tenant only.** You never read, guess at, or name another tenant. A key that stops working is a question for their tenant admin, not a reason to try other accounts.
+- **You are not the steward.** You do not dispatch or overrule stewards; you make work visible and route it.
+- **No polling.** Answer from one read per question; do not loop requests against the API.
+- **Say what you cannot see.** If a route returns empty or you lack a permission the config's `permissions` array does not include, say exactly that instead of guessing.

package/skills/join/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: join
+description:
+  Join this machine to the customer's catalyst-cloud tenant in one step — install the skill bundle and discover the tenant from the account key. Use when a customer is getting started, when their config is missing or broken, when they rotated their key, or when they ask which tenant this machine belongs to.
+---
+
+<!-- vendored-from: @catalyst-cloud/catalyst-skills -->
+
+# Join — one command, no second step
+
+Joining is one command. It installs the skills where Claude Code discovers them, asks the cloud who the key belongs to (`GET /api/v1/me` — the key names the tenant, so the human never types an account id), and writes `~/.config/catalyst-cloud/customer.json` (mode 0600, holds the key).
+
+```sh
+npx @catalyst-cloud/catalyst-skills join --key <account-key>
+```
+
+Alternatives: `npm install -g @catalyst-cloud/catalyst-skills && catalyst-skills join --key <account-key>`, or `bunx @catalyst-cloud/catalyst-skills join --key <account-key>`. The key may also live in `CATALYST_CLOUD_TOKEN`; a non-default cloud may be pinned with `CATALYST_CLOUD_BASE_URL` or `--base-url`.
+
+## What you do
+
+1. Ask the human for their account key (their tenant admin mints it — you cannot).
+2. Run the join command. Watch its output: it names the tenant (`Joined <name> (<slug>)`), where the config landed, and which skills were installed.
+3. Verify: `catalyst-skills status` (or `npx @catalyst-cloud/catalyst-skills status`) echoes the tenant back.
+4. If join fails: `401 credential not accepted` means a stale or mistyped key — back to the tenant admin, never a retry loop. A network error names the URL; check `--base-url`.
+
+## Rules
+
+- **The key is a credential.** It goes into the join command or `CATALYST_CLOUD_TOKEN` and nowhere else — not into tickets, transcripts, or any file you write besides the one join writes.
+- **Never guess a tenant.** There is no `--account`; the key is the only tenant selector, on purpose.
+- **After an update**, the next command prints a one-line notice with the changelog entry and the update command — read it to the human if they are watching.

package/skills/linearis/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: linearis
+description:
+  Read and write Linear tickets for the customer's own tenant through its catalyst-cloud mirror — freshness-gated reads from the tenant API, writes through their existing Linear tooling. Use when a ticket's state, comments, labels, or projects must be read or changed and the concierge or steward needs the actual ticket record.
+---
+
+<!-- vendored-from: @catalyst-cloud/catalyst-skills — adapted from the catalyst repository's catalyst-dev plugin (plugins/dev/skills/linearis) for customer tenants -->
+
+# Linearis — tickets through the tenant mirror
+
+The customer's tenant mirrors their Linear and GitHub state. Reads go through the mirror's API — one request per question, never a poll loop. Writes (comment, label, state moves, filing an ask) go through whatever Linear access the customer's own environment already has; if none is configured, say so plainly rather than improvising a credential — and tell the `ask` skill, which must not file on a default without one.
+
+`baseUrl`, `key`, and `account` come from `~/.config/catalyst-cloud/customer.json` (written by `catalyst-skills join`). Every request below is `curl -sS -H "Authorization: Bearer <key>" "<baseUrl><route>?account=<account>&…"`.
+
+## Reading a ticket — freshness first, then the row
+
+A stored row is only as current as the mirror's last successful pass, and the row itself does not say when that was. So a ticket read is **two requests**: the freshness probe, then the row.
+
+1. **Gate on the freshness probe** — `GET /api/v1/freshness?account=<account>`. It returns `head_seq`, `server_time_ms`, and one entry per `sources[]` (`linear`, `github`) with `last_ingest_ms`, `last_reconcile_ms`, `has_error`, `unproven_legs`, and `deferrals`. Read the `linear` entry and classify before trusting anything:
+   - **fresh**: `server_time_ms - last_reconcile_ms` under 15 minutes, `has_error` is `false`, `unproven_legs` is `[]`.
+   - **stale**: `last_reconcile_ms` older than 15 minutes, or `has_error` is `true`, or `unproven_legs` is non-empty.
+   - **inconclusive**: `last_reconcile_ms` is `null`, or `has_error` / `unproven_legs` is `null` — the mirror could not answer, which is not the same as healthy.
+2. **Then read the row** — `GET /api/v1/issues/<id>?account=<account>` (the Linear identifier, e.g. `ABC-123`, or the id).
+
+Report the verdict with the answer: a stale or inconclusive read is delivered **as** stale or inconclusive ("as of <last_reconcile_ms>, the mirror's Linear pass is N minutes old / errored"), never as current. Do not act on a stale row as if it were live — if the decision depends on it, say what you could not confirm. Re-reading the row does not help while the probe is stale; the probe is the thing to re-check, once.
+
+## Listing and searching
+
+- **Search** — `GET /api/v1/search?q=<terms>&account=<account>` (2–100 characters). It matches ticket identifiers and titles, pull-request titles, project and initiative names, and returns up to five of each under `issues`, `pulls`, `projects`, `initiatives`. This is the only search route: `/api/v1/issues` has no `q` parameter — it ignores one silently and hands back the ordinary first page, which reads as a false "not found".
+- **List** — `GET /api/v1/issues?account=<account>&limit=<n>`, newest-updated first; narrow with `team_key=`, `state=`, `priority=`, `assignee=`, `cycle=`; page with the `after=` cursor the response returns.
+- Projects: `/api/v1/projects`; cycles: `/api/v1/cycles`; initiatives: `/api/v1/initiatives`; pull requests: `/api/v1/pulls`. Recent activity is the `concierge` skill's bounded history read, not `/api/v1/events` (a live server-sent stream that never returns on its own).
+
+## Rules
+
+- **Read the ticket before acting on it.** Never summarize a ticket from its title alone — read the body and the comment thread.
+- **Freshness over faith**: the mirror is near-live, not live, and only the freshness probe says how near. One probe per read; do not loop.
+- **One request per question.** The shared key is rate-finite; a poll loop spends the customer's whole fleet budget.
+- **Thread replies where they arrived** — a comment on a ticket is answered on that ticket, in-thread, never as a new top-level ticket.
+- **Bookkeeping comments are marked**: anything you post that is a machine record (a merge note, a state-move log) starts its body with `[bookkeeping]`.
+- **Never invent ticket ids.** Cite an identifier only after you read it back from the API.

package/skills/setup/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: setup
+description:
+  Readiness checks before first real use of the customer skill bundle — placeholders today, growing into a full preflight. Use when a customer asks whether their machine is ready, when something in the bundle misbehaves and you need a checklist, or right after join to confirm everything lines up.
+---
+
+<!-- vendored-from: @catalyst-cloud/catalyst-skills — placeholder readiness skill; grows into the real preflight -->
+
+# Setup — is this machine ready?
+
+A placeholder checklist, run by hand or by you, that answers "ready or not" in one pass. Each check is a real command; each failure names the fix.
+
+## Checklist
+
+1. **CLI present**: `npx @catalyst-cloud/catalyst-skills --version` (or `catalyst-skills --version` when installed globally) prints a version. Minimums: Claude Code 2.0+, Node 18.17+ (20+ recommended), Bun 1.0+ if you use `bunx`.
+2. **Joined**: `~/.config/catalyst-cloud/customer.json` exists and `catalyst-skills status` names a tenant. Missing → run the `join` skill.
+3. **Key works**: `curl -sS -H "Authorization: Bearer <key from the config>" <baseUrl from the config>/api/v1/me` answers `{account, slug, name, permissions, principal}`. `401` → stale key, ask the tenant admin. `403 account-not-operational` → the tenant is suspended; that is an admin conversation, not a local fix.
+4. **Skills discovered**: `ls ~/.claude/skills` shows `ask`, `concierge`, `join`, `linearis`, `setup`, `steward`. Missing → `catalyst-skills install`.
+5. **Tenant readable**: one read of `/api/v1/issues?account=<account>` with the same key returns data (or an empty list — that is a healthy read).
+
+## Rules
+
+- **One pass, one verdict.** End with `READY` or the short list of what is not ready, each with its fix.
+- **No fixes you were not asked for** — this skill reports; the human (or the concierge) decides what to change.
+- **Never print the key itself** — reference "the key in the config", not its value.
+
+This skill is deliberately a placeholder: the checks above are the honest minimum today. A fuller preflight (Claude Code version detection, permissions audit, connectivity matrix) grows here without changing the join flow.

package/skills/steward/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: steward
+description:
+  The long-running owner of ONE initiative or project on the customer's catalyst-cloud tenant. Use when asked to run, drive, or own a project end to end; to make work ready and visible; to watch tickets until they close; or when resuming a scope you already hold. Coordinates by preparing and tracking tickets in the tenant — never by writing product code itself.
+---
+
+<!-- vendored-from: @catalyst-cloud/catalyst-skills — adapted from the catalyst repository's catalyst-dev plugin (plugins/dev/skills/steward) for customer tenants -->
+
+# Steward — one scope, single-threaded owner
+
+You own one project or initiative on the customer's tenant until it closes: you make work **ready and visible**; the fleet — the customer's own agents and tools — does it.
+
+## Know the tenant
+
+Read `~/.config/catalyst-cloud/customer.json` (written by `catalyst-skills join`) for `baseUrl`, `key`, `account`, `slug`, `name`. Reads go to `curl -sS -H "Authorization: Bearer <key>" <baseUrl>/api/v1/<route>?account=<account>` — real routes: `/api/v1/issues`, `/api/v1/issues/<id>`, `/api/v1/search?q=`, `/api/v1/projects`, `/api/v1/cycles`, `/api/v1/initiatives`, `/api/v1/pulls`, `/api/v1/freshness`, `/api/v1/changes?since=`. Read a ticket the way the `linearis` skill says (freshness probe first), and recent activity the way the `concierge` skill says (a bounded `/api/v1/changes` read, never `/api/v1/events`, which is a live stream). Do not invent routes.
+
+## What you do
+
+- **Make work ready**: before anything is dispatched, the ticket it would run against exists, names its acceptance, and carries the context a worker needs (repos, environments, who decides).
+- **Make work visible**: keep a status summary for your scope current — what is in flight, what is blocked and on whom, what closed. The `concierge` reads your summary; the human reads the concierge.
+- **Watch for stalls**: a ticket that has not moved gets chased by you first — is it blocked, unowned, or waiting on the human? Only a genuine decision reaches the human, as an `ask`.
+- **Answer in-thread**: questions inside your scope are answered by you, in the place they were asked.
+
+## Invariants
+
+- **You hold one scope.** You never reach into another steward's initiative; cross-scope needs go through the concierge.
+- **You write no product code.** You change ticket state, post comments, and keep the status summary current. Implementation belongs to workers.
+- **A cap is never silent**: every ticket you could have moved but did not is named, with why.
+- **Escalate inward**: an unblocking question goes to another agent or the concierge before it ever becomes a human ask. Only product, priority, or approval decisions survive to the human.
+- **No polling loops**: check state once per decision, not on a timer.