Devin Foley
1ea2f0e2d6
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The release channels (canary → nightly → beta → stable) select by install target, and users discover them today only through maintainer-oriented docs > - A user who wants to know "which lane am I on, and what else is there" has no self-serve answer > - The channel rollout planned a read-only CLI command for exactly this > - This pull request adds `paperclipai channels`: every lane with the version its dist-tag resolves to, the install command for it, and which lane the running install follows > - The benefit is self-serve lane discovery without reading release documentation ## Linked Issues or Issue Description Refs #11008 — the user-facing discovery surface for the channel model completed there. **Subsystem affected** CLI: `cli/src/commands/channels.ts` (new), `cli/src/index.ts`, `doc/CHANNELS.md`, tests. **Problem or motivation** Channel selection is install-based (`@latest` / `@beta` / `@nightly` / `@canary`), but nothing in the product tells a user which channel their install follows or what the other lanes currently resolve to. The information lives in `doc/CHANNELS.md` and the npm registry, neither of which a running install surfaces. **Proposed solution** A read-only `paperclipai channels` command: prints each channel with the version its dist-tag currently resolves to (per-lane registry lookups that degrade to `unavailable` individually), the install command for each, and the running install's lane parsed from its version suffix — source checkouts carry the repository's placeholder version and are reported as unmapped rather than guessed. `--json` emits the same data for scripting. ## What Changed - `cli/src/commands/channels.ts` (new): channel table, lane parsing, registry resolution, human and `--json` output - `cli/src/index.ts`: registers `channels` - `doc/CHANNELS.md`: "Seeing where you are" section - `cli/src/__tests__/channels.test.ts` (new): lane parsing including unknown versions, full resolution against a fake runner, per-lane degradation, table/dist-tag sync ## Verification - `vitest run cli/src/__tests__/channels.test.ts`: 5 pass - `pnpm typecheck` in `cli/` - Live run against the real registry shows all four lanes with their current versions (`2026.722.0` / `2026.811.0-beta.0` / `2026.811.0-nightly.0` / canary) and correctly reports a source checkout as unmapped ## Risks - Low. Read-only command reusing the existing `resolvePublishedVersion` registry helper; no state, no auth, no publish surface ## Model Used Claude Fable 5 (`claude-fable-5`, Anthropic) in Claude Code, with extended thinking and full tool use. All changes model-authored under human direction. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green (pending — will confirm before merge) - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups (pending — will confirm before merge) - [x] I will address all Greptile and reviewer comments before requesting merge
4.0 KiB
Release Channels
Paperclip ships on four channels. Pick the one that matches your appetite for freshness versus stability — switching is just a matter of which version you install.
| Channel | What it is | Updates | npm | Docker |
|---|---|---|---|---|
stable |
The recommended release | every week or two | paperclipai@latest |
ghcr.io/paperclipai/paperclip:latest |
beta |
Release candidates soaking before stable | when promoted | paperclipai@beta |
ghcr.io/paperclipai/paperclip:beta |
nightly |
Yesterday's merges, smoke-tested as a unit | once a night | paperclipai@nightly |
ghcr.io/paperclipai/paperclip:nightly |
canary |
Every merge to master, as it happens |
many times a day | paperclipai@canary |
ghcr.io/paperclipai/paperclip:canary |
Choosing a channel
stable is the right choice for almost everyone. It only moves when a release has been explicitly vetted and promoted by a maintainer, and every stable must first soak as a beta for at least 3 days.
beta is for people who want the next stable early. A beta is a nightly that a maintainer hand-picked and explicitly promoted behind an approval gate, and it is re-smoked after publishing. Betas are the release candidates: what you run on beta today is what stable becomes a few days later.
nightly is for people who want new features quickly but not the churn of tracking every merge. Once a night, the newest master build that published green is run through the full release smoke suite (real Docker container, real onboarding flow, browser-driven). Only if that passes does it ship as the nightly. If smoke fails, there is no nightly that night — the channel never ships a build that failed its checks.
canary is the bleeding edge: it publishes on every merge to master.
It is primarily the lane that continuously exercises our release automation,
but it's available to anyone who wants the newest bits and accepts the risk.
Installing from a channel
npm / npx:
npx paperclipai@latest onboard # stable
npx paperclipai@beta onboard
npx paperclipai@nightly onboard
npx paperclipai@canary onboard
Docker:
docker pull ghcr.io/paperclipai/paperclip:latest # stable
docker pull ghcr.io/paperclipai/paperclip:beta
docker pull ghcr.io/paperclipai/paperclip:nightly
docker pull ghcr.io/paperclipai/paperclip:canary
Every image is also published as :sha-<short-sha> for exact pinning, and
stable images additionally get :YYYY.MDD.P version tags.
Seeing where you are
npx paperclipai channels
prints every channel with the version it currently resolves to, the install
command for each, and which channel your install follows (with --json for
scripting).
Switching channels
Channel choice is per-install: install from a different tag and you're on that channel. Moving forward (stable → nightly) is always safe. Moving backward (nightly → stable) can mean running an older schema than your data was created with — treat a downgrade like a restore and keep a backup of your data directory before switching down.
Reading version strings
The version tells you which channel a build came from:
2026.807.0— stable, published Aug 7 20262026.807.0-beta.0— beta promoted on Aug 7 20262026.807.0-nightly.0— nightly cut on Aug 7 20262026.807.0-canary.4— the fifth canary for the Aug 7 line
Each promotion republishes the exact source commit of the previous lane's build: a nightly shares its source SHA with a canary, and a beta with a nightly. The version dates the promotion, and the shared SHA is visible in the release job summaries and as git tags on the commit.
One quirk to be aware of: npm's semver ordering compares prerelease names
alphabetically, so -beta.N sorts below -canary.N, which sorts below
-nightly.N for the same base version. This never matters when installing by
dist-tag (the recommended way), only if you write version ranges by hand.
For maintainers
The publishing mechanics, promotion flow, and release checklist live in
RELEASING.md.