The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
chore: formalize release workflow
Dottaa7cfd9f24b86
diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlnew file mode 100644index 0000000000..492b02b5c2--- /dev/null+++ b/.github/workflows/release.yml@@ -0,0 +1,132 @@+name: Release++on:+ workflow_dispatch:+ inputs:+ channel:+ description: Release channel+ required: true+ type: choice+ default: canary+ options:+ - canary+ - stable+ bump:+ description: Semantic version bump+ required: true+ type: choice+ default: patch+ options:+ - patch+ - minor+ - major+ dry_run:+ description: Preview the release without publishing+ required: true+ type: boolean+ default: true++concurrency:+ group: release-${{ github.ref }}+ cancel-in-progress: false++jobs:+ verify:+ if: github.ref == 'refs/heads/master'+ runs-on: ubuntu-latest+ timeout-minutes: 30+ permissions:+ contents: read++ steps:+ - name: Checkout repository+ uses: actions/checkout@v4+ with:+ fetch-depth: 0++ - name: Setup pnpm+ uses: pnpm/action-setup@v4+ with:+ version: 9.15.4++ - name: Setup Node.js+ uses: actions/setup-node@v4+ with:+ node-version: 24+ cache: pnpm++ - name: Install dependencies+ run: pnpm install --no-frozen-lockfile++ - name: Typecheck+ run: pnpm -r typecheck++ - name: Run tests+ run: pnpm test:run++ - name: Build+ run: pnpm build++ publish:+ if: github.ref == 'refs/heads/master'+ needs: verify+ runs-on: ubuntu-latest+ timeout-minutes: 45+ environment: npm-release+ permissions:+ contents: write+ id-token: write++ steps:+ - name: Checkout repository+ uses: actions/checkout@v4+ with:+ fetch-depth: 0++ - name: Setup pnpm+ uses: pnpm/action-setup@v4+ with:+ version: 9.15.4++ - name: Setup Node.js+ uses: actions/setup-node@v4+ with:+ node-version: 24+ cache: pnpm++ - name: Install dependencies+ run: pnpm install --no-frozen-lockfile++ - name: Configure git author+ run: |+ git config user.name "github-actions[bot]"+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"++ - name: Run release script+ env:+ GITHUB_ACTIONS: "true"+ run: |+ args=("${{ inputs.bump }}")+ if [ "${{ inputs.channel }}" = "canary" ]; then+ args+=("--canary")+ fi+ if [ "${{ inputs.dry_run }}" = "true" ]; then+ args+=("--dry-run")+ fi+ ./scripts/release.sh "${args[@]}"++ - name: Push stable release commit and tag+ if: inputs.channel == 'stable' && !inputs.dry_run+ run: git push origin HEAD:master --follow-tags++ - name: Create GitHub Release+ if: inputs.channel == 'stable' && !inputs.dry_run+ env:+ GH_TOKEN: ${{ github.token }}+ run: |+ version="$(git tag --points-at HEAD | grep '^v' | head -1 | sed 's/^v//')"+ if [ -z "$version" ]; then+ echo "Error: no v* tag points at HEAD after stable release." >&2+ exit 1+ fi+ ./scripts/create-github-release.sh "$version"diff --git a/doc/PUBLISHING.md b/doc/PUBLISHING.mdindex 29ac729159..fad105d671 100644--- a/doc/PUBLISHING.md+++ b/doc/PUBLISHING.md@@ -1,196 +1,119 @@# Publishing to npm-This document covers how to build and publish the `paperclipai` CLI package to npm.+Low-level reference for how Paperclip packages are built for npm.-## Prerequisites+For the maintainer release workflow, use [doc/RELEASING.md](RELEASING.md). This document is only about packaging internals and the scripts that produce publishable artifacts.-- Node.js 20+-- pnpm 9.15+-- An npm account with publish access to the `paperclipai` package-- Logged in to npm: `npm login`+## Current Release Entry Points-## One-Command Publish+Use these scripts instead of older one-off publish commands:-The fastest way to publish — bumps version, builds, publishes, restores, commits, and tags in one shot:+- [`scripts/release.sh`](../scripts/release.sh) for canary and stable npm publishes+- [`scripts/rollback-latest.sh`](../scripts/rollback-latest.sh) to repoint `latest` during rollback+- [`scripts/create-github-release.sh`](../scripts/create-github-release.sh) after a stable push-```bash-./scripts/bump-and-publish.sh patch # 0.1.1 → 0.1.2-./scripts/bump-and-publish.sh minor # 0.1.1 → 0.2.0-./scripts/bump-and-publish.sh major # 0.1.1 → 1.0.0-./scripts/bump-and-publish.sh 2.0.0 # set explicit version-./scripts/bump-and-publish.sh patch --dry-run # everything except npm publish-```+## Why the CLI needs special packaging-The script runs all 6 steps below in order. It requires a clean working tree and an active `npm login` session (unless `--dry-run`). After it finishes, push:+The CLI package, `paperclipai`, imports code from workspace packages such as:-```bash-git push && git push origin v<version>-```+- `@paperclipai/server`+- `@paperclipai/db`+- `@paperclipai/shared`+- adapter packages under `packages/adapters/`-## Manual Step-by-Step+Those workspace references use `workspace:*` during development. npm cannot install those references directly for end users, so the release build has to transform the CLI into a publishable standalone package.-If you prefer to run each step individually:+## `build-npm.sh`-### Quick Reference+Run:```bash-# Bump version-./scripts/version-bump.sh patch # 0.1.0 → 0.1.1--# Build./scripts/build-npm.sh--# Preview what will be published-cd cli && npm pack --dry-run--# Publish-cd cli && npm publish --access public--# Restore dev package.json-mv cli/package.dev.json cli/package.json```-## Step-by-Step+This script does six things:-### 1. Bump the version+1. Runs the forbidden token check unless `--skip-checks` is supplied+2. Runs `pnpm -r typecheck`+3. Bundles the CLI entrypoint with esbuild into `cli/dist/index.js`+4. Verifies the bundled entrypoint with `node --check`+5. Rewrites `cli/package.json` into a publishable npm manifest and stores the dev copy as `cli/package.dev.json`+6. Copies the repo `README.md` into `cli/README.md` for npm package metadata-```bash-./scripts/version-bump.sh <patch|minor|major|X.Y.Z>-```+`build-npm.sh` is used by the release script so that npm users install a real package rather than unresolved workspace dependencies.-This updates the version in two places:+## Publishable CLI layout-- `cli/package.json` — the source of truth-- `cli/src/index.ts` — the Commander `.version()` call+During development, [`cli/package.json`](../cli/package.json) contains workspace references.-Examples:+During release preparation:-```bash-./scripts/version-bump.sh patch # 0.1.0 → 0.1.1-./scripts/version-bump.sh minor # 0.1.0 → 0.2.0-./scripts/version-bump.sh major # 0.1.0 → 1.0.0-./scripts/version-bump.sh 1.2.3 # set explicit version-```+- `cli/package.json` becomes a publishable manifest with external npm dependency ranges+- `cli/package.dev.json` stores the development manifest temporarily+- `cli/dist/index.js` contains the bundled CLI entrypoint+- `cli/README.md` is copied in for npm metadata-### 2. Build+After release finalization, the release script restores the development manifest and removes the temporary README copy.-```bash-./scripts/build-npm.sh-```+## Package discovery-The build script runs five steps:+The release tooling scans the workspace for public packages under:-1. **Forbidden token check** — scans tracked files for tokens listed in `.git/hooks/forbidden-tokens.txt`. If the file is missing (e.g. on a contributor's machine), the check passes silently. The script never prints which tokens it's searching for.-2. **TypeScript type-check** — runs `pnpm -r typecheck` across all workspace packages.-3. **esbuild bundle** — bundles the CLI entry point (`cli/src/index.ts`) and all workspace package code (`@paperclipai/*`) into a single file at `cli/dist/index.js`. External npm dependencies (express, postgres, etc.) are kept as regular imports.-4. **Generate publishable package.json** — replaces `cli/package.json` with a version that has real npm dependency ranges instead of `workspace:*` references (see [package.dev.json](#packagedevjson) below).-5. **Summary** — prints the bundle size and next steps.+- `packages/`+- `server/`+- `cli/`-To skip the forbidden token check (e.g. in CI without the token list):+`ui/` remains ignored for npm publishing because it is private.-```bash-./scripts/build-npm.sh --skip-checks-```+This matters because all public packages are versioned and published together as one release unit.-### 3. Preview (optional)+## Canary packaging model-See what npm will publish:+Canaries are published as semver prereleases such as:-```bash-cd cli && npm pack --dry-run-```+- `1.2.3-canary.0`+- `1.2.3-canary.1`-### 4. Publish+They are published under the npm dist-tag `canary`.-```bash-cd cli && npm publish --access public-```+This means:-### 5. Restore dev package.json+- `npx paperclipai@canary onboard` can install them explicitly+- `npx paperclipai onboard` continues to resolve `latest`+- the stable changelog can stay at `releases/v1.2.3.md`-After publishing, restore the workspace-aware `package.json`:+## Stable packaging model-```bash-mv cli/package.dev.json cli/package.json-```+Stable releases publish normal semver versions such as `1.2.3` under the npm dist-tag `latest`.-### 6. Commit and tag+The stable publish flow also creates the local release commit and git tag. Pushing the commit/tag and creating the GitHub Release happen afterward as separate maintainer steps.-```bash-git add cli/package.json cli/src/index.ts-git commit -m "chore: bump version to X.Y.Z"-git tag vX.Y.Z-```+## Rollback model-## package.dev.json+Rollback does not unpublish packages.-During development, `cli/package.json` contains `workspace:*` references like:--```json-{- "dependencies": {- "@paperclipai/server": "workspace:*",- "@paperclipai/db": "workspace:*"- }-}-```+Instead, the maintainer should move the `latest` dist-tag back to the previous good stable version with:-These tell pnpm to resolve those packages from the local monorepo. This is great for development but **npm doesn't understand `workspace:*`** — publishing with these references would cause install failures for users.--The build script solves this with a two-file swap:--1. **Before building:** `cli/package.json` has `workspace:*` refs (the dev version).-2. **During build (`build-npm.sh` step 4):**- - The dev `package.json` is copied to `package.dev.json` as a backup.- - `generate-npm-package-json.mjs` reads every workspace package's `package.json`, collects all their external npm dependencies, and writes a new `cli/package.json` with those real dependency ranges — no `workspace:*` refs.-3. **After publishing:** you restore the dev version with `mv package.dev.json package.json`.--The generated publishable `package.json` looks like:--```json-{- "name": "paperclipai",- "version": "0.1.0",- "bin": { "paperclipai": "./dist/index.js" },- "dependencies": {- "express": "^5.1.0",- "postgres": "^3.4.5",- "commander": "^13.1.0"- }-}+```bash+./scripts/rollback-latest.sh <stable-version>```-`package.dev.json` is listed in `.gitignore` — it only exists temporarily on disk during the build/publish cycle.--## How the bundle works--The CLI is a monorepo package that imports code from `@paperclipai/server`, `@paperclipai/db`, `@paperclipai/shared`, and several adapter packages. These workspace packages don't exist on npm.--**esbuild** bundles all workspace TypeScript code into a single `dist/index.js` file (~250kb). External npm packages (express, postgres, zod, etc.) are left as normal `import` statements — they get installed by npm when a user runs `npx paperclipai onboard`.+That keeps history intact while restoring the default install path quickly.-The esbuild configuration lives at `cli/esbuild.config.mjs`. It automatically reads every workspace package's `package.json` to determine which dependencies are external (real npm packages) vs. internal (workspace code to bundle).+## Notes for CI-## Forbidden token enforcement+The repo includes a manual GitHub Actions release workflow at [`.github/workflows/release.yml`](../.github/workflows/release.yml).-The build process includes the same forbidden-token check used by the git pre-commit hook. This catches any accidentally committed tokens before they reach npm.+Recommended CI release setup:-- Token list: `.git/hooks/forbidden-tokens.txt` (one token per line, `#` comments supported)-- The file lives inside `.git/` and is never committed-- If the file is missing, the check passes — contributors without the list can still build-- The script never prints which tokens are being searched for-- Matches are printed so you know which files to fix, but not which token triggered it--Run the check standalone:--```bash-pnpm check:tokens-```+- use npm trusted publishing via GitHub OIDC+- require approval through the `npm-release` environment+- run releases from `master`+- use canary first, then stable-## npm scripts reference+## Related Files-| Script | Command | Description |-|---|---|---|-| `bump-and-publish` | `pnpm bump-and-publish <type>` | One-command bump + build + publish + commit + tag |-| `build:npm` | `pnpm build:npm` | Full build (check + typecheck + bundle + package.json) |-| `version:bump` | `pnpm version:bump <type>` | Bump CLI version |-| `check:tokens` | `pnpm check:tokens` | Run forbidden token check only |+- [`scripts/build-npm.sh`](../scripts/build-npm.sh)+- [`scripts/generate-npm-package-json.mjs`](../scripts/generate-npm-package-json.mjs)+- [`cli/esbuild.config.mjs`](../cli/esbuild.config.mjs)+- [`doc/RELEASING.md`](RELEASING.md)diff --git a/doc/RELEASING.md b/doc/RELEASING.mdnew file mode 100644index 0000000000..cab82cbea8--- /dev/null+++ b/doc/RELEASING.md@@ -0,0 +1,437 @@+# Releasing Paperclip++Maintainer runbook for shipping a full Paperclip release across npm, GitHub, and the website-facing changelog surface.++This document is intentionally practical:++- TL;DR command sequences are at the top.+- Detailed checklists come next.+- Motivation, failure handling, and rollback playbooks follow after that.++## Release Surfaces++Every Paperclip release has four separate surfaces:++1. **Verification** — the exact git SHA must pass typecheck, tests, and build.+2. **npm** — `paperclipai` and the public workspace packages are published.+3. **GitHub** — the stable release gets a git tag and a GitHub Release.+4. **Website / announcements** — the stable changelog is published externally and announced.++Treat those as related but separate. npm can succeed while the GitHub Release is still pending. GitHub can be correct while the website changelog is stale. A maintainer release is done only when all four surfaces are handled.++## TL;DR++### Canary release++Use this when you want an installable prerelease without changing `latest`.++```bash+# 0. Start clean+git status --short++# 1. Verify the candidate SHA+pnpm -r typecheck+pnpm test:run+pnpm build++# 2. Draft or update the stable changelog+# releases/vX.Y.Z.md++# 3. Preview the canary release+./scripts/release.sh patch --canary --dry-run++# 4. Publish the canary+./scripts/release.sh patch --canary++# 5. Smoke test what users will actually install+PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh++# Users install with:+npx paperclipai@canary onboard+```++Result:++- npm gets a prerelease such as `1.2.3-canary.0` under dist-tag `canary`+- `latest` is unchanged+- no git tag is created+- no GitHub Release is created+- the working tree returns to clean after the script finishes++### Stable release++Use this only after the canary SHA is good enough to become the public default.++```bash+# 0. Start from the vetted commit+git checkout master+git pull+git status --short++# 1. Verify again on the exact release SHA+pnpm -r typecheck+pnpm test:run+pnpm build++# 2. Confirm the stable changelog exists+ls releases/v*.md++# 3. Preview the stable publish+./scripts/release.sh patch --dry-run++# 4. Publish the stable release to npm and create the local release commit + tag+./scripts/release.sh patch++# 5. Push the release commit and tag+git push origin HEAD:master --follow-tags++# 6. Create or update the GitHub Release from the pushed tag+./scripts/create-github-release.sh X.Y.Z+```++Result:++- npm gets stable `X.Y.Z` under dist-tag `latest`+- a local git commit and tag `vX.Y.Z` are created+- after push, GitHub gets the matching Release+- the website and announcement steps still need to be handled manually++### Emergency rollback++If `latest` is broken after publish, repoint it to the last known good stable version first, then work on the fix.++```bash+# Preview+./scripts/rollback-latest.sh X.Y.Z --dry-run++# Roll back latest for every public package+./scripts/rollback-latest.sh X.Y.Z+```++This does **not** unpublish anything. It only moves the `latest` dist-tag back to the last good stable release.++### GitHub Actions release++There is also a manual workflow at [`.github/workflows/release.yml`](../.github/workflows/release.yml). It is designed for npm trusted publishing via GitHub OIDC instead of long-lived npm tokens.++Use it from the Actions tab:++1. Choose `Release`+2. Choose `channel`: `canary` or `stable`+3. Choose `bump`: `patch`, `minor`, or `major`+4. Choose whether this is a `dry_run`+5. Run it from `master`++The workflow:++- reruns `typecheck`, `test:run`, and `build`+- gates publish behind the `npm-release` environment+- can publish canaries without touching `latest`+- can publish stable, push the release commit and tag, and create the GitHub Release++## Release Checklist++### Before any publish++- [ ] The working tree is clean, including untracked files+- [ ] The target branch and SHA are the ones you actually want to release+- [ ] The required verification gate passed on that exact SHA+- [ ] The bump type is correct for the user-visible impact+- [ ] The stable changelog file exists or is ready to be written at `releases/vX.Y.Z.md`+- [ ] You know which previous stable version you would roll back to if needed++### Before a canary++- [ ] You are intentionally testing something that should be installable before it becomes default+- [ ] You are comfortable with users installing it via `npx paperclipai@canary onboard`+- [ ] You understand that each canary is a new immutable npm version such as `1.2.3-canary.1`++### Before a stable++- [ ] The candidate has already passed smoke testing+- [ ] The changelog should be the stable version only, for example `v1.2.3`+- [ ] You are ready to push the release commit and tag immediately after npm publish+- [ ] You are ready to create the GitHub Release immediately after the push+- [ ] You have a post-release website / announcement plan++### After a stable++- [ ] `npm view paperclipai@latest version` matches the new stable version+- [ ] The git tag exists on GitHub+- [ ] The GitHub Release exists and uses `releases/vX.Y.Z.md`+- [ ] The website changelog is updated+- [ ] Any announcement copy matches the shipped release, not the canary++## Verification Gate++The repository standard is:++```bash+pnpm -r typecheck+pnpm test:run+pnpm build+```++This matches [`.github/workflows/pr-verify.yml`](../.github/workflows/pr-verify.yml). Run it before claiming a release candidate is ready.++## Versioning Policy++### Stable versions++Stable releases use normal semver:++- `patch` for bug fixes+- `minor` for additive features, endpoints, and additive migrations+- `major` for destructive migrations, removed APIs, or other breaking behavior++### Canary versions++Canaries are semver prereleases of the **intended stable version**:++- `1.2.3-canary.0`+- `1.2.3-canary.1`+- `1.2.3-canary.2`++That gives you three useful properties:++1. Users can install the prerelease explicitly with `@canary`+2. `latest` stays safe+3. The stable changelog can remain just `v1.2.3`++We do **not** create separate changelog files for canary versions.++## Changelog Policy++The maintainer changelog source of truth is:++- `releases/vX.Y.Z.md`++That file is for the eventual stable release. It should not include `-canary` in the filename or heading.++Recommended structure:++- `Breaking Changes` when needed+- `Highlights`+- `Improvements`+- `Fixes`+- `Upgrade Guide` when needed++Package-level `CHANGELOG.md` files are generated as part of the release mechanics. They are not the main release narrative.++## Detailed Workflow++### 1. Decide the bump++Review the range since the last stable tag:++```bash+LAST_TAG=$(git tag --list 'v*' --sort=-version:refname | head -1)+git log "${LAST_TAG}..HEAD" --oneline --no-merges+git diff --name-only "${LAST_TAG}..HEAD" -- packages/db/src/migrations/+git diff "${LAST_TAG}..HEAD" -- packages/db/src/schema/+git log "${LAST_TAG}..HEAD" --format="%s" | grep -E 'BREAKING CHANGE|BREAKING:|^[a-z]+!:' || true+```++Use the higher bump if there is any doubt.++### 2. Write the stable changelog first++Create or update:++```bash+releases/vX.Y.Z.md+```++This is deliberate. The release notes should describe the stable story, not the canary mechanics.++### 3. Publish one or more canaries++Run:++```bash+./scripts/release.sh <patch|minor|major> --canary+```++What the script does:++1. Verifies the working tree is clean+2. Computes the intended stable version from the last stable tag+3. Computes the next canary ordinal from npm+4. Versions the public packages to `X.Y.Z-canary.N`+5. Builds the workspace and publishable CLI+6. Publishes to npm under dist-tag `canary`+7. Cleans up the temporary versioning state so your branch returns to clean++This means the script is safe to repeat as many times as needed while iterating:++- `1.2.3-canary.0`+- `1.2.3-canary.1`+- `1.2.3-canary.2`++The target stable release can still remain `1.2.3`.++### 4. Smoke test the canary++Run the actual install path in Docker:++```bash+PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh+```++Minimum checks:++- [ ] `npx paperclipai@canary onboard` installs+- [ ] onboarding completes without crashes+- [ ] the server boots+- [ ] the UI loads+- [ ] basic company creation and dashboard load work++### 5. Publish stable from the vetted commit++Once the candidate SHA is good, run the stable flow on that exact commit:++```bash+./scripts/release.sh <patch|minor|major>+```++What the script does:++1. Verifies the working tree is clean+2. Versions the public packages to the stable semver+3. Builds the workspace and CLI publish bundle+4. Publishes to npm under `latest`+5. Restores temporary publish artifacts+6. Creates the local release commit and git tag++What it does **not** do:++- it does not push for you+- it does not update the website+- it does not announce the release for you++### 6. Push the release and create the GitHub Release++After a stable publish succeeds:++```bash+git push origin HEAD:master --follow-tags+./scripts/create-github-release.sh X.Y.Z+```++The GitHub release notes come from:++- `releases/vX.Y.Z.md`++### 7. Complete the external surfaces++After GitHub is correct:++- publish the changelog on the website+- write the announcement copy+- ensure public docs and install guidance point to the stable version++## GitHub Actions and npm Trusted Publishing++If you want GitHub to own the actual npm publish, use [`.github/workflows/release.yml`](../.github/workflows/release.yml) together with npm trusted publishing.++Recommended setup:++1. Configure the GitHub Actions workflow as a trusted publisher for **every public package** on npm+2. Use the `npm-release` GitHub environment with required reviewers+3. Run stable publishes from `master` only+4. Keep the workflow manual via `workflow_dispatch`++Why this is the right shape:++- no long-lived npm token needs to live in GitHub secrets+- reviewers can approve the publish step at the environment gate+- the workflow reruns verification on the release SHA before publish+- stable and canary use the same mechanics++## Failure Playbooks++### If the canary fails before publish++Nothing shipped. Fix the code and rerun the canary workflow.++### If the canary publishes but the smoke test fails++Do **not** publish stable.++Instead:++1. Fix the issue+2. Publish another canary+3. Re-run smoke testing++The canary version number will increase, but the stable target version can remain the same.++### If the stable npm publish succeeds but push fails++This is a partial release. npm is already live.++Do this immediately:++1. Fix the git issue+2. Push the release commit and tag from the same checkout+3. Create the GitHub Release++Do **not** publish the same version again.++### If the stable release is bad after `latest` moves++Use the rollback script first:++```bash+./scripts/rollback-latest.sh <last-good-version>+```++Then:++1. open an incident note or maintainer comment+2. fix forward on a new patch release+3. update the changelog / release notes if the user-facing guidance changed++### If the GitHub Release is wrong++Edit it by re-running:++```bash+./scripts/create-github-release.sh X.Y.Z+```++This updates the release notes if the GitHub Release already exists.++### If the website changelog is wrong++Fix the website independently. Do not republish npm just to repair the website surface.++## Rollback Strategy++The default rollback strategy is **dist-tag rollback, then fix forward**.++Why:++- npm versions are immutable+- users need `npx paperclipai onboard` to recover quickly+- moving `latest` back is faster and safer than trying to delete history++Rollback procedure:++1. identify the last known good stable version+2. run `./scripts/rollback-latest.sh <version>`+3. verify `npm view paperclipai@latest version`+4. fix forward with a new stable release++## Scripts Reference++- [`scripts/release.sh`](../scripts/release.sh) — stable and canary npm publish flow+- [`scripts/create-github-release.sh`](../scripts/create-github-release.sh) — create or update the GitHub Release after push+- [`scripts/rollback-latest.sh`](../scripts/rollback-latest.sh) — repoint `latest` to the last good stable release+- [`scripts/docker-onboard-smoke.sh`](../scripts/docker-onboard-smoke.sh) — Docker smoke test for the installed CLI++## Related Docs++- [doc/PUBLISHING.md](PUBLISHING.md) — low-level npm build and packaging internals+- [skills/release/SKILL.md](../skills/release/SKILL.md) — agent release coordination workflow+- [skills/release-changelog/SKILL.md](../skills/release-changelog/SKILL.md) — stable changelog drafting workflowdiff --git a/package.json b/package.jsonindex e19fb78540..737438eceb 100644--- a/package.json+++ b/package.json@@ -19,6 +19,8 @@"paperclipai": "node cli/node_modules/tsx/dist/cli.mjs cli/src/index.ts","build:npm": "./scripts/build-npm.sh","release": "./scripts/release.sh",+ "release:github": "./scripts/create-github-release.sh",+ "release:rollback": "./scripts/rollback-latest.sh","changeset": "changeset","version-packages": "changeset version","check:tokens": "node scripts/check-forbidden-tokens.mjs",diff --git a/scripts/create-github-release.sh b/scripts/create-github-release.shnew file mode 100755index 0000000000..4d1d0789c9--- /dev/null+++ b/scripts/create-github-release.sh@@ -0,0 +1,86 @@+#!/usr/bin/env bash+set -euo pipefail++REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"++dry_run=false+version=""++usage() {+ cat <<'EOF'+Usage:+ ./scripts/create-github-release.sh <version> [--dry-run]++Examples:+ ./scripts/create-github-release.sh 1.2.3+ ./scripts/create-github-release.sh 1.2.3 --dry-run++Notes:+ - Run this after pushing the release commit and tag.+ - If the release already exists, this script updates its title and notes.+EOF+}++while [ $# -gt 0 ]; do+ case "$1" in+ --dry-run) dry_run=true ;;+ -h|--help)+ usage+ exit 0+ ;;+ *)+ if [ -n "$version" ]; then+ echo "Error: only one version may be provided." >&2+ exit 1+ fi+ version="$1"+ ;;+ esac+ shift+done++if [ -z "$version" ]; then+ usage+ exit 1+fi++if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then+ echo "Error: version must be a stable semver like 1.2.3." >&2+ exit 1+fi++tag="v$version"+notes_file="$REPO_ROOT/releases/${tag}.md"++if ! command -v gh >/dev/null 2>&1; then+ echo "Error: gh CLI is required to create GitHub releases." >&2+ exit 1+fi++if [ ! -f "$notes_file" ]; then+ echo "Error: release notes file not found at $notes_file." >&2+ exit 1+fi++if ! git -C "$REPO_ROOT" rev-parse "$tag" >/dev/null 2>&1; then+ echo "Error: local git tag $tag does not exist." >&2+ exit 1+fi++if [ "$dry_run" = true ]; then+ echo "[dry-run] gh release create $tag --title $tag --notes-file $notes_file"+ exit 0+fi++if ! git -C "$REPO_ROOT" ls-remote --exit-code --tags origin "refs/tags/$tag" >/dev/null 2>&1; then+ echo "Error: remote tag $tag was not found on origin. Push the release commit and tag first." >&2+ exit 1+fi++if gh release view "$tag" >/dev/null 2>&1; then+ gh release edit "$tag" --title "$tag" --notes-file "$notes_file"+ echo "Updated GitHub Release $tag"+else+ gh release create "$tag" --title "$tag" --notes-file "$notes_file"+ echo "Created GitHub Release $tag"+fidiff --git a/scripts/release.sh b/scripts/release.shindex 3668d87c84..4908912cf9 100755--- a/scripts/release.sh+++ b/scripts/release.sh@@ -1,420 +1,460 @@#!/usr/bin/env bashset -euo pipefail-# release.sh — One-command version bump, build, and publish via Changesets.+# release.sh — Prepare and publish a Paperclip release.#-# Usage:-# ./scripts/release.sh patch # 0.2.0 → 0.2.1-# ./scripts/release.sh minor # 0.2.0 → 0.3.0-# ./scripts/release.sh major # 0.2.0 → 1.0.0-# ./scripts/release.sh patch --dry-run # everything except npm publish-# ./scripts/release.sh patch --canary # publish under @canary tag, no commit/tag-# ./scripts/release.sh patch --canary --dry-run-# ./scripts/release.sh --promote 0.2.8 # promote canary to @latest + commit/tag-# ./scripts/release.sh --promote 0.2.8 --dry-run+# Stable release:+# ./scripts/release.sh patch+# ./scripts/release.sh minor --dry-run#-# Steps (normal):-# 1. Preflight checks (clean tree, npm login)-# 2. Auto-create a changeset for all public packages-# 3. Run changeset version (bumps versions, generates CHANGELOGs)-# 4. Build all packages-# 5. Build CLI bundle (esbuild)-# 6. Publish to npm via changeset publish (unless --dry-run)-# 7. Commit and tag+# Canary release:+# ./scripts/release.sh patch --canary+# ./scripts/release.sh minor --canary --dry-run#-# --canary: Steps 1-5 unchanged, Step 6 publishes with --tag canary, Step 7 skipped.-# --promote: Skips Steps 1-6, promotes canary to latest, then commits and tags.+# Canary releases publish prerelease versions such as 1.2.3-canary.0 under the+# npm dist-tag "canary". Stable releases publish 1.2.3 under "latest".REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"CLI_DIR="$REPO_ROOT/cli"--# ── Helper: create GitHub Release ────────────────────────────────────────────-create_github_release() {- local version="$1"- local is_dry_run="$2"- local release_notes="$REPO_ROOT/releases/v${version}.md"-- if [ "$is_dry_run" = true ]; then- echo " [dry-run] gh release create v$version"- return- fi-- if ! command -v gh &>/dev/null; then- echo " ⚠ gh CLI not found — skipping GitHub Release"- return- fi-- local gh_args=(gh release create "v$version" --title "v$version")- if [ -f "$release_notes" ]; then- gh_args+=(--notes-file "$release_notes")- else- gh_args+=(--generate-notes)- fi-- if "${gh_args[@]}"; then- echo " ✓ Created GitHub Release v$version"- else- echo " ⚠ GitHub Release creation failed (non-fatal)"- fi-}--# ── Parse args ────────────────────────────────────────────────────────────────+TEMP_CHANGESET_FILE="$REPO_ROOT/.changeset/release-bump.md"+TEMP_PRE_FILE="$REPO_ROOT/.changeset/pre.json"dry_run=falsecanary=false-promote=false-promote_version=""bump_type=""+cleanup_on_exit=false++usage() {+ cat <<'EOF'+Usage:+ ./scripts/release.sh <patch|minor|major> [--canary] [--dry-run]++Examples:+ ./scripts/release.sh patch+ ./scripts/release.sh minor --dry-run+ ./scripts/release.sh patch --canary+ ./scripts/release.sh minor --canary --dry-run++Notes:+ - Canary publishes prerelease versions like 1.2.3-canary.0 under the npm+ dist-tag "canary".+ - Stable publishes 1.2.3 under the npm dist-tag "latest".+ - Dry runs leave the working tree clean.+EOF+}+while [ $# -gt 0 ]; docase "$1" in--dry-run) dry_run=true ;;--canary) canary=true ;;+ -h|--help)+ usage+ exit 0+ ;;--promote)- promote=true- shift- if [ $# -eq 0 ] || [[ "$1" == --* ]]; then- echo "Error: --promote requires a version argument (e.g. --promote 0.2.8)"+ echo "Error: --promote was removed. Re-run a stable release from the vetted commit instead."+ exit 1+ ;;+ *)+ if [ -n "$bump_type" ]; then+ echo "Error: only one bump type may be provided."exit 1fi- promote_version="$1"+ bump_type="$1";;- *) bump_type="$1" ;;esacshiftdone-if [ "$promote" = true ] && [ "$canary" = true ]; then- echo "Error: --canary and --promote cannot be used together"+if [[ ! "$bump_type" =~ ^(patch|minor|major)$ ]]; then+ usageexit 1fi-if [ "$promote" = false ]; then- if [ -z "$bump_type" ]; then- echo "Usage: $0 <patch|minor|major> [--dry-run] [--canary]"- echo " $0 --promote <version> [--dry-run]"- exit 1- fi-- if [[ ! "$bump_type" =~ ^(patch|minor|major)$ ]]; then- echo "Error: bump type must be patch, minor, or major (got '$bump_type')"- exit 1- fi-fi--# ── Promote mode (skips Steps 1-6) ───────────────────────────────────────────+info() {+ echo "$@"+}-if [ "$promote" = true ]; then- NEW_VERSION="$promote_version"- echo ""- echo "==> Promote mode: promoting v$NEW_VERSION from canary to latest..."-- # Get all publishable package names- PACKAGES=$(node -e "-const { readFileSync } = require('fs');-const { resolve } = require('path');-const root = '$REPO_ROOT';-const dirs = ['packages/shared', 'packages/adapter-utils', 'packages/db',- 'packages/adapters/claude-local', 'packages/adapters/codex-local', 'packages/adapters/opencode-local', 'packages/adapters/openclaw-gateway',- 'server', 'cli'];-const names = [];-for (const d of dirs) {- try {- const pkg = JSON.parse(readFileSync(resolve(root, d, 'package.json'), 'utf8'));- if (!pkg.private) names.push(pkg.name);- } catch {}+fail() {+ echo "Error: $*" >&2+ exit 1}-console.log(names.join('\n'));-")- echo ""- echo " Promoting packages to @latest:"- while IFS= read -r pkg; do- if [ "$dry_run" = true ]; then- echo " [dry-run] npm dist-tag add ${pkg}@${NEW_VERSION} latest"- else- npm dist-tag add "${pkg}@${NEW_VERSION}" latest- echo " ✓ ${pkg}@${NEW_VERSION} → latest"- fi- done <<< "$PACKAGES"-- # Restore CLI dev package.json if present+restore_publish_artifacts() {if [ -f "$CLI_DIR/package.dev.json" ]; thenmv "$CLI_DIR/package.dev.json" "$CLI_DIR/package.json"- echo " ✓ Restored workspace dependencies in cli/package.json"fi- # Remove the README copied for npm publishing- if [ -f "$CLI_DIR/README.md" ]; then- rm "$CLI_DIR/README.md"- fi-- # Remove temporary build artifacts+ rm -f "$CLI_DIR/README.md"rm -rf "$REPO_ROOT/server/ui-dist"+for pkg_dir in server packages/adapters/claude-local packages/adapters/codex-local; dorm -rf "$REPO_ROOT/$pkg_dir/skills"done+}- # Stage release files, commit, and tag- echo ""- echo " Committing and tagging v$NEW_VERSION..."- if [ "$dry_run" = true ]; then- echo " [dry-run] git add + commit + tag v$NEW_VERSION"- else- git add \- .changeset/ \- '**/CHANGELOG.md' \- '**/package.json' \- cli/src/index.ts- git commit -m "chore: release v$NEW_VERSION"- git tag "v$NEW_VERSION"- echo " ✓ Committed and tagged v$NEW_VERSION"+cleanup_release_state() {+ restore_publish_artifacts++ rm -f "$TEMP_CHANGESET_FILE" "$TEMP_PRE_FILE"++ if [ -n "$(git -C "$REPO_ROOT" status --porcelain)" ]; then+ git -C "$REPO_ROOT" restore --source=HEAD --staged --worktree .+ rm -f "$TEMP_CHANGESET_FILE" "$TEMP_PRE_FILE"fi+}- create_github_release "$NEW_VERSION" "$dry_run"+if [ "$cleanup_on_exit" = true ]; then+ trap cleanup_release_state EXIT+fi- echo ""+set_cleanup_trap() {+ cleanup_on_exit=true+ trap cleanup_release_state EXIT+}++require_clean_worktree() {+ if [ -n "$(git -C "$REPO_ROOT" status --porcelain)" ]; then+ fail "working tree is not clean. Commit, stash, or remove changes before releasing."+ fi+}++require_npm_publish_auth() {if [ "$dry_run" = true ]; then- echo "Dry run complete for promote v$NEW_VERSION."- echo " - Would promote all packages to @latest"- echo " - Would commit and tag v$NEW_VERSION"- echo " - Would create GitHub Release"- else- echo "Promoted all packages to @latest at v$NEW_VERSION"- echo ""- echo "Verify: npm view paperclipai@latest version"- echo ""- echo "To push:"- echo " git push && git push origin v$NEW_VERSION"+ returnfi- exit 0++ if npm whoami >/dev/null 2>&1; then+ info " ✓ Logged in to npm as $(npm whoami)"+ return+ fi++ if [ "${GITHUB_ACTIONS:-}" = "true" ]; then+ info " ✓ npm publish auth will be provided by GitHub Actions trusted publishing"+ return+ fi++ fail "npm publish auth is not available. Use 'npm login' locally or run from the GitHub release workflow."+}++list_public_package_info() {+ node - "$REPO_ROOT" <<'NODE'+const fs = require('fs');+const path = require('path');++const root = process.argv[2];+const roots = ['packages', 'server', 'ui', 'cli'];+const seen = new Set();+const rows = [];++function walk(relDir) {+ const absDir = path.join(root, relDir);+ const pkgPath = path.join(absDir, 'package.json');++ if (fs.existsSync(pkgPath)) {+ const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));+ if (!pkg.private) {+ rows.push([relDir, pkg.name]);+ }+ return;+ }++ if (!fs.existsSync(absDir)) {+ return;+ }++ for (const entry of fs.readdirSync(absDir, { withFileTypes: true })) {+ if (!entry.isDirectory()) continue;+ if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '.git') continue;+ walk(path.join(relDir, entry.name));+ }+}++for (const rel of roots) {+ walk(rel);+}++rows.sort((a, b) => a[0].localeCompare(b[0]));++for (const [dir, name] of rows) {+ const key = `${dir}\t${name}`;+ if (seen.has(key)) continue;+ seen.add(key);+ process.stdout.write(`${dir}\t${name}\n`);+}+NODE+}++compute_bumped_version() {+ node - "$1" "$2" <<'NODE'+const current = process.argv[2];+const bump = process.argv[3];+const match = current.match(/^(\d+)\.(\d+)\.(\d+)$/);++if (!match) {+ throw new Error(`invalid semver version: ${current}`);+}++let [major, minor, patch] = match.slice(1).map(Number);++if (bump === 'patch') {+ patch += 1;+} else if (bump === 'minor') {+ minor += 1;+ patch = 0;+} else if (bump === 'major') {+ major += 1;+ minor = 0;+ patch = 0;+} else {+ throw new Error(`unsupported bump type: ${bump}`);+}++process.stdout.write(`${major}.${minor}.${patch}`);+NODE+}++next_canary_version() {+ local stable_version="$1"+ local versions_json++ versions_json="$(npm view paperclipai versions --json 2>/dev/null || echo '[]')"++ node - "$stable_version" "$versions_json" <<'NODE'+const stable = process.argv[2];+const versionsArg = process.argv[3];++let versions = [];+try {+ const parsed = JSON.parse(versionsArg);+ versions = Array.isArray(parsed) ? parsed : [parsed];+} catch {+ versions = [];+}++const pattern = new RegExp(`^${stable.replace(/\./g, '\\.')}-canary\\.(\\d+)$`);+let max = -1;++for (const version of versions) {+ const match = version.match(pattern);+ if (!match) continue;+ max = Math.max(max, Number(match[1]));+}++process.stdout.write(`${stable}-canary.${max + 1}`);+NODE+}++replace_version_string() {+ local from_version="$1"+ local to_version="$2"++ node - "$REPO_ROOT" "$from_version" "$to_version" <<'NODE'+const fs = require('fs');+const path = require('path');++const root = process.argv[2];+const fromVersion = process.argv[3];+const toVersion = process.argv[4];++const roots = ['packages', 'server', 'ui', 'cli'];+const targets = new Set(['package.json', 'CHANGELOG.md']);+const extraFiles = [path.join('cli', 'src', 'index.ts')];++function rewriteFile(filePath) {+ if (!fs.existsSync(filePath)) return;+ const current = fs.readFileSync(filePath, 'utf8');+ if (!current.includes(fromVersion)) return;+ fs.writeFileSync(filePath, current.split(fromVersion).join(toVersion));+}++function walk(relDir) {+ const absDir = path.join(root, relDir);+ if (!fs.existsSync(absDir)) return;++ for (const entry of fs.readdirSync(absDir, { withFileTypes: true })) {+ if (entry.isDirectory()) {+ if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '.git') continue;+ walk(path.join(relDir, entry.name));+ continue;+ }++ if (targets.has(entry.name)) {+ rewriteFile(path.join(absDir, entry.name));+ }+ }+}++for (const rel of roots) {+ walk(rel);+}++for (const relFile of extraFiles) {+ rewriteFile(path.join(root, relFile));+}+NODE+}++LAST_STABLE_TAG="$(git -C "$REPO_ROOT" tag --list 'v*' --sort=-version:refname | head -1)"+CURRENT_STABLE_VERSION="${LAST_STABLE_TAG#v}"+if [ -z "$CURRENT_STABLE_VERSION" ]; then+ CURRENT_STABLE_VERSION="0.0.0"+fi++TARGET_STABLE_VERSION="$(compute_bumped_version "$CURRENT_STABLE_VERSION" "$bump_type")"+TARGET_PUBLISH_VERSION="$TARGET_STABLE_VERSION"++if [ "$canary" = true ]; then+ TARGET_PUBLISH_VERSION="$(next_canary_version "$TARGET_STABLE_VERSION")"fi-# ── Step 1: Preflight checks ─────────────────────────────────────────────────+PUBLIC_PACKAGE_INFO="$(list_public_package_info)"+PUBLIC_PACKAGE_NAMES="$(printf '%s\n' "$PUBLIC_PACKAGE_INFO" | cut -f2)"+PUBLIC_PACKAGE_DIRS="$(printf '%s\n' "$PUBLIC_PACKAGE_INFO" | cut -f1)"-echo ""-echo "==> Step 1/7: Preflight checks..."+if [ -z "$PUBLIC_PACKAGE_INFO" ]; then+ fail "no public packages were found in the workspace."+fi-if [ "$dry_run" = false ]; then- if ! npm whoami &>/dev/null; then- echo "Error: Not logged in to npm. Run 'npm login' first."- exit 1- fi- echo " ✓ Logged in to npm as $(npm whoami)"+info ""+info "==> Release plan"+info " Last stable tag: ${LAST_STABLE_TAG:-<none>}"+info " Current stable version: $CURRENT_STABLE_VERSION"+if [ "$canary" = true ]; then+ info " Target stable version: $TARGET_STABLE_VERSION"+ info " Canary version: $TARGET_PUBLISH_VERSION"+else+ info " Stable version: $TARGET_STABLE_VERSION"fi-if ! git -C "$REPO_ROOT" diff --quiet || ! git -C "$REPO_ROOT" diff --cached --quiet; then- echo "Error: Working tree has uncommitted changes. Commit or stash them first."- exit 1+info ""+info "==> Step 1/7: Preflight checks..."+require_clean_worktree+info " ✓ Working tree is clean"+require_npm_publish_auth++if [ "$dry_run" = true ] || [ "$canary" = true ]; then+ set_cleanup_trapfi-echo " ✓ Working tree is clean"--# ── Step 2: Auto-create changeset ────────────────────────────────────────────--echo ""-echo "==> Step 2/7: Creating changeset ($bump_type bump for all packages)..."--# Get all publishable (non-private) package names-PACKAGES=$(node -e "-const { readdirSync, readFileSync } = require('fs');-const { resolve } = require('path');-const root = '$REPO_ROOT';-const wsYaml = readFileSync(resolve(root, 'pnpm-workspace.yaml'), 'utf8');-const dirs = ['packages/shared', 'packages/adapter-utils', 'packages/db',- 'packages/adapters/claude-local', 'packages/adapters/codex-local', 'packages/adapters/opencode-local', 'packages/adapters/openclaw-gateway',- 'server', 'cli'];-const names = [];-for (const d of dirs) {- try {- const pkg = JSON.parse(readFileSync(resolve(root, d, 'package.json'), 'utf8'));- if (!pkg.private) names.push(pkg.name);- } catch {}-}-console.log(names.join('\n'));-")-# Write a changeset file-CHANGESET_FILE="$REPO_ROOT/.changeset/release-bump.md"+info ""+info "==> Step 2/7: Creating release changeset..."{echo "---"- while IFS= read -r pkg; do- echo "\"$pkg\": $bump_type"- done <<< "$PACKAGES"+ while IFS= read -r pkg_name; do+ [ -z "$pkg_name" ] && continue+ echo "\"$pkg_name\": $bump_type"+ done <<< "$PUBLIC_PACKAGE_NAMES"echo "---"echo ""- echo "Version bump ($bump_type)"-} > "$CHANGESET_FILE"--echo " ✓ Created changeset for $(echo "$PACKAGES" | wc -l | xargs) packages"--# ── Step 3: Version packages ─────────────────────────────────────────────────+ if [ "$canary" = true ]; then+ echo "Canary release preparation for $TARGET_STABLE_VERSION"+ else+ echo "Stable release preparation for $TARGET_STABLE_VERSION"+ fi+} > "$TEMP_CHANGESET_FILE"+info " ✓ Created release changeset for $(printf '%s\n' "$PUBLIC_PACKAGE_NAMES" | sed '/^$/d' | wc -l | xargs) packages"-echo ""-echo "==> Step 3/7: Running changeset version..."+info ""+info "==> Step 3/7: Versioning packages..."cd "$REPO_ROOT"+if [ "$canary" = true ]; then+ npx changeset pre enter canary+finpx changeset version-echo " ✓ Versions bumped and CHANGELOGs generated"-# Read the new version from the CLI package-NEW_VERSION=$(node -e "console.log(require('$CLI_DIR/package.json').version)")-echo " New version: $NEW_VERSION"--# Update the version string in cli/src/index.ts-CURRENT_VERSION_IN_SRC=$(sed -n 's/.*\.version("\([^"]*\)".*/\1/p' "$CLI_DIR/src/index.ts" | head -1)-if [ -n "$CURRENT_VERSION_IN_SRC" ] && [ "$CURRENT_VERSION_IN_SRC" != "$NEW_VERSION" ]; then- sed -i '' "s/\.version(\"$CURRENT_VERSION_IN_SRC\")/\.version(\"$NEW_VERSION\")/" "$CLI_DIR/src/index.ts"- echo " ✓ Updated cli/src/index.ts version to $NEW_VERSION"+if [ "$canary" = true ]; then+ BASE_CANARY_VERSION="${TARGET_STABLE_VERSION}-canary.0"+ if [ "$TARGET_PUBLISH_VERSION" != "$BASE_CANARY_VERSION" ]; then+ replace_version_string "$BASE_CANARY_VERSION" "$TARGET_PUBLISH_VERSION"+ fifi-# ── Step 4: Build packages ───────────────────────────────────────────────────+VERSION_IN_CLI_PACKAGE="$(node -e "console.log(require('$CLI_DIR/package.json').version)")"+if [ "$VERSION_IN_CLI_PACKAGE" != "$TARGET_PUBLISH_VERSION" ]; then+ fail "versioning drift detected. Expected $TARGET_PUBLISH_VERSION but found $VERSION_IN_CLI_PACKAGE."+fi+info " ✓ Versioned workspace to $TARGET_PUBLISH_VERSION"-echo ""-echo "==> Step 4/7: Building all packages..."+info ""+info "==> Step 4/7: Building workspace artifacts..."cd "$REPO_ROOT"--# Build packages in dependency order (excluding CLI)-pnpm --filter @paperclipai/shared build-pnpm --filter @paperclipai/adapter-utils build-pnpm --filter @paperclipai/db build-pnpm --filter @paperclipai/adapter-claude-local build-pnpm --filter @paperclipai/adapter-codex-local build-pnpm --filter @paperclipai/adapter-opencode-local build-pnpm --filter @paperclipai/adapter-openclaw-gateway build-pnpm --filter @paperclipai/server build--# Build UI and bundle into server package for static serving+pnpm buildbash "$REPO_ROOT/scripts/prepare-server-ui-dist.sh"--# Bundle skills into packages that need them (adapters + server)for pkg_dir in server packages/adapters/claude-local packages/adapters/codex-local; dorm -rf "$REPO_ROOT/$pkg_dir/skills"cp -r "$REPO_ROOT/skills" "$REPO_ROOT/$pkg_dir/skills"done-echo " ✓ All packages built (including UI + skills)"--# ── Step 5: Build CLI bundle ─────────────────────────────────────────────────+info " ✓ Workspace build complete"-echo ""-echo "==> Step 5/7: Building CLI bundle..."-cd "$REPO_ROOT"+info ""+info "==> Step 5/7: Building publishable CLI bundle...""$REPO_ROOT/scripts/build-npm.sh" --skip-checks-echo " ✓ CLI bundled"--# ── Step 6: Publish ──────────────────────────────────────────────────────────+info " ✓ CLI bundle ready"+info ""if [ "$dry_run" = true ]; then- echo ""- if [ "$canary" = true ]; then- echo "==> Step 6/7: Skipping publish (--dry-run, --canary)"- else- echo "==> Step 6/7: Skipping publish (--dry-run)"- fi- echo ""- echo " Preview what would be published:"- for dir in packages/shared packages/adapter-utils packages/db \- packages/adapters/claude-local packages/adapters/codex-local packages/adapters/opencode-local packages/adapters/openclaw-gateway \- server cli; do- echo " --- $dir ---"- cd "$REPO_ROOT/$dir"+ info "==> Step 6/7: Previewing publish payloads (--dry-run)..."+ while IFS= read -r pkg_dir; do+ [ -z "$pkg_dir" ] && continue+ info " --- $pkg_dir ---"+ cd "$REPO_ROOT/$pkg_dir"npm pack --dry-run 2>&1 | tail -3- done+ done <<< "$PUBLIC_PACKAGE_DIRS"cd "$REPO_ROOT"if [ "$canary" = true ]; then- echo ""- echo " [dry-run] Would publish with: npx changeset publish --tag canary"+ info " [dry-run] Would publish ${TARGET_PUBLISH_VERSION} under dist-tag canary"+ else+ info " [dry-run] Would publish ${TARGET_PUBLISH_VERSION} under dist-tag latest"fielse- echo ""if [ "$canary" = true ]; then- echo "==> Step 6/7: Publishing to npm (canary)..."- cd "$REPO_ROOT"+ info "==> Step 6/7: Publishing canary to npm..."npx changeset publish --tag canary- echo " ✓ Published all packages under @canary tag"+ info " ✓ Published ${TARGET_PUBLISH_VERSION} under dist-tag canary"else- echo "==> Step 6/7: Publishing to npm..."- cd "$REPO_ROOT"+ info "==> Step 6/7: Publishing stable release to npm..."npx changeset publish- echo " ✓ Published all packages"+ info " ✓ Published ${TARGET_PUBLISH_VERSION} under dist-tag latest"fifi-# ── Step 7: Restore CLI dev package.json and commit ──────────────────────────--echo ""-if [ "$canary" = true ]; then- echo "==> Step 7/7: Skipping commit and tag (canary mode — promote later)..."+info ""+if [ "$dry_run" = true ]; then+ info "==> Step 7/7: Cleaning up dry-run state..."+ info " ✓ Dry run leaves the working tree unchanged"+elif [ "$canary" = true ]; then+ info "==> Step 7/7: Cleaning up canary state..."+ info " ✓ Canary state will be discarded after publish"else- echo "==> Step 7/7: Restoring dev package.json, committing, and tagging..."-fi-cd "$REPO_ROOT"--# Restore the dev package.json (build-npm.sh backs it up)-if [ -f "$CLI_DIR/package.dev.json" ]; then- mv "$CLI_DIR/package.dev.json" "$CLI_DIR/package.json"- echo " ✓ Restored workspace dependencies in cli/package.json"-fi--# Remove the README copied for npm publishing-if [ -f "$CLI_DIR/README.md" ]; then- rm "$CLI_DIR/README.md"-fi+ info "==> Step 7/7: Finalizing stable release commit..."+ restore_publish_artifacts-# Remove temporary build artifacts before committing (these are only needed during publish)-rm -rf "$REPO_ROOT/server/ui-dist"-for pkg_dir in server packages/adapters/claude-local packages/adapters/codex-local; do- rm -rf "$REPO_ROOT/$pkg_dir/skills"-done--if [ "$canary" = false ]; then- # Stage only release-related files (avoid sweeping unrelated changes with -A)- git add \- .changeset/ \- '**/CHANGELOG.md' \- '**/package.json' \- cli/src/index.ts- git commit -m "chore: release v$NEW_VERSION"- git tag "v$NEW_VERSION"- echo " ✓ Committed and tagged v$NEW_VERSION"-fi+ git -C "$REPO_ROOT" add -u .changeset packages server cli+ if [ -f "$REPO_ROOT/releases/v${TARGET_STABLE_VERSION}.md" ]; then+ git -C "$REPO_ROOT" add "releases/v${TARGET_STABLE_VERSION}.md"+ fi-if [ "$canary" = false ]; then- create_github_release "$NEW_VERSION" "$dry_run"+ git -C "$REPO_ROOT" commit -m "chore: release v$TARGET_STABLE_VERSION"+ git -C "$REPO_ROOT" tag "v$TARGET_STABLE_VERSION"+ info " ✓ Created commit and tag v$TARGET_STABLE_VERSION"fi-# ── Done ──────────────────────────────────────────────────────────────────────--echo ""-if [ "$canary" = true ]; then- if [ "$dry_run" = true ]; then- echo "Dry run complete for canary v$NEW_VERSION."- echo " - Versions bumped, built, and previewed"- echo " - Dev package.json restored"- echo " - No commit or tag (canary mode)"- echo ""- echo "To actually publish canary, run:"- echo " ./scripts/release.sh $bump_type --canary"+info ""+if [ "$dry_run" = true ]; then+ if [ "$canary" = true ]; then+ info "Dry run complete for canary ${TARGET_PUBLISH_VERSION}."else- echo "Published canary at v$NEW_VERSION"- echo ""- echo "Verify: npm view paperclipai@canary version"- echo ""- echo "To promote to latest:"- echo " ./scripts/release.sh --promote $NEW_VERSION"+ info "Dry run complete for stable v${TARGET_STABLE_VERSION}."fi-elif [ "$dry_run" = true ]; then- echo "Dry run complete for v$NEW_VERSION."- echo " - Versions bumped, built, and previewed"- echo " - Dev package.json restored"- echo " - Commit and tag created (locally)"- echo " - Would create GitHub Release"- echo ""- echo "To actually publish, run:"- echo " ./scripts/release.sh $bump_type"+elif [ "$canary" = true ]; then+ info "Published canary ${TARGET_PUBLISH_VERSION}."+ info "Install with: npx paperclipai@canary onboard"+ info "Stable version remains: $CURRENT_STABLE_VERSION"else- echo "Published all packages at v$NEW_VERSION"- echo ""- echo "To push:"- echo " git push && git push origin v$NEW_VERSION"- echo ""- echo "GitHub Release: https://github.com/cryppadotta/paperclip/releases/tag/v$NEW_VERSION"+ info "Published stable v${TARGET_STABLE_VERSION}."+ info "Next steps:"+ info " git push origin HEAD:master --follow-tags"+ info " ./scripts/create-github-release.sh $TARGET_STABLE_VERSION"fidiff --git a/scripts/rollback-latest.sh b/scripts/rollback-latest.shnew file mode 100755index 0000000000..a00da98413--- /dev/null+++ b/scripts/rollback-latest.sh@@ -0,0 +1,111 @@+#!/usr/bin/env bash+set -euo pipefail++REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"++dry_run=false+version=""++usage() {+ cat <<'EOF'+Usage:+ ./scripts/rollback-latest.sh <stable-version> [--dry-run]++Examples:+ ./scripts/rollback-latest.sh 1.2.2+ ./scripts/rollback-latest.sh 1.2.2 --dry-run++Notes:+ - This repoints the npm dist-tag "latest" for every public package.+ - It does not unpublish anything.+EOF+}++while [ $# -gt 0 ]; do+ case "$1" in+ --dry-run) dry_run=true ;;+ -h|--help)+ usage+ exit 0+ ;;+ *)+ if [ -n "$version" ]; then+ echo "Error: only one version may be provided." >&2+ exit 1+ fi+ version="$1"+ ;;+ esac+ shift+done++if [ -z "$version" ]; then+ usage+ exit 1+fi++if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then+ echo "Error: version must be a stable semver like 1.2.2." >&2+ exit 1+fi++if [ "$dry_run" = false ] && ! npm whoami >/dev/null 2>&1; then+ echo "Error: npm publish rights are required. Run 'npm login' first." >&2+ exit 1+fi++list_public_package_names() {+ node - "$REPO_ROOT" <<'NODE'+const fs = require('fs');+const path = require('path');++const root = process.argv[2];+const roots = ['packages', 'server', 'ui', 'cli'];+const seen = new Set();++function walk(relDir) {+ const absDir = path.join(root, relDir);+ const pkgPath = path.join(absDir, 'package.json');++ if (fs.existsSync(pkgPath)) {+ const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));+ if (!pkg.private && !seen.has(pkg.name)) {+ seen.add(pkg.name);+ process.stdout.write(`${pkg.name}\n`);+ }+ return;+ }++ if (!fs.existsSync(absDir)) {+ return;+ }++ for (const entry of fs.readdirSync(absDir, { withFileTypes: true })) {+ if (!entry.isDirectory()) continue;+ if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '.git') continue;+ walk(path.join(relDir, entry.name));+ }+}++for (const rel of roots) {+ walk(rel);+}+NODE+}++package_names="$(list_public_package_names)"++if [ -z "$package_names" ]; then+ echo "Error: no public packages were found in the workspace." >&2+ exit 1+fi++while IFS= read -r package_name; do+ [ -z "$package_name" ] && continue+ if [ "$dry_run" = true ]; then+ echo "[dry-run] npm dist-tag add ${package_name}@${version} latest"+ else+ npm dist-tag add "${package_name}@${version}" latest+ echo "Updated latest -> ${package_name}@${version}"+ fi+done <<< "$package_names"diff --git a/skills/release-changelog/SKILL.md b/skills/release-changelog/SKILL.mdindex d28fa9310a..b70b97f525 100644--- a/skills/release-changelog/SKILL.md+++ b/skills/release-changelog/SKILL.md@@ -1,363 +1,140 @@---name: release-changelogdescription: >- Generate user-facing release changelogs for Paperclip. Reads git history,- merged PRs, and changeset files since the last release tag. Detects breaking- changes, categorizes changes, and outputs structured markdown to- releases/v{version}.md. Use when preparing a release or when asked to- generate a changelog.+ Generate the stable Paperclip release changelog at releases/v{version}.md by+ reading commits, changesets, and merged PR context since the last stable tag.---# Release Changelog Skill-Generate a user-facing changelog for a new Paperclip release. This skill reads-the commit history, changeset files, and merged PRs since the last release tag,-detects breaking changes, categorizes everything, and writes a structured-release notes file.+Generate the user-facing changelog for the **stable** Paperclip release.-**Output:** `releases/v{version}.md` in the repo root.-**Review required:** Always present the draft for human sign-off before-finalizing. Never auto-publish.+Output:----+- `releases/v{version}.md`++Important rule:++- even if there are canary releases such as `1.2.3-canary.0`, the changelog file stays `releases/v1.2.3.md`## Step 0 — Idempotency Check-Before generating anything, check if a changelog already exists for this version:+Before generating anything, check whether the file already exists:```bashls releases/v{version}.md 2>/dev/null```-**If the file already exists:**--1. Read the existing changelog and present it to the reviewer.-2. Ask: "A changelog for v{version} already exists. Do you want to (a) keep it- as-is, (b) regenerate from scratch, or (c) update specific sections?"-3. If the reviewer says keep it → **stop here**. Do not overwrite. This skill is- done.-4. If the reviewer says regenerate → back up the existing file to- `releases/v{version}.md.prev`, then proceed from Step 1.-5. If the reviewer says update → read the existing file, proceed through Steps- 1-4 to gather fresh data, then merge changes into the existing file rather- than replacing it wholesale. Preserve any manual edits the reviewer previously- made.--**If the file does not exist:** Proceed normally from Step 1.--**Critical rule:** This skill NEVER triggers a version bump. It only reads git-history and writes a markdown file. The `release.sh` script is the only thing-that bumps versions, and it is called separately by the `release` coordination-skill. Running this skill multiple times is always safe — worst case it-overwrites a draft changelog (with reviewer permission).+If it exists:----+1. read it first+2. present it to the reviewer+3. ask whether to keep it, regenerate it, or update specific sections+4. never overwrite it silently-## Step 1 — Determine the Release Range+## Step 1 — Determine the Stable Range-Find the last release tag and the planned version:+Find the last stable tag:```bash-# Last release tag (most recent semver tag)-git tag --sort=-version:refname | head -1-# e.g. v0.2.7--# All commits since that tag-git log v0.2.7..HEAD --oneline --no-merges+git tag --list 'v*' --sort=-version:refname | head -1+git log v{last}..HEAD --oneline --no-merges```-If no tag exists yet, use the initial commit as the base.+The planned stable version comes from one of:-The new version number comes from one of:-- An explicit argument (e.g. "generate changelog for v0.3.0")-- The bump type (patch/minor/major) applied to the last tag-- The version already set in `cli/package.json` if `scripts/release.sh` has been run+- an explicit maintainer request+- the chosen bump type applied to the last stable tag+- the release plan already agreed in `doc/RELEASING.md`----+Do not derive the changelog version from a canary tag or prerelease suffix.-## Step 2 — Gather Raw Change Data+## Step 2 — Gather the Raw Inputs-Collect changes from three sources, in priority order:+Collect release data from:-### 2a. Git Commits+1. git commits since the last stable tag+2. `.changeset/*.md` files+3. merged PRs via `gh` when available-```bash-git log v{last}..HEAD --oneline --no-merges-git log v{last}..HEAD --format="%H %s" --no-merges # full SHAs for file diffs-```--### 2b. Changeset Files--Look for unconsumed changesets in `.changeset/`:+Useful commands:```bash+git log v{last}..HEAD --oneline --no-merges+git log v{last}..HEAD --format="%H %s" --no-mergesls .changeset/*.md | grep -v README.md-```--Each changeset file has YAML frontmatter with package names and bump types-(`patch`, `minor`, `major`), followed by a description. Parse these — the bump-type is a strong categorization signal, and the description may contain-user-facing summaries.--### 2c. Merged PRs (when available)--If GitHub access is available via `gh`:--```bashgh pr list --state merged --search "merged:>={last-tag-date}" --json number,title,body,labels```-PR titles and bodies are often the best source of user-facing descriptions.-Prefer PR descriptions over raw commit messages when both are available.------## Step 3 — Detect Breaking Changes-Scan for breaking changes using these signals. **Any match flags the release as-containing breaking changes**, which affects version bump requirements and-changelog structure.+Look for:-### 3a. Migration Files+- destructive migrations+- removed or changed API fields/endpoints+- renamed or removed config keys+- `major` changesets+- `BREAKING:` or `BREAKING CHANGE:` commit signals-Check for new migration files since the last tag:+Key commands:```bashgit diff --name-only v{last}..HEAD -- packages/db/src/migrations/-```--- **New migration files exist** = DB migration required in upgrade.-- Inspect migration content: look for `DROP`, `ALTER ... DROP`, `RENAME` to- distinguish destructive vs. additive migrations.-- Additive-only migrations (new tables, new nullable columns, new indexes) are- safe but should still be mentioned.-- Destructive migrations (column drops, type changes, table drops) = breaking.--### 3b. Schema Changes--```bashgit diff v{last}..HEAD -- packages/db/src/schema/-```--Look for:-- Removed or renamed columns/tables-- Changed column types-- Removed default values or nullable constraints-- These indicate breaking DB changes even if no explicit migration file exists--### 3c. API Route Changes--```bashgit diff v{last}..HEAD -- server/src/routes/ server/src/api/+git log v{last}..HEAD --format="%s" | rg -n 'BREAKING CHANGE|BREAKING:|^[a-z]+!:' || true```-Look for:-- Removed endpoints-- Changed request/response shapes (removed fields, type changes)-- Changed authentication requirements--### 3d. Config Changes+If the requested bump is lower than the minimum required bump, flag that before the release proceeds.-```bash-git diff v{last}..HEAD -- cli/src/config/ packages/*/src/*config*-```+## Step 4 — Categorize for Users-Look for renamed, removed, or restructured configuration keys.+Use these stable changelog sections:-### 3e. Changeset Severity+- `Breaking Changes`+- `Highlights`+- `Improvements`+- `Fixes`+- `Upgrade Guide` when needed-Any `.changeset/*.md` file with a `major` bump = explicitly flagged breaking.+Exclude purely internal refactors, CI changes, and docs-only work unless they materially affect users.-### 3f. Commit Conventions+Guidelines:-Scan commit messages for:-- `BREAKING:` or `BREAKING CHANGE:` prefix-- `!` after the type in conventional commits (e.g. `feat!:`, `fix!:`)+- group related commits into one user-facing entry+- write from the user perspective+- keep highlights short and concrete+- spell out upgrade actions for breaking changes-### Version Bump Rules+## Step 5 — Write the File-| Condition | Minimum Bump |-|---|---|-| Destructive migration (DROP, RENAME) | `major` |-| Removed API endpoints or fields | `major` |-| Any `major` changeset or `BREAKING:` commit | `major` |-| New (additive) migration | `minor` |-| New features (`feat:` commits, `minor` changesets) | `minor` |-| Bug fixes only | `patch` |--If the planned bump is lower than the minimum required, **warn the reviewer**-and recommend the correct bump level.-------## Step 4 — Categorize Changes--Assign every meaningful change to one of these categories:--| Category | What Goes Here | Shows in User Notes? |-|---|---|---|-| **Breaking Changes** | Anything requiring user action to upgrade | Yes (top, with warning) |-| **Highlights** | New user-visible features, major behavioral changes | Yes (with 1-2 sentence descriptions) |-| **Improvements** | Enhancements to existing features | Yes (bullet list) |-| **Fixes** | Bug fixes | Yes (bullet list) |-| **Internal** | Refactoring, deps, CI, tests, docs | No (dev changelog only) |--### Categorization Heuristics--Use these signals to auto-categorize. When signals conflict, prefer the-higher-visibility category and flag for human review.--| Signal | Category |-|---|---|-| Commit touches migration files, schema changes | Breaking Change (if destructive) |-| Changeset marked `major` | Breaking Change |-| Commit message has `BREAKING:` or `!:` | Breaking Change |-| New UI components, new routes, new API endpoints | Highlight |-| Commit message starts with `feat:` or `add:` | Highlight or Improvement |-| Changeset marked `minor` | Highlight |-| Commit message starts with `fix:` or `bug:` | Fix |-| Changeset marked `patch` | Fix or Improvement |-| Commit message starts with `chore:`, `refactor:`, `ci:`, `test:`, `docs:` | Internal |-| PR has detailed body with user-facing description | Use PR body as the description |--### Writing Good Descriptions--- **Highlights** get 1-2 sentence descriptions explaining the user benefit.- Write from the user's perspective ("You can now..." not "Added a component that...").-- **Improvements and Fixes** are concise bullet points.-- **Breaking Changes** get detailed descriptions including what changed,- why, and what the user needs to do.-- Group related commits into a single changelog entry. Five commits implementing- one feature = one Highlight entry, not five bullets.-- Omit purely internal changes from user-facing notes entirely.-------## Step 5 — Write the Changelog--Output the changelog to `releases/v{version}.md` using this template:+Template:```markdown# v{version}> Released: {YYYY-MM-DD}-{If breaking changes detected, include this section:}-## Breaking Changes-> **Action required before upgrading.** Read the Upgrade Guide below.--- **{Breaking change title}** — {What changed and why. What the user needs to do.}-## Highlights-- **{Feature name}** — {1-2 sentence description of what it does and why it matters.}-## Improvements-- {Concise description of improvement}-## Fixes-- {Concise description of fix}-------{If breaking changes detected, include this section:}-## Upgrade Guide--### Before You Update--1. **Back up your database.**- - SQLite: `cp paperclip.db paperclip.db.backup`- - Postgres: `pg_dump -Fc paperclip > paperclip-pre-{version}.dump`-2. **Note your current version:** `paperclip --version`--### After Updating--{Specific steps: run migrations, update configs, etc.}--### Rolling Back--If something goes wrong:-1. Restore your database backup-2. `npm install @paperclipai/server@{previous-version}````-### Template Rules--- Omit any empty section entirely (don't show "## Fixes" with no bullets).-- The Breaking Changes section always comes first when present.-- The Upgrade Guide always comes last when present.-- Use `**bold**` for feature/change names, regular text for descriptions.-- Keep the entire changelog scannable — a busy user should get the gist from- headings and bold text alone.-------## Step 6 — Present for Review--After generating the draft:+Omit empty sections except `Highlights`, `Improvements`, and `Fixes`, which should usually exist.-1. **Show the full changelog** to the reviewer (CTO or whoever triggered the release).-2. **Flag ambiguous items** — commits you weren't sure how to categorize, or- items that might be breaking but aren't clearly signaled.-3. **Flag version bump mismatches** — if the planned bump is lower than what- the changes warrant.-4. **Wait for approval** before considering the changelog final.+## Step 6 — Review Before Release-If the reviewer requests edits, update `releases/v{version}.md` accordingly.+Before handing it off:-Do not proceed to publishing, website updates, or social announcements. Those-are handled by the `release` coordination skill (separate from this one).+1. confirm the heading is the stable version only+2. confirm there is no `-canary` language in the title or filename+3. confirm any breaking changes have an upgrade path+4. present the draft for human sign-off------## Directory Convention--Release changelogs live in `releases/` at the repo root:--```-releases/- v0.2.7.md- v0.3.0.md- ...-```--Each file is named `v{version}.md` matching the git tag. This directory is-committed to the repo and serves as the source of truth for release history.--The `releases/` directory should be created with a `.gitkeep` if it doesn't-exist yet.-------## Quick Reference--```bash-# Full workflow summary:--# 1. Find last tag-LAST_TAG=$(git tag --sort=-version:refname | head -1)--# 2. Commits since last tag-git log $LAST_TAG..HEAD --oneline --no-merges--# 3. Files changed (for breaking change detection)-git diff --name-only $LAST_TAG..HEAD--# 4. Migration changes specifically-git diff --name-only $LAST_TAG..HEAD -- packages/db/src/migrations/--# 5. Schema changes-git diff $LAST_TAG..HEAD -- packages/db/src/schema/--# 6. Unconsumed changesets-ls .changeset/*.md | grep -v README.md--# 7. Merged PRs (if gh available)-gh pr list --state merged --search "merged:>=$(git log -1 --format=%aI $LAST_TAG)" \- --json number,title,body,labels-```+This skill never publishes anything. It only prepares the stable changelog artifact.diff --git a/skills/release/SKILL.md b/skills/release/SKILL.mdindex 4c91fffd18..6546870471 100644--- a/skills/release/SKILL.md+++ b/skills/release/SKILL.md@@ -1,402 +1,234 @@---name: releasedescription: >- Coordinate a full Paperclip release across engineering, website publishing,- and social announcement. Use when CTO/CEO requests "do a release" or- "release vX.Y.Z". Runs pre-flight checks, generates changelog via- release-changelog, executes npm release, creates cross-project follow-up- tasks, and posts a release wrap-up.+ Coordinate a full Paperclip release across engineering verification, npm,+ GitHub, website publishing, and announcement follow-up. Use when leadership+ asks to ship a release, not merely to discuss version bumps.---# Release Coordination Skill-Run the full Paperclip release process as an organizational workflow, not just-an npm publish.+Run the full Paperclip release as a maintainer workflow, not just an npm publish.This skill coordinates:-- User-facing changelog generation (`release-changelog` skill)-- Canary publish to npm (`scripts/release.sh --canary`)-- Docker smoke test of the canary (`scripts/docker-onboard-smoke.sh`)-- Promotion to `latest` after canary is verified-- Website publishing task creation-- CMO announcement task creation-- Final release summary with links----+- stable changelog drafting via `release-changelog`+- prerelease canary publishing via `scripts/release.sh --canary`+- Docker smoke testing via `scripts/docker-onboard-smoke.sh`+- stable publishing via `scripts/release.sh`+- pushing the release commit and tag+- GitHub Release creation via `scripts/create-github-release.sh`+- website / announcement follow-up tasks## TriggerUse this skill when leadership asks for:+- "do a release"-- "release {patch|minor|major}"+- "ship the next patch/minor/major"- "release vX.Y.Z"-----## PreconditionsBefore proceeding, verify all of the following:1. `skills/release-changelog/SKILL.md` exists and is usable.-2. The `release-changelog` dependency work is complete/reviewed before running this flow.-3. App repo working tree is clean.-4. There are commits since the last release tag.-5. You have release permissions (`npm whoami` succeeds for real publish).-6. If running via Paperclip, you have issue context for posting status updates.+2. The repo working tree is clean, including untracked files.+3. There are commits since the last stable tag.+4. The release SHA has passed the verification gate or is about to.+5. npm publish rights are available locally, or the GitHub release workflow is being used with trusted publishing.+6. If running through Paperclip, you have issue context for status updates and follow-up task creation.If any precondition fails, stop and report the blocker.-----## InputsCollect these inputs up front:-- Release request source issue (if in Paperclip)-- Requested bump (`patch|minor|major`) or explicit version (`vX.Y.Z`)-- Whether this run is dry-run or live publish-- Company/project context for follow-up issue creation+- requested bump: `patch`, `minor`, or `major`+- whether this run is a dry run or live release+- whether the release is being run locally or from GitHub Actions+- release issue / company context for website and announcement follow-up----+## Step 0 — Release Model-## Step 0 — Idempotency Guards+Paperclip now uses this release model:-Each step in this skill is designed to be safely re-runnable. Before executing-any step, check whether it has already been completed:+1. Draft the **stable** changelog as `releases/vX.Y.Z.md`+2. Publish one or more **prerelease canaries** such as `X.Y.Z-canary.0`+3. Smoke test the canary via Docker+4. Publish the stable version `X.Y.Z`+5. Push the release commit and tag+6. Create the GitHub Release+7. Complete website and announcement surfaces-| Step | How to Check | If Already Done |-|---|---|---|-| Changelog | `releases/v{version}.md` exists | Read it, ask reviewer to confirm or update. Do NOT regenerate without asking. |-| Canary publish | `npm view paperclipai@{version}` succeeds | Skip canary publish. Proceed to smoke test. |-| Smoke test | Manual or scripted verification | If canary already verified, proceed to promote. |-| Promote | `git tag v{version}` exists | Skip promotion entirely. A tag means the version is already promoted to latest. |-| Website task | Search Paperclip issues for "Publish release notes for v{version}" | Skip creation. Link the existing task. |-| CMO task | Search Paperclip issues for "release announcement tweet for v{version}" | Skip creation. Link the existing task. |+Critical consequence:-**The golden rule:** If a git tag `v{version}` already exists, the release is-fully promoted. Only post-publish tasks (website, CMO, wrap-up) should proceed.-If the version exists on npm but there's no git tag, the canary was published but-not yet promoted — resume from smoke test.+- Canaries do **not** use promote-by-dist-tag anymore.+- The changelog remains stable-only. Do not create `releases/vX.Y.Z-canary.N.md`.-**Iterating on changelogs:** You can re-run this skill with an existing changelog-to refine it _before_ the npm publish step. The `release-changelog` skill has-its own idempotency check and will ask the reviewer what to do with an existing-file. This is the expected workflow for iterating on release notes.+## Step 1 — Decide the Stable Version------## Step 1 - Pre-flight and Version Decision--Run pre-flight in the App repo root:+Use the last stable tag as the base:```bash-LAST_TAG=$(git tag --sort=-version:refname | head -1)-git diff --quiet && git diff --cached --quiet-git log "${LAST_TAG}..HEAD" --oneline --no-merges | head -50-```--Then detect minimum required bump:--```bash-# migrations+LAST_TAG=$(git tag --list 'v*' --sort=-version:refname | head -1)+git log "${LAST_TAG}..HEAD" --oneline --no-mergesgit diff --name-only "${LAST_TAG}..HEAD" -- packages/db/src/migrations/--# schema deltasgit diff "${LAST_TAG}..HEAD" -- packages/db/src/schema/--# breaking commit conventionsgit log "${LAST_TAG}..HEAD" --format="%s" | rg -n 'BREAKING CHANGE|BREAKING:|^[a-z]+!:' || true```Bump policy:-- Destructive migration/API removal/major changeset/breaking commit -> `major`-- Additive migrations or clear new features -> at least `minor`-- Fixes-only -> `patch`--If requested bump is lower than required minimum, escalate bump and explain why.----+- destructive migrations, removed APIs, breaking config changes -> `major`+- additive migrations or clearly user-visible features -> at least `minor`+- fixes only -> `patch`-## Step 2 - Generate Changelog Draft+If the requested bump is too low, escalate it and explain why.-First, check if `releases/v{version}.md` already exists. If it does, the-`release-changelog` skill will detect this and ask the reviewer whether to keep,-regenerate, or update it. **Do not silently overwrite an existing changelog.**+## Step 2 — Draft the Stable Changelog-Invoke the `release-changelog` skill and produce:-- `releases/v{version}.md`-- Sections ordered as: Breaking Changes (if any), Highlights, Improvements, Fixes, Upgrade Guide (if any)+Invoke `release-changelog` and generate:-Required behavior:-- Present the draft for human review.-- Flag ambiguous categorization items.-- Flag bump mismatches before publish.-- Do not publish until reviewer confirms.+- `releases/vX.Y.Z.md`----+Rules:-## Step 3 — Publish Canary+- review the draft with a human before publish+- preserve manual edits if the file already exists+- keep the heading and filename stable-only, for example `v1.2.3`+- do not create a separate canary changelog file-The canary is the gatekeeper: every release goes to npm as a canary first. The-`latest` tag is never touched until the canary passes smoke testing.+## Step 3 — Verify the Release SHA-**Idempotency check:** Before publishing, check if this version already exists-on npm:+Run the standard gate:```bash-# Check if canary is already published-npm view paperclipai@{version} version 2>/dev/null && echo "ALREADY_PUBLISHED" || echo "NOT_PUBLISHED"--# Also check git tag-git tag -l "v{version}"+pnpm -r typecheck+pnpm test:run+pnpm build```-- If a git tag exists → the release is already fully promoted. Skip to Step 6.-- If the version exists on npm but no git tag → canary was published but not yet- promoted. Skip to Step 4 (smoke test).-- If neither exists → proceed with canary publish.+If the release will be run through GitHub Actions, the workflow can rerun this gate. Still report whether the local tree currently passes.-### Publishing the canary+## Step 4 — Publish a Canary-Use `release.sh` with the `--canary` flag (see script changes below):+Run:```bash-# Dry run first./scripts/release.sh {patch|minor|major} --canary --dry-run--# Publish canary (after dry-run review)./scripts/release.sh {patch|minor|major} --canary```-This publishes all packages to npm with the `canary` dist-tag. The `latest` tag-is **not** updated. Users running `npx paperclipai onboard` still get the-previous stable version.+What this means:-After publish, verify the canary is accessible:+- npm receives `X.Y.Z-canary.N` under dist-tag `canary`+- `latest` remains unchanged+- no git tag is created+- the script cleans the working tree afterward++After publish, verify:```bashnpm view paperclipai@canary version-# Should show the new version```-**How `--canary` works in release.sh:**-- Steps 1-5 are the same (preflight, changeset, version, build, CLI bundle)-- Step 6 uses `npx changeset publish --tag canary` instead of `npx changeset publish`-- Step 7 does NOT commit or tag — the commit and tag happen later in the promote- step, only after smoke testing passes--**Script changes required:** Add `--canary` support to `scripts/release.sh`:-- Parse `--canary` flag alongside `--dry-run`-- When `--canary`: pass `--tag canary` to `changeset publish`-- When `--canary`: skip the git commit and tag step (Step 7)-- When NOT `--canary`: behavior is unchanged (backwards compatible)+The user install path is:------## Step 4 — Smoke Test the Canary--Run the canary in a clean Docker environment to verify `npx paperclipai onboard`-works end-to-end.+```bash+npx paperclipai@canary onboard+```-### Automated smoke test+## Step 5 — Smoke Test the Canary-Use the existing Docker smoke test infrastructure with the canary version:+Run:```bashPAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh```-This builds a clean Ubuntu container, installs `paperclipai@canary` via npx, and-runs the onboarding flow. The UI is accessible at `http://localhost:3131`.--### What to verify--At minimum, confirm:+Confirm:-1. **Container starts** — no npm install errors, no missing dependencies-2. **Onboarding completes** — the wizard runs through without crashes-3. **Server boots** — UI is accessible at the expected port-4. **Basic operations** — can create a company, view the dashboard+1. install succeeds+2. onboarding completes+3. server boots+4. UI loads+5. basic company/dashboard flow works-For a more thorough check (stretch goal — can be automated later):+If smoke testing fails:-5. **Browser automation** — script Playwright/Puppeteer to walk through onboard- in the Docker container's browser and verify key pages render+- stop the stable release+- fix the issue+- publish another canary+- repeat the smoke test-### If smoke test fails+Each retry should create a higher canary ordinal, while the stable target version can stay the same.-- Do NOT promote the canary.-- Fix the issue, publish a new canary (re-run Step 3 — idempotency guards allow- this since there's no git tag yet).-- Re-run the smoke test.+## Step 6 — Publish Stable-### If smoke test passes--Proceed to Step 5 (promote).-------## Step 5 — Promote Canary to Latest--Once the canary passes smoke testing, promote it to `latest` so that-`npx paperclipai onboard` picks up the new version.--### Promote on npm+Once the SHA is vetted, run:```bash-# For each published package, move the dist-tag from canary to latest-npm dist-tag add paperclipai@{version} latest-npm dist-tag add @paperclipai/server@{version} latest-npm dist-tag add @paperclipai/cli@{version} latest-npm dist-tag add @paperclipai/shared@{version} latest-npm dist-tag add @paperclipai/db@{version} latest-npm dist-tag add @paperclipai/adapter-utils@{version} latest-npm dist-tag add @paperclipai/adapter-claude-local@{version} latest-npm dist-tag add @paperclipai/adapter-codex-local@{version} latest-npm dist-tag add @paperclipai/adapter-openclaw-gateway@{version} latest+./scripts/release.sh {patch|minor|major} --dry-run+./scripts/release.sh {patch|minor|major}```-**Script option:** Add `./scripts/release.sh --promote {version}` to automate-the dist-tag promotion for all packages.+Stable publish does this:-### Commit and tag+- publishes `X.Y.Z` to npm under `latest`+- creates the local release commit+- creates the local git tag `vX.Y.Z`-After promotion, finalize in git (this is what `release.sh` Step 7 normally-does, but was deferred during canary publish):+Stable publish does **not** push the release for you.-```bash-git add .-git commit -m "chore: release v{version}"-git tag "v{version}"-```+## Step 7 — Push and Create GitHub Release-### Verify promotion+After stable publish succeeds:```bash-npm view paperclipai@latest version-# Should now show the new version--# Final sanity check-npx --yes paperclipai@latest --version+git push origin HEAD:master --follow-tags+./scripts/create-github-release.sh X.Y.Z```----+Use the stable changelog file as the GitHub Release notes source.-## Step 6 - Create Cross-Project Follow-up Tasks+## Step 8 — Finish the Other Surfaces-**Idempotency check:** Before creating tasks, search for existing ones:+Create or verify follow-up work for:-```-GET /api/companies/{companyId}/issues?q=release+notes+v{version}-GET /api/companies/{companyId}/issues?q=announcement+tweet+v{version}-```+- website changelog publishing+- launch post / social announcement+- any release summary in Paperclip issue context-If matching tasks already exist (check title contains the version), skip-creation and link the existing tasks instead. Do not create duplicates.--Create at least two tasks in Paperclip (only if they don't already exist):--1. Website task: publish changelog for `v{version}`-2. CMO task: draft announcement tweet for `v{version}`--When creating tasks:-- Set `parentId` to the release issue id.-- Carry over `goalId` from the parent issue when present.-- Include `billingCode` for cross-team work when required by company policy.-- Mark website task `high` priority if release has breaking changes.--Suggested payloads:--```json-POST /api/companies/{companyId}/issues-{- "projectId": "{websiteProjectId}",- "parentId": "{releaseIssueId}",- "goalId": "{goalId-or-null}",- "billingCode": "{billingCode-or-null}",- "title": "Publish release notes for v{version}",- "priority": "medium",- "status": "todo",- "description": "Publish /changelog entry for v{version}. Include full markdown from releases/v{version}.md and prominent upgrade guide if breaking changes exist."-}-```--```json-POST /api/companies/{companyId}/issues-{- "projectId": "{workspaceProjectId}",- "parentId": "{releaseIssueId}",- "goalId": "{goalId-or-null}",- "billingCode": "{billingCode-or-null}",- "title": "Draft release announcement tweet for v{version}",- "priority": "medium",- "status": "todo",- "description": "Draft launch tweet with top 1-2 highlights, version number, and changelog URL. If breaking changes exist, include an explicit upgrade-guide callout."-}-```+These should reference the stable release, not the canary.------## Step 7 - Wrap Up the Release Issue+## Failure Handling-Post a concise markdown update linking:-- Release issue-- Changelog file (`releases/v{version}.md`)-- npm package URL (both `@canary` and `@latest` after promotion)-- Canary smoke test result (pass/fail, what was tested)-- Website task-- CMO task-- Final changelog URL (once website publishes)-- Tweet URL (once published)+If the canary is bad:-Completion rules:-- Keep issue `in_progress` until canary is promoted AND website + social tasks- are done.-- Mark `done` only when all required artifacts are published and linked.-- If waiting on another team, keep open with clear owner and next action.+- publish another canary, do not ship stable----+If stable npm publish succeeds but push or GitHub release creation fails:-## Release Flow Summary+- fix the git/GitHub issue immediately from the same checkout+- do not republish the same version-The full release lifecycle is now:+If `latest` is bad after stable publish:+```bash+./scripts/rollback-latest.sh <last-good-version>```-1. Generate changelog → releases/v{version}.md (review + iterate)-2. Publish canary → npm @canary dist-tag (latest untouched)-3. Smoke test canary → Docker clean install verification-4. Promote to latest → npm @latest dist-tag + git tag + commit-5. Create follow-up tasks → website changelog + CMO tweet-6. Wrap up → link everything, close issue-```--At any point you can re-enter the flow — idempotency guards detect which steps-are already done and skip them. The changelog can be iterated before or after-canary publish. The canary can be re-published if the smoke test reveals issues-(just fix + re-run Step 3). Only after smoke testing passes does `latest` get-updated.------## Paperclip API Notes (When Running in Agent Context)--Use:-- `GET /api/companies/{companyId}/projects` to resolve website/workspace project IDs.-- `POST /api/companies/{companyId}/issues` to create follow-up tasks.-- `PATCH /api/issues/{issueId}` with comments for release progress.--For issue-modifying calls, include:-- `Authorization: Bearer $PAPERCLIP_API_KEY`-- `X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID`+Then fix forward with a new patch release.------## Failure Handling+## Output-If blocked, update the release issue explicitly with:-- what failed-- exact blocker-- who must act next-- whether any release artifacts were partially published+When the skill completes, provide:-Never silently fail mid-release.+- stable version and, if relevant, the final canary version tested+- verification status+- npm status+- git tag / GitHub Release status+- website / announcement follow-up status+- rollback recommendation if anything is still partially complete