@catalyst-cloud/catalyst-skills 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.1.1
+
+The bundle now lives and publishes from its own public repository, coalesce-labs/catalyst-cloud-skills, so every skill can be read before it is installed; the README leads with the CATALYST_CLOUD_TOKEN form of join, and join's output no longer names an internal ticket.
+
 ## 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/README.md

@@ -1,70 +1,111 @@
 # @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.
+The customer skill bundle for Catalyst Cloud (https://catalystcloud.dev). One command installs six Claude Code skills — `concierge`, `steward`, `ask`, `linearis`, `join`, and `setup` — into `~/.claude/skills` and joins your machine to your own tenant. It is for catalyst-cloud customers: every skill is plain Markdown you can read in this repository before you install it, the installer is this npm package, and the account key from your tenant admin is the only credential.
+
+## Read the skills first
+
+Every skill is a plain Markdown file under `skills/<name>/SKILL.md` in this repository. Read them before you install anything:
+
+- [`skills/ask/SKILL.md`](skills/ask/SKILL.md)
+- [`skills/concierge/SKILL.md`](skills/concierge/SKILL.md)
+- [`skills/join/SKILL.md`](skills/join/SKILL.md)
+- [`skills/linearis/SKILL.md`](skills/linearis/SKILL.md)
+- [`skills/setup/SKILL.md`](skills/setup/SKILL.md)
+- [`skills/steward/SKILL.md`](skills/steward/SKILL.md)
 
 ## 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` |
+- Claude Code 2.0 or newer, which discovers skills in `~/.claude/skills`.
+- Node 18.17 or newer (20 or newer recommended), which supplies the `npx` used below.
+- Bun 1.0 or newer, optional, only if you prefer `bunx` over `npx`.
+- An account key from your tenant admin. The key is the only tenant selector: you never type a tenant or account id.
 
-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
 
-## Install and join — one step
+The recommended form passes the key as an environment variable, because a key typed into a command line lands in your shell history:
 
 ```sh
-npx @catalyst-cloud/catalyst-skills join --key <your-account-key>
+CATALYST_CLOUD_TOKEN=<your-account-key> npx @catalyst-cloud/catalyst-skills join
 ```
 
-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.
+If you accept the shell-history trade-off, the `--key` form is equivalent:
 
-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.
+```sh
+npx @catalyst-cloud/catalyst-skills join --key <your-account-key>
+```
 
-### Plain global-install form
+Or install the package globally once and run the command directly:
 
 ```sh
 npm install -g @catalyst-cloud/catalyst-skills
-catalyst-skills join --key <your-account-key>
+CATALYST_CLOUD_TOKEN=<your-account-key> catalyst-skills join
 ```
 
-`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.
+`bunx @catalyst-cloud/catalyst-skills join` works in place of the `npx` form. A non-default cloud is set with `CATALYST_CLOUD_BASE_URL` or `--base-url <url>`.
+
+`join` does all of this in one run:
+
+1. Installs the six skills into your skills directory, `~/.claude/skills` by default (`--skills-dir <dir>` overrides it).
+2. Calls `GET /api/v1/me` on the cloud with your key, which discovers your tenant from the key alone.
+3. Writes `~/.config/catalyst-cloud/customer.json` with file mode `0600`; that file holds your key.
+4. Prints what it did: the tenant it joined (`Joined <name> (<slug>) — account <account>`), the config path and mode, the skills installed, and the tenant contract range the package pins.
 
-### If join fails
+Re-running `join` after a key rotation rewrites the config. `catalyst-skills status` prints which tenant this machine is joined to; `catalyst-skills --version` prints the package version and its pinned tenant contract range.
 
-- `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`.
+## First use
 
-## What comes from where
+Open a new Claude Code session and talk to the concierge about your own tenant — it reads the config `join` wrote. For example:
 
-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.
+- Which tenant is this machine joined to, and who am I on it?
+- Give me a status summary of my projects this cycle.
 
-- **`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`).
+## The skills
 
-## Version contract
+| skill | purpose | file |
+| --- | --- | --- |
+| `concierge` | The one agent a human talks to on their tenant: status summaries, routing work to stewards, filing new work, and questions their tenant data answers. | [`SKILL.md`](skills/concierge/SKILL.md) |
+| `steward` | The long-running owner of one initiative or project: makes work ready and visible, watches tickets until they close, and never writes product code itself. | [`SKILL.md`](skills/steward/SKILL.md) |
+| `ask` | Records a decision request when active work is gated on a decision or action only the human can make. | [`SKILL.md`](skills/ask/SKILL.md) |
+| `linearis` | Reads and writes Linear tickets for your tenant through its catalyst-cloud mirror, with freshness-gated reads. | [`SKILL.md`](skills/linearis/SKILL.md) |
+| `join` | Joins this machine to your tenant in one step: installs the bundle and discovers the tenant from the account key. | [`SKILL.md`](skills/join/SKILL.md) |
+| `setup` | Runs readiness checks before first real use of the bundle, and confirms everything lines up right after `join`. | [`SKILL.md`](skills/setup/SKILL.md) |
 
-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.
+## Versions and origins
 
-## Updates (one-line notice)
+The package pins the tenant contract range `0.x`, recorded in `package.json` under `catalystCloud.tenantContractRange`, and reports it in `--version`, `status`, and `join`. The four vendored skills (`concierge`, `steward`, `ask`, `linearis`) carry a `vendored-from:` line naming their origin, the catalyst repository's catalyst-dev plugin; `join` and `setup` are written in this repository.
 
-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:
+## What it writes on your machine
 
+- Six skill directories under `~/.claude/skills/`: `ask`, `concierge`, `join`, `linearis`, `setup`, `steward`.
+- One config file, `~/.config/catalyst-cloud/customer.json`, written with mode `0600`.
+
+Nothing else. Your account key goes into that one config file and nowhere else.
+
+## Updating
+
+Update the package with `npm update -g @catalyst-cloud/catalyst-skills`, or run any command against the latest publish with `npx @catalyst-cloud/catalyst-skills@latest join`. The next `catalyst-skills` run prints a one-line notice:
+
+```
+[catalyst-skills] updated 0.1.0 → 0.2.0: <that version's CHANGELOG.md summary> · update with: npm update -g @catalyst-cloud/catalyst-skills (or: npx @catalyst-cloud/catalyst-skills@latest join)
 ```
-[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)
+
+The same run refreshes the installed skill copies to the new bundle before it records the new version, so a published skill fix reaches your machine. A skill directory you hand-edited 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 and tells you to run `catalyst-skills install`.
+
+## Uninstalling
+
+```sh
+rm -rf ~/.claude/skills/ask ~/.claude/skills/concierge ~/.claude/skills/join ~/.claude/skills/linearis ~/.claude/skills/setup ~/.claude/skills/steward
+rm ~/.config/catalyst-cloud/customer.json
 ```
 
-and never prints it again for that version. `catalyst-skills notice` is the skill-facing entry point for that line.
+If you joined with `--skills-dir <dir>`, remove the six directories there instead. If you installed the package globally, also run `npm uninstall -g @catalyst-cloud/catalyst-skills`.
+
+## If join fails
 
-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`.
+- `catalyst-skills: GET /me failed (401): credential not accepted — ask your tenant admin for a valid account key` — the key is stale or mistyped. Ask your tenant admin for a valid account key, then run `join` again.
+- `catalyst-skills: GET /me failed (403): account-not-operational` — the tenant is suspended. This is an admin conversation on the tenant, not a local fix.
+- `catalyst-skills: could not reach <url>: <detail>` — the machine cannot reach the cloud. The URL is named in the message; check `CATALYST_CLOUD_BASE_URL` or `--base-url`.
 
-## For the package maintainers
+## License
 
-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.
+MIT — see [LICENSE](LICENSE). How to contribute and how releases happen are described in [CONTRIBUTING.md](CONTRIBUTING.md).

package/dist/cli.js

@@ -386,7 +386,7 @@ async function cmdJoin(args, ctx, manifest) {
     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)`);
+    ctx.stdout(`Tenant contract range: ${manifest.tenantContractRange}`);
     if (previous && previous !== manifest.version) {
         const entry = parseChangelogEntry(readChangelog(), manifest.version);
         ctx.stdout(updateNoticeLine(previous, manifest.version, entry));

package/package.json

@@ -1,12 +1,20 @@
 {
   "name": "@catalyst-cloud/catalyst-skills",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/coalesce-labs/catalyst-cloud-skills.git"
+  },
+  "homepage": "https://github.com/coalesce-labs/catalyst-cloud-skills#readme",
+  "bugs": {
+    "url": "https://github.com/coalesce-labs/catalyst-cloud-skills/issues"
+  },
   "engines": {
     "node": ">=18.17"
   },
@@ -29,11 +37,11 @@
     "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"
+    "test:coverage": "vitest run --coverage"
   },
   "devDependencies": {
-    "@catalyst-cloud/typescript-config": "workspace:*",
     "@types/node": "^26.3.0",
+    "@vitest/coverage-v8": "^4.1.11",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11"
   }