quiver-cli 1.3.1 → 2.0.0

package/README.md

@@ -1,298 +1,256 @@
 # quiver-cli
 
-Compose a selected subset of skills, slash commands, provider plugins and MCP
-servers from a central catalog into any repo — as **native configs** for
-opencode, Claude Code and Codex — with **lockfile-based drift awareness**.
+Quiver V2 installs skills from direct GitHub sources, plus custom skills,
+commands, provider plugins and MCP servers from catalogs. Each installed entry
+has its own source pin and drift baseline. Runtime output remains native to
+OpenCode, Claude Code and Codex; there is no extra agent runtime.
 
-One thing done right: repo composition + drift detection. No marketplace, no
-extra agents, no command abstraction.
+**Release status:** this branch documents V2, targeting 2.0.0. The published
+CLI remains 1.3.1 until the V2 release; use a source build to try these contracts.
 
-- **One source of truth** — `.agents/` + `quiver.lock`, committed to the repo.
-- **Native output** — `.opencode/`, `opencode.json`, `.claude/`, `.mcp.json`,
-  `.codex/` are generated and gitignored; each tool loads its own format.
-- **Drift detection** — content digests for skills/commands, tool snapshots for
-  MCP servers (including tool-description poisoning).
-- **Upstream awareness** — know when a source repo updates a skill you imported.
+- Commit `.agents/` and `quiver.lock`. They are the project's local source of truth.
+- Generate provider files with `sync`; do not edit or commit generated output.
+- Use `check` for local drift and MCP snapshots, and `update` for source changes.
+- Catalog content lives in [quiver-catalog](https://github.com/nbialk/quiver-catalog),
+  not in the CLI package.
 
-## Quick start
+## Why V2?
 
-Requires **Node >= 20.12** (the interactive pickers depend on it; `init`, `add`,
-`remove` and `providers` abort on older versions).
+In V1, "up to date" meant matching the configured catalog. With the default
+bundled catalog, external skill updates depended on a catalog import and a new
+CLI release. V2 removes that bottleneck: external skills track their original
+repositories, while custom and curated content stays in a separate catalog.
+Each installation keeps its own source revision; updates remain explicit.
 
-From the root of the target repository:
+Read the [V2 guide](https://github.com/nbialk/quiver-cli/blob/main/docs/v2.md)
+for the motivation, release highlights, breaking changes and upgrade walkthrough.
 
-```bash
-pnpm dlx quiver-cli init
-```
-
-The interactive picker lets you select skills, commands and MCP servers from
-the catalog; quiver then materializes them into `.agents/`, writes
-`quiver.lock`, generates the native provider configs and patches `.gitignore`.
-
-```bash
-git add .agents quiver.lock .gitignore
-git commit -m "chore: add agent config"
-```
+## Quick Start
 
-Restart your AI tool (opencode, Claude Code, Codex) to load the configs.
-Day to day:
+Requires **Node >= 20.12.0**. From the target repository, choose one setup:
 
 ```bash
-quiver-cli add mcp:context7   # add one entry (skill:/command:/mcp:/plugin:)
-quiver-cli sync               # regenerate provider configs from .agents/
-quiver-cli check              # detect drift (CI-friendly: --json, exit 1)
+quiver-cli init          # interactive entry and provider selection
+quiver-cli init --empty  # alternative: local setup, no catalog fetch or network
 ```
 
-## Commands
-
-| Command                    | Description                                                       |
-| -------------------------- | ----------------------------------------------------------------- |
-| `quiver-cli init`          | Interactive picker; write native configs + `quiver.lock`          |
-| `quiver-cli add <id>`      | Add one entry (`skill:`, `command:`, `mcp:`, `plugin:`)           |
-| `quiver-cli remove <id>`   | Remove one entry; keep lockfile + configs consistent (alias: `rm`)|
-| `quiver-cli disable <id>`  | Turn an MCP server off locally (`mcp:<name>`, gitignored override)|
-| `quiver-cli enable <id>`   | Turn a locally disabled MCP server back on                        |
-| `quiver-cli update [id]`   | Pull newer catalog content into `.agents/` (all or one entry)     |
-| `quiver-cli sync`          | Regenerate provider configs from `.agents/`; warn on drift        |
-| `quiver-cli providers`     | Change which tools get configs (`opencode`, `claude`, `codex`)    |
-| `quiver-cli list`          | Show skills, commands, plugins + MCP tool counts (alias: `ls`)    |
-| `quiver-cli check`         | Detect drift: skill digests, provider shims, MCP tool snapshots   |
-| `quiver-cli upstream`      | Check source repos for skill updates (catalog maintenance)        |
-| `quiver-cli upstream pull` | Pull latest upstream content into the catalog (`[skill]`)         |
-| `quiver-cli help`          | Show help                                                         |
-| `quiver-cli version`       | Show the version + any available update (`-v`, `--version`)       |
-
-Options: `-f/--force`, `--all/-y` (non-interactive), `--json`
-(check/upstream/list/update), `--providers=opencode,claude` (set the generated
-configs for `init`, `sync` and `providers`), `--catalog=<source>` (catalog
-source for `init` and `upstream`), `--offline` (skip MCP re-introspection
-during `check`), `-V/--verbose` (full tool lists and description diffs in
-`check`), `--accept` (record the current MCP tool snapshots as the new
-baseline in `check`), `--introspect-stdio` (allow running stdio MCP servers
-during `check`).
-
-Value flags are written with `=` (`--providers=opencode,claude`,
-`--catalog=github:acme/catalog`); the space-separated form is not supported.
-`quiver-cli providers` also accepts the list as a positional
-(`quiver-cli providers opencode,claude`) and falls back to an interactive
-multiselect pre-filled with the current selection.
-
-## What gets generated
-
-| Artifact | opencode                    | Claude Code                 | Codex                        |
-| -------- | --------------------------- | --------------------------- | ---------------------------- |
-| Skills   | `.opencode/skills/*` (link) | `.claude/skills/*` (link)   | native from `.agents/skills` |
-| Commands | `.opencode/commands/*`      | `.claude/commands/*` (link) | (not supported yet)          |
-| MCP      | `opencode.json`             | `.mcp.json`                 | `.codex/config.toml`         |
-| Settings | `.opencode/tui.json`        | `.claude/settings.json`     | —                            |
-| Plugins  | `.opencode/plugins/*`       | —                           | —                            |
-| Guide    | `AGENTS.md` (link)          | `CLAUDE.md` (link)          | `AGENTS.md` (native)         |
-
-`AGENTS.md` at the repo root is a symlink to `.agents/AGENTS.md` (created only
-when the catalog ships one); `CLAUDE.md` links to it. Both are written
-independently of the provider selection. Codex reads skills and `AGENTS.md`
-natively from the repo, so no shims are emitted for those.
-
-By default configs are generated for all three tools. `init` asks which ones
-you use (or pass `--providers=opencode,claude`); the choice is stored in
-`quiver.lock`, and deselected tools have their generated files cleaned up on
-`sync`.
-
-Besides `mcpServers` and `plugins`, `.agents/config.json` carries provider
-overlays that are copied into the generated configs:
-
-| Key        | Effect                                                            |
-| ---------- | ----------------------------------------------------------------- |
-| `opencode` | Merged with the selected MCP servers into `opencode.json`         |
-| `tui`      | Emitted as `.opencode/tui.json`                                   |
-| `claude`   | `claude.settings` is written verbatim to `.claude/settings.json`  |
-| `shared`   | Free-form values carried through into the repo's `config.json`    |
-
-Selected local plugins are copied under `.agents/plugins/opencode/` and linked
-into OpenCode's plugin discovery directory.
-
-MCP `${VAR}` placeholders are emitted as OpenCode-native `{env:VAR}` references,
-so generated `opencode.json` files never contain resolved secret values.
-
-The bundled catalog includes the official RTK OpenCode adapter. Install RTK
-separately, then enable the adapter per repository:
+`init --all` explicitly selects all eligible catalog entries. `--yes`/`-y`
+confirms defaults, not selection of everything. Non-interactive selection needs
+`--all` or `--empty`; JSON mode never opens a picker. Initialization preserves
+existing local content and refuses to replace an existing lockfile.
 
 ```bash
-quiver-cli add plugin:rtk
-quiver-cli check             # also verifies that the rtk binary is on PATH
+quiver-cli add                         # browse remaining catalog entries
+quiver-cli add mcp:context7            # select one entry
+quiver-cli add --all                   # explicitly select all remaining entries
+quiver-cli add github:vercel-labs/agent-skills/skills/react-best-practices --name=react-performance
+quiver-cli sync                        # local provider regeneration
+quiver-cli check --offline             # local checks only
 ```
 
-## Toggling MCP servers locally
-
-Some MCP servers are only worth their token cost for specific tasks. Instead
-of removing them, switch them off locally:
-
-```bash
-quiver-cli disable mcp:posthog   # drop it from the generated provider configs
-quiver-cli enable mcp:posthog    # bring it back - instant, no re-introspection
-```
-
-The state lives in `.agents/config.local.json` (gitignored), so toggling never
-touches the committed `.agents/config.json`, `quiver.lock` or your teammates'
-setups. Disabled servers keep their lockfile entry and tool snapshot; `list`
-marks them as `disabled`, and `check` skips their re-introspection.
-
-## The lockfile
+Commit `.agents/`, `quiver.lock` and the generated ignore rules, then restart
+your provider to load its configuration. Keep `.env.local` and
+`.agents/config.local.json` private and gitignored.
 
-`quiver.lock` records, per entry: source path, content digest, and — for MCP
-servers — a **tool snapshot** (`{ description, inputSchemaHash }` per tool).
-This is the basis for `sync` and `check`.
+## Sources And Pins
 
-## `check` — drift awareness
+Direct skill sources use `github:owner/repo[/path][#ref]`. The selected directory
+must contain `SKILL.md`; accompanying references and scripts are installed too.
+Use `--name=<alias>` to choose the installed name without changing its source.
 
-`check` is the single drift command. It compares four things:
+- No `#ref` tracks the repository's default branch, not an assumed `main`.
+- A named branch or tag resolves that exact ref on installation and update.
+- A full 40-character commit SHA is fixed. Quiver does not select semver ranges
+  or automatically switch to a newer version tag.
+- A unique bare name is accepted where an entry is expected. Disambiguate with
+  `skill:name`, `command:name`, `plugin:name` or `mcp:name` when names overlap.
 
-- **Skills/commands**: compares the stored digest against the current `.agents/`
-  content.
-- **Provider shims**: verifies the generated `.opencode/`, `.claude/`, `.codex/`
-  configs match the lockfile (missing, stale or out-of-sync files) → fix with
-  `quiver-cli sync`.
-- **Plugin requirements**: warns when an installed plugin needs a binary that is
-  not on `PATH` (e.g. `rtk`).
-- **MCP servers** (the real lever): re-introspects `tools/list` and diffs against
-  the snapshot → new/removed tools, changed input schemas, and — security
-  critical — **changed tool descriptions** (defends against tool-description
-  poisoning), shown as a readable before/after.
+The default discovery source is `github:nbialk/quiver-catalog`. Its
+`catalog.json` contains pointers to external skills; custom skills, commands,
+plugins and MCP definitions live alongside it. `posthog-custom` is the curated
+Quiver variant, not an unchanged copy of the original PostHog skills. Choose
+an original source explicitly if that is what you want.
 
-The first successful introspection records a baseline; subsequent `check` runs
-diff against it. stdio servers run foreign code and are only introspected with
-`--introspect-stdio`.
+Catalog pointers are resolved afresh for **new installs only**. Installed entries
+record their own repository/path, requested ref, resolved commit and pristine
+source digest in `quiver.lock`. Changing a catalog alias never retargets an
+installed entry, and its updates do not depend on that alias remaining available.
 
-**OAuth-protected servers** (e.g. Linear): `check` reuses opencode's MCP
-credentials (`~/.local/share/opencode/mcp-auth.json`, read-only — quiver never
-refreshes or rewrites them). Authenticate once with
-`opencode mcp auth <name>`, then re-run `quiver-cli check` to record the tool
-snapshot. Without a valid token the server is skipped with an actionable hint,
-and `quiver-cli list` shows why the tool count is missing.
-
-Pass `--offline` to skip MCP re-introspection entirely and check only digests
-and provider shims — no network, no foreign code, useful for a fast local
-sanity check.
-
-Once a reported MCP change has been reviewed and is legitimate, record it as the
-new baseline:
+Teams can select a custom catalog at initialization:
 
 ```bash
-quiver-cli check -V         # full tool lists and description before/after
-quiver-cli check --accept   # adopt the current snapshots
+quiver-cli init --catalog=github:acme/agent-catalog
+quiver-cli init --catalog=github:acme/monorepo/tools/agents#stable
+quiver-cli init --catalog=local:/absolute/path/agent-catalog
 ```
 
-`quiver-cli check --json` is CI-friendly (exit 1 on drift).
-
-## `upstream` — source updates
-
-`upstream` is a **catalog-maintenance** command, not a per-repo one. `check`
-detects drift between the lockfile and the repo's `.agents/`; `upstream` answers
-a different question: **has the source repo updated a skill since it was
-imported into the catalog?**
-
-Because it records baselines (and `pull` rewrites skill copies) **in the catalog
-itself**, run it where the catalog is writable — inside the quiver-cli repo, or
-against a writable local checkout via `--catalog=local:/absolute/path/.agents`.
-Run from a consuming repo, where the catalog is the read-only installed package
-(or a remote cache), it aborts with guidance; use `quiver-cli check` /
-`quiver-cli update` there instead.
-
-Origins live in `template/.agents/upstreams.json` (`repo`, `path`, `ref` per
-skill). `quiver-cli upstream` queries the GitHub Commits API for the latest
-commit touching each path:
+The locator points to the catalog directory itself; append `/.agents` only if
+that is where the catalog actually lives. `local:` is for explicit absolute
+development paths, never paths relative to the CLI package. Local installations
+record their source root, path and digest; they do not invent a Git commit pin.
 
-- First run records a baseline commit per skill.
-- Later runs report `up to date`, `upstream updated <old> → <new>`, or `skipped`
-  (e.g. rate-limited). To lift the anonymous 60 req/h limit, provide a token via
-  `GITHUB_TOKEN`/`GH_TOKEN` (env or repo `.env.local`), or just log in with the
-  `gh` CLI — its token is picked up automatically.
-- Skills flagged `curated: true` are reported as **drift-curated** — they were
-  modified after import, so changes must be reconciled by hand.
+GitHub downloads use commit-addressed caches under `~/.cache/quiver/catalogs/`
+(or `$XDG_CACHE_HOME/quiver/catalogs/`). Private sources require read access via
+`GITHUB_TOKEN`, then `GH_TOKEN`, then an authenticated `gh` CLI, in that order.
+Authentication, missing paths, invalid refs and rate limits are errors, never
+evidence that an entry is up to date.
 
-`quiver-cli upstream pull [skill]` fetches the latest upstream content into the
-catalog via a shallow sparse git clone and records the new baseline. Curated
-skills are skipped unless `--force` is given. Repos consuming the catalog then
-pick the changes up with `quiver-cli update` (local modifications are never
-overwritten without `--force`). `quiver-cli upstream --json` is CI-friendly
-(exit 1 on drift).
+## Local Drift
 
-## Remote catalogs
+`sync` reads installed `.agents/` content and regenerates provider files. It
+does not fetch sources, advance pins or accept changed lockfile digests. A fresh
+clone can use its committed local files without reaching the catalog.
 
-By default `init` uses the catalog bundled with the package. Teams can host
-their own catalog in a GitHub repo and point `init` at it:
+Normal `check` is project-read-only. It compares content/config digests, provider
+files, plugin binary requirements and observed MCP tool descriptions/schemas
+against recorded baselines. It does not silently save a first MCP snapshot.
 
 ```bash
-quiver-cli init --catalog=github:acme/agent-catalog            # .agents at repo root
-quiver-cli init --catalog=github:acme/monorepo/tools/.agents   # subdirectory
-quiver-cli init --catalog=github:acme/agent-catalog#v2         # branch or tag
+quiver-cli check --json
+quiver-cli check --offline
+quiver-cli check mcp:context7 --verbose
+quiver-cli check mcp:context7 --accept  # explicitly record the observed snapshot
+quiver-cli check skill:cleanup --offline --accept
+quiver-cli check --all --accept        # explicit acceptance for all entries
 ```
 
-The source is recorded in `quiver.lock` together with the **resolved commit
-SHA** (`catalog.ref` / `catalog.resolved`):
+Acceptance updates only the selected local baseline and successfully observed
+MCP snapshots. It does **not** change the pristine source digest, prove source
+authenticity or approve later overwrites of accepted customizations. Missing or
+unsafe local artifacts cannot be accepted.
 
-- `add` installs from the pinned SHA — reproducible, and served from the local
-  cache without network when possible.
-- `update` re-resolves the ref (branch/tag HEAD), moves the pin forward and
-  pulls newer content into `.agents/`.
+`check --offline` performs no network access and runs no stdio MCP code. Skipped,
+missing-baseline or authentication-blocked MCP observations are reported as
+incomplete, not current. In JSON output, inspect `complete` as well as `ok`:
+an intentional offline skip can pass local checks without certifying live tools.
+A missing baseline on a queried server, detected drift or an authentication
+failure produces a nonzero exit code.
 
-Catalogs are downloaded via the GitHub tarball API and cached under
-`~/.cache/quiver/catalogs/` (content-addressed by commit SHA, immutable).
-`XDG_CACHE_HOME` is honoured if set.
+Stdio introspection requires `--introspect-stdio`, which permits running foreign
+code. For OAuth-protected HTTP servers, Quiver can reuse OpenCode credentials
+read-only; it does not refresh them. Authenticate with `opencode mcp auth <name>`,
+review with `check`, then explicitly accept the snapshot. `inspect <name>` shows
+recorded MCP tools, descriptions and estimated token cost without a source fetch.
 
-### Private repos & tokens
-
-For private catalog repos (and to lift API rate limits), provide a GitHub
-token. Resolution order: `GITHUB_TOKEN` → `GH_TOKEN` → the `gh` CLI.
-
-**The cleanest way is the `gh` CLI** — no token to manage, just the familiar
-browser-confirm flow:
+## Source Updates
 
 ```bash
-gh auth login        # browser confirmation; quiver picks up the token automatically
+quiver-cli update --dry-run --json
+quiver-cli update skill:react-performance
+quiver-cli update skill:react-performance --source=github:acme/skills/react#stable --dry-run
 ```
 
-Once `gh` is authenticated, quiver uses its token automatically. For CI or
-environments without `gh`, set `GITHUB_TOKEN` (or `GH_TOKEN`) instead:
-
-```bash
-GITHUB_TOKEN=ghp_… quiver-cli add mcp:context7
-```
+`update [id]` resolves each installed entry's recorded source independently.
+Without an ID it considers all installed entries. A dry run writes nothing in
+the project, including the lockfile or provider files; it may populate caches.
 
-The token needs read access to the catalog repo. quiver never writes tokens to
-generated configs or the lockfile.
+Local edits, including previously accepted customizations, are preserved unless
+you approve discarding them with `--force`. This is destructive content approval,
+not permission to follow a different catalog pointer. Only a targeted
+`update <id> --source=github:...` explicitly retargets an entry. An absolute
+`--source=local:/path/to/artifact` is also supported for local development.
 
-## Secrets
+Application is staged per entry, with rollback for handled I/O failures. Entries
+that succeed remain correctly locked if later entries fail. This is not a global
+or crash-atomic transaction. If rollback itself fails, recovery backups are
+retained under `.quiver-stage-*`; review the reported location before cleanup.
+Provider generation is separate: repair derived output with `quiver-cli sync`.
 
-MCP servers referencing `${VAR}` placeholders resolve from `.env.local` at the
-repo root (gitignored). `init`/`add` generate an `.env.local.example` listing
-exactly the variables the selected servers need (none needed → no file). For
-Codex, secret headers are mapped to `env_http_headers` so secrets never land in
-the committed `config.toml`.
+## Migrating From V1
 
-## Staying up to date
+**Migration does not automatically connect old entries to upstream sources.**
+Follow the [V2 upgrade walkthrough](https://github.com/nbialk/quiver-cli/blob/main/docs/v2.md#upgrading-an-existing-project)
+to migrate metadata first and then review source assignments separately.
 
-quiver-cli checks npm for a newer release (at most once a day, cached under
-`~/.cache/quiver/`, or `XDG_CACHE_HOME` if set) and prints a one-line notice
-after a command when an update is available. `quiver-cli version` checks on
-demand. Update with:
+V1 projects can still `list`, `sync` and `check` their local installation without
+fetching the former bundled catalog. Mutations of the lockfile require migration:
 
 ```bash
-pnpm add -g quiver-cli   # or: npm i -g quiver-cli / yarn global add quiver-cli
+quiver-cli migrate --dry-run --json
+quiver-cli migrate
 ```
 
-The check is best-effort and never blocks or fails a command. It is silenced
-automatically for `--json`, non-interactive shells and CI, and can be disabled
-entirely with `QUIVER_NO_UPDATE_NOTIFIER=1`.
+Migration changes metadata only. Installed files, IDs, paths, local digests and
+MCP snapshots stay unchanged. Historical origins remain explicitly **legacy and
+unverified**; migration neither fetches content nor fabricates source digests.
+
+An old `local:template/.agents` locator is preserved as historical provenance,
+not reinterpreted relative to the new package and not automatically mapped to
+quiver-catalog or an original author's repository. Legacy entries need a reviewed,
+explicit `update <id> --source=github:...` before source updates are possible.
+Use direct sources for new additions when the historical discovery catalog is
+no longer available. Curated V1 content is never silently replaced by originals.
+
+## Provider Output
+
+Provider behavior is unchanged in V2: all providers consume local installed
+content, not the discovery catalog or a live remote source.
+
+| Artifact | OpenCode | Claude Code | Codex |
+| -------- | -------- | ----------- | ----- |
+| Skills | `.opencode/skills/*` links | `.claude/skills/*` links | native `.agents/skills` |
+| Commands | `.opencode/commands/*` | `.claude/commands/*` links | not supported |
+| MCP | `opencode.json` | `.mcp.json` | `.codex/config.toml` |
+| Settings | `.opencode/tui.json` | `.claude/settings.json` | none |
+| Plugins | `.opencode/plugins/*` links | none | none |
+| Guide | `AGENTS.md` link | `CLAUDE.md` link | native `AGENTS.md` |
+
+When `.agents/AGENTS.md` exists, root `AGENTS.md` links to it and `CLAUDE.md`
+links to `AGENTS.md`, independently of provider selection. Ignore rules for
+these generated guides are root-only, so nested source guides remain committable.
+
+`init --providers=opencode,claude` selects providers explicitly; otherwise the
+picker offers all three. `providers [a,b]` changes the stored selection and
+regenerates output, cleaning deselected providers. `sync` uses that selection;
+it no longer accepts `--providers`.
+
+`.agents/config.json` holds MCP/plugin definitions and provider overlays:
+`opencode` merges into `opencode.json`, `tui` becomes `.opencode/tui.json`,
+`claude.settings` becomes `.claude/settings.json`, and `shared` stays local.
+The catalog's `plugin:rtk` adapter requires RTK installed separately; `check`
+verifies its binary is on `PATH`.
+
+`disable mcp:<name>` and `enable mcp:<name>` only change gitignored
+`.agents/config.local.json` and generated output. They preserve committed config,
+pins and snapshots. `list` marks disabled servers, and `check` skips their live
+introspection. `remove <id>` removes an installation; local changes require
+explicit `--force` approval. `rm` and `ls` remain aliases for `remove` and `list`.
+
+MCP `${VAR}` placeholders use `.env.local`. Generated OpenCode configuration uses
+`{env:VAR}`; Codex uses `env_http_headers` for secret headers. Example env files
+contain variable names, not credentials. Never commit real secrets or generated
+provider files.
+
+## Limits And Safety
+
+- GitHub is the only remote source host. Quiver does not hydrate Git LFS objects
+  or submodules.
+- Symlinks inside a selected skill are unsupported. Digests cover file bytes
+  and relative paths, not executable bits or other file modes.
+- Quiver copies direct skill scripts but does not execute them. Provider agents
+  may execute installed scripts, commands or plugins; installation is not a
+  security guarantee. Review sources and updates before enabling them.
+- MCP snapshots expose changes, including possible tool-description poisoning;
+  they do not certify a server as safe. See [SECURITY.md](SECURITY.md).
+
+Run `quiver-cli help` for command-specific flags. Value options require `=`,
+for example `--name=alias` or `--source=github:owner/repo/path#ref`. There is no
+`upstream` or `outdated` command; use `update --dry-run` for source changes.
+`version` reports the installed CLI version locally. Optional npm update notices
+after online install/update operations can be disabled with
+`QUIVER_NO_UPDATE_NOTIFIER=1`; local/offline commands do not trigger them.
 
 ## Development
 
 ```bash
 pnpm install
-pnpm build          # tsup -> dist/cli.js
 pnpm typecheck
-pnpm test           # vitest
+pnpm vitest run test/package.test.ts
+pnpm build
+node bin/quiver-cli.mjs help
 ```
 
-The catalog lives under `template/.agents/`. Edit it to change what's available
-to install.
+The npm package includes `bin/` and `dist/`, plus npm's standard package metadata,
+README and license. It contains no bundled catalog or skill payloads. Contribute
+catalog changes to [quiver-catalog](https://github.com/nbialk/quiver-catalog), not
+this repository's installed `.agents/`. See [CONTRIBUTING.md](CONTRIBUTING.md).