@paperclipai/adapter-codex-local 0.2.7 → 0.3.0-canary.0

package/LICENSE

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

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,IAAI,gBAAgB,CAAC;AAClC,eAAO,MAAM,KAAK,kBAAkB,CAAC;AACrC,eAAO,MAAM,yBAAyB,kBAAkB,CAAC;AACzD,eAAO,MAAM,gDAAgD,OAAO,CAAC;AAErE,eAAO,MAAM,MAAM;;;GAUlB,CAAC;AAEF,eAAO,MAAM,qBAAqB,w3CAwBjC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,IAAI,gBAAgB,CAAC;AAClC,eAAO,MAAM,KAAK,kBAAkB,CAAC;AACrC,eAAO,MAAM,yBAAyB,kBAAkB,CAAC;AACzD,eAAO,MAAM,gDAAgD,OAAO,CAAC;AAErE,eAAO,MAAM,MAAM;;;GAWlB,CAAC;AAEF,eAAO,MAAM,qBAAqB,w3CAwBjC,CAAC"}

package/dist/index.js

@@ -3,6 +3,7 @@ export const label = "Codex (local)";
 export const DEFAULT_CODEX_LOCAL_MODEL = "gpt-5.3-codex";
 export const DEFAULT_CODEX_LOCAL_BYPASS_APPROVALS_AND_SANDBOX = true;
 export const models = [
+    { id: "gpt-5.4", label: "gpt-5.4" },
     { id: DEFAULT_CODEX_LOCAL_MODEL, label: DEFAULT_CODEX_LOCAL_MODEL },
     { id: "gpt-5.3-codex-spark", label: "gpt-5.3-codex-spark" },
     { id: "gpt-5", label: "gpt-5" },

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,IAAI,GAAG,aAAa,CAAC;AAClC,MAAM,CAAC,MAAM,KAAK,GAAG,eAAe,CAAC;AACrC,MAAM,CAAC,MAAM,yBAAyB,GAAG,eAAe,CAAC;AACzD,MAAM,CAAC,MAAM,gDAAgD,GAAG,IAAI,CAAC;AAErE,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,EAAE,EAAE,EAAE,yBAAyB,EAAE,KAAK,EAAE,yBAAyB,EAAE;IACnE,EAAE,EAAE,EAAE,qBAAqB,EAAE,KAAK,EAAE,qBAAqB,EAAE;IAC3D,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE;IAC/B,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE;IACzB,EAAE,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE;IACnC,EAAE,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE;IACzC,EAAE,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE;IACzC,EAAE,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE;IACnC,EAAE,EAAE,EAAE,mBAAmB,EAAE,KAAK,EAAE,YAAY,EAAE;CACjD,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;CAwBpC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,IAAI,GAAG,aAAa,CAAC;AAClC,MAAM,CAAC,MAAM,KAAK,GAAG,eAAe,CAAC;AACrC,MAAM,CAAC,MAAM,yBAAyB,GAAG,eAAe,CAAC;AACzD,MAAM,CAAC,MAAM,gDAAgD,GAAG,IAAI,CAAC;AAErE,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,EAAE,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE;IACnC,EAAE,EAAE,EAAE,yBAAyB,EAAE,KAAK,EAAE,yBAAyB,EAAE;IACnE,EAAE,EAAE,EAAE,qBAAqB,EAAE,KAAK,EAAE,qBAAqB,EAAE;IAC3D,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE;IAC/B,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE;IACzB,EAAE,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE;IACnC,EAAE,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE;IACzC,EAAE,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE;IACzC,EAAE,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE;IACnC,EAAE,EAAE,EAAE,mBAAmB,EAAE,KAAK,EAAE,YAAY,EAAE;CACjD,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;CAwBpC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paperclipai/adapter-codex-local",
-  "version": "0.2.7",
+  "version": "0.3.0-canary.0",
   "type": "module",
   "exports": {
     ".": {
@@ -29,9 +29,10 @@
   ],
   "dependencies": {
     "picocolors": "^1.1.1",
-    "@paperclipai/adapter-utils": "0.2.7"
+    "@paperclipai/adapter-utils": "0.3.0-canary.0"
   },
   "devDependencies": {
+    "@types/node": "^24.6.0",
     "typescript": "^5.7.3"
   },
   "scripts": {

package/skills/paperclip/SKILL.md

@@ -16,6 +16,8 @@ You run in **heartbeats** — short execution windows triggered by Paperclip. Ea
 
 Env vars auto-injected: `PAPERCLIP_AGENT_ID`, `PAPERCLIP_COMPANY_ID`, `PAPERCLIP_API_URL`, `PAPERCLIP_RUN_ID`. Optional wake-context vars may also be present: `PAPERCLIP_TASK_ID` (issue/task that triggered this wake), `PAPERCLIP_WAKE_REASON` (why this run was triggered), `PAPERCLIP_WAKE_COMMENT_ID` (specific comment that triggered this wake), `PAPERCLIP_APPROVAL_ID`, `PAPERCLIP_APPROVAL_STATUS`, and `PAPERCLIP_LINKED_ISSUE_IDS` (comma-separated). For local adapters, `PAPERCLIP_API_KEY` is auto-injected as a short-lived run JWT. For non-local adapters, your operator should set `PAPERCLIP_API_KEY` in adapter config. All requests use `Authorization: Bearer $PAPERCLIP_API_KEY`. All endpoints under `/api`, all JSON. Never hard-code the API URL.
 
+Manual local CLI mode (outside heartbeat runs): use `paperclipai agent local-cli <agent-id-or-shortname> --company-id <company-id>` to install Paperclip skills for Claude/Codex and print/export the required `PAPERCLIP_*` environment variables for that agent identity.
+
 **Run audit trail:** You MUST include `-H 'X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID'` on ALL API requests that modify issues (checkout, update, comment, create subtask, release). This links your actions to the current heartbeat run for traceability.
 
 ## The Heartbeat Procedure
@@ -89,6 +91,30 @@ Workspace rules:
 - For repo-only setup, omit `cwd` and provide `repoUrl`.
 - Include both `cwd` + `repoUrl` when local and remote references should both be tracked.
 
+## OpenClaw Invite Workflow (CEO)
+
+Use this when asked to invite a new OpenClaw employee.
+
+1. Generate a fresh OpenClaw invite prompt:
+
+```
+POST /api/companies/{companyId}/openclaw/invite-prompt
+{ "agentMessage": "optional onboarding note for OpenClaw" }
+```
+
+Access control:
+- Board users with invite permission can call it.
+- Agent callers: only the company CEO agent can call it.
+
+2. Build the copy-ready OpenClaw prompt for the board:
+- Use `onboardingTextUrl` from the response.
+- Ask the board to paste that prompt into OpenClaw.
+- If the issue includes an OpenClaw URL (for example `ws://127.0.0.1:18789`), include that URL in your comment so the board/OpenClaw uses it in `agentDefaultsPayload.url`.
+
+3. Post the prompt in the issue comment so the human can paste it into OpenClaw.
+
+4. After OpenClaw submits the join request, monitor approvals and continue onboarding (approval + API key claim + skill install).
+
 ## Critical Rules
 
 - **Always checkout** before working. Never PATCH to `in_progress` manually.
@@ -112,16 +138,18 @@ When posting issue comments, use concise markdown with:
 
 - a short status line
 - bullets for what changed / what is blocked
-- links to related entities when available (`[Issue PAP-123](/issues/<issue-identifier>)`, `[Approval](/approvals/<approval-id>)`, `[Agent](/agents/<agent-url-key-or-id>)`)
+- links to related entities when available
 
-Prefer canonical UI links:
+**Company-prefixed URLs (required):** All internal links MUST include the company prefix. Derive the prefix from any issue identifier you have (e.g., `PAP-315` → prefix is `PAP`). Use this prefix in all UI links:
 
-- Issues: `/issues/<issue-identifier>` (for example `PAP-224`)
-- Agents: `/agents/<agent-url-key>` (id fallback allowed)
-- Projects: `/projects/<project-url-key>` (id fallback allowed)
-- Runs: `/agents/<agent-url-key-or-id>/runs/<run-id>`
+- Issues: `/<prefix>/issues/<issue-identifier>` (e.g., `/PAP/issues/PAP-224`)
+- Issue comments: `/<prefix>/issues/<issue-identifier>#comment-<comment-id>` (deep link to a specific comment)
+- Agents: `/<prefix>/agents/<agent-url-key>` (e.g., `/PAP/agents/claudecoder`)
+- Projects: `/<prefix>/projects/<project-url-key>` (id fallback allowed)
+- Approvals: `/<prefix>/approvals/<approval-id>`
+- Runs: `/<prefix>/agents/<agent-url-key-or-id>/runs/<run-id>`
 
-Compatibility redirect behavior: UUID/id links such as `/issues/<uuid>`, `/agents/<id>`, `/projects/<id>`, and `/agents/<id>/runs/<run-id>` should resolve and redirect to canonical routes.
+Do NOT use unprefixed paths like `/issues/PAP-123` or `/agents/cto` — always include the company prefix.
 
 Example:
 
@@ -130,9 +158,9 @@ Example:
 
 Submitted CTO hire request and linked it for board review.
 
-- Approval: [ca6ba09d](/approvals/ca6ba09d-b558-4a53-a552-e7ef87e54a1b)
-- Pending agent: [CTO draft](/agents/cto)
-- Source issue: [PC-142](/issues/PC-142)
+- Approval: [ca6ba09d](/PAP/approvals/ca6ba09d-b558-4a53-a552-e7ef87e54a1b)
+- Pending agent: [CTO draft](/PAP/agents/cto)
+- Source issue: [PC-142](/PAP/issues/PC-142)
 ```
 
 ## Planning (Required when planning requested)
@@ -198,9 +226,11 @@ PATCH /api/agents/{agentId}/instructions-path
 | Checkout task        | `POST /api/issues/:issueId/checkout`                                                       |
 | Get task + ancestors | `GET /api/issues/:issueId`                                                                 |
 | Get comments         | `GET /api/issues/:issueId/comments`                                                        |
+| Get specific comment | `GET /api/issues/:issueId/comments/:commentId`                                              |
 | Update task          | `PATCH /api/issues/:issueId` (optional `comment` field)                                    |
 | Add comment          | `POST /api/issues/:issueId/comments`                                                       |
 | Create subtask       | `POST /api/companies/:companyId/issues`                                                    |
+| Generate OpenClaw invite prompt (CEO) | `POST /api/companies/:companyId/openclaw/invite-prompt`                   |
 | Create project       | `POST /api/companies/:companyId/projects`                                                  |
 | Create project workspace | `POST /api/projects/:projectId/workspaces`                                             |
 | Set instructions path | `PATCH /api/agents/:agentId/instructions-path`                                            |
@@ -219,6 +249,43 @@ GET /api/companies/{companyId}/issues?q=dockerfile
 
 Results are ranked by relevance: title matches first, then identifier, description, and comments. You can combine `q` with other filters (`status`, `assigneeAgentId`, `projectId`, `labelId`).
 
+## Self-Test Playbook (App-Level)
+
+Use this when validating Paperclip itself (assignment flow, checkouts, run visibility, and status transitions).
+
+1. Create a throwaway issue assigned to a known local agent (`claudecoder` or `codexcoder`):
+
+```bash
+pnpm paperclipai issue create \
+  --company-id "$PAPERCLIP_COMPANY_ID" \
+  --title "Self-test: assignment/watch flow" \
+  --description "Temporary validation issue" \
+  --status todo \
+  --assignee-agent-id "$PAPERCLIP_AGENT_ID"
+```
+
+2. Trigger and watch a heartbeat for that assignee:
+
+```bash
+pnpm paperclipai heartbeat run --agent-id "$PAPERCLIP_AGENT_ID"
+```
+
+3. Verify the issue transitions (`todo -> in_progress -> done` or `blocked`) and that comments are posted:
+
+```bash
+pnpm paperclipai issue get <issue-id-or-identifier>
+```
+
+4. Reassignment test (optional): move the same issue between `claudecoder` and `codexcoder` and confirm wake/run behavior:
+
+```bash
+pnpm paperclipai issue update <issue-id> --assignee-agent-id <other-agent-id> --status todo
+```
+
+5. Cleanup: mark temporary issues done/cancelled with a clear note.
+
+If you use direct `curl` during these tests, include `X-Paperclip-Run-Id` on all mutating issue requests whenever running inside a heartbeat.
+
 ## Full Reference
 
 For detailed API tables, JSON response schemas, worked examples (IC and Manager heartbeats), governance/approvals, cross-team delegation rules, error codes, issue lifecycle diagram, and the common mistakes table, read: `skills/paperclip/references/api-reference.md`

package/skills/paperclip/references/api-reference.md

@@ -216,11 +216,13 @@ Use markdown formatting and include links to related entities when they exist:
 ```md
 ## Update
 
-- Approval: [APPROVAL_ID](/approvals/<approval-id>)
-- Pending agent: [AGENT_NAME](/agents/<agent-url-key-or-id>)
-- Source issue: [ISSUE_ID](/issues/<issue-identifier-or-id>)
+- Approval: [APPROVAL_ID](/<prefix>/approvals/<approval-id>)
+- Pending agent: [AGENT_NAME](/<prefix>/agents/<agent-url-key-or-id>)
+- Source issue: [ISSUE_ID](/<prefix>/issues/<issue-identifier-or-id>)
 ```
 
+Where `<prefix>` is the company prefix derived from the issue identifier (e.g., `PAP-123` → prefix is `PAP`).
+
 **@-mentions:** Mention another agent by name using `@AgentName` to automatically wake them:
 
 ```
@@ -278,6 +280,23 @@ GET /api/companies/{companyId}/dashboard — health summary: agent/task counts,
 
 Use the dashboard for situational awareness, especially if you're a manager or CEO.
 
+## OpenClaw Invite Prompt (CEO)
+
+Use this endpoint to generate a short-lived OpenClaw onboarding invite prompt:
+
+```
+POST /api/companies/{companyId}/openclaw/invite-prompt
+{
+  "agentMessage": "optional note for the joining OpenClaw agent"
+}
+```
+
+Response includes invite token, onboarding text URL, and expiry metadata.
+
+Access is intentionally constrained:
+- board users with invite permission
+- CEO agent only (non-CEO agents are rejected)
+
 ---
 
 ## Setting Agent Instructions Path
@@ -479,6 +498,7 @@ Terminal states: `done`, `cancelled`
 | POST   | `/api/issues/:issueId/checkout`    | Atomic checkout (claim + start). Idempotent if you already own it.                       |
 | POST   | `/api/issues/:issueId/release`     | Release task ownership                                                                   |
 | GET    | `/api/issues/:issueId/comments`    | List comments                                                                            |
+| GET    | `/api/issues/:issueId/comments/:commentId` | Get a specific comment by ID                                                     |
 | POST   | `/api/issues/:issueId/comments`    | Add comment (@-mentions trigger wakeups)                                                 |
 | GET    | `/api/issues/:issueId/approvals`   | List approvals linked to issue                                                           |
 | POST   | `/api/issues/:issueId/approvals`   | Link approval to issue                                                                    |
@@ -502,6 +522,7 @@ Terminal states: `done`, `cancelled`
 | GET    | `/api/goals/:goalId`                 | Goal details       |
 | POST   | `/api/companies/:companyId/goals`    | Create goal        |
 | PATCH  | `/api/goals/:goalId`                 | Update goal        |
+| POST   | `/api/companies/:companyId/openclaw/invite-prompt` | Generate OpenClaw invite prompt (CEO/board only) |
 
 ### Approvals, Costs, Activity, Dashboard
 

package/skills/release/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: release
+description: >
+  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 as a maintainer workflow, not just an npm publish.
+
+This skill coordinates:
+
+- 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
+
+## Trigger
+
+Use this skill when leadership asks for:
+
+- "do a release"
+- "ship the next patch/minor/major"
+- "release vX.Y.Z"
+
+## Preconditions
+
+Before proceeding, verify all of the following:
+
+1. `skills/release-changelog/SKILL.md` exists and is usable.
+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.
+
+## Inputs
+
+Collect these inputs up front:
+
+- 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
+
+Paperclip now uses this release model:
+
+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
+
+Critical consequence:
+
+- Canaries do **not** use promote-by-dist-tag anymore.
+- The changelog remains stable-only. Do not create `releases/vX.Y.Z-canary.N.md`.
+
+## Step 1 — Decide the Stable Version
+
+Run release preflight first:
+
+```bash
+./scripts/release-preflight.sh canary {patch|minor|major}
+# or
+./scripts/release-preflight.sh stable {patch|minor|major}
+```
+
+Then use the last stable tag as the base:
+
+```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" | rg -n 'BREAKING CHANGE|BREAKING:|^[a-z]+!:' || true
+```
+
+Bump policy:
+
+- destructive migrations, removed APIs, breaking config changes -> `major`
+- additive migrations or clearly user-visible features -> at least `minor`
+- fixes only -> `patch`
+
+If the requested bump is too low, escalate it and explain why.
+
+## Step 2 — Draft the Stable Changelog
+
+Invoke `release-changelog` and generate:
+
+- `releases/vX.Y.Z.md`
+
+Rules:
+
+- 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
+
+## Step 3 — Verify the Release SHA
+
+Run the standard gate:
+
+```bash
+pnpm -r typecheck
+pnpm test:run
+pnpm build
+```
+
+If the release will be run through GitHub Actions, the workflow can rerun this gate. Still report whether the local tree currently passes.
+
+## Step 4 — Publish a Canary
+
+Run:
+
+```bash
+./scripts/release.sh {patch|minor|major} --canary --dry-run
+./scripts/release.sh {patch|minor|major} --canary
+```
+
+What this means:
+
+- 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
+
+Guard:
+
+- if the current stable is `0.2.7`, the next patch canary is `0.2.8-canary.0`
+- the tooling must never publish `0.2.7-canary.N` after `0.2.7` is already stable
+
+After publish, verify:
+
+```bash
+npm view paperclipai@canary version
+```
+
+The user install path is:
+
+```bash
+npx paperclipai@canary onboard
+```
+
+## Step 5 — Smoke Test the Canary
+
+Run:
+
+```bash
+PAPERCLIPAI_VERSION=canary ./scripts/docker-onboard-smoke.sh
+```
+
+Confirm:
+
+1. install succeeds
+2. onboarding completes
+3. server boots
+4. UI loads
+5. basic company/dashboard flow works
+
+If smoke testing fails:
+
+- stop the stable release
+- fix the issue
+- publish another canary
+- repeat the smoke test
+
+Each retry should create a higher canary ordinal, while the stable target version can stay the same.
+
+## Step 6 — Publish Stable
+
+Once the SHA is vetted, run:
+
+```bash
+./scripts/release.sh {patch|minor|major} --dry-run
+./scripts/release.sh {patch|minor|major}
+```
+
+Stable publish does this:
+
+- publishes `X.Y.Z` to npm under `latest`
+- creates the local release commit
+- creates the local git tag `vX.Y.Z`
+
+Stable publish does **not** push the release for you.
+
+## Step 7 — Push and Create GitHub Release
+
+After stable publish succeeds:
+
+```bash
+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 8 — Finish the Other Surfaces
+
+Create or verify follow-up work for:
+
+- website changelog publishing
+- launch post / social announcement
+- any release summary in Paperclip issue context
+
+These should reference the stable release, not the canary.
+
+## Failure Handling
+
+If the canary is bad:
+
+- publish another canary, do not ship stable
+
+If stable npm publish succeeds but push or GitHub release creation fails:
+
+- fix the git/GitHub issue immediately from the same checkout
+- do not republish the same version
+
+If `latest` is bad after stable publish:
+
+```bash
+./scripts/rollback-latest.sh <last-good-version>
+```
+
+Then fix forward with a new patch release.
+
+## Output
+
+When the skill completes, provide:
+
+- 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

package/skills/release-changelog/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: release-changelog
+description: >
+  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 the user-facing changelog for the **stable** Paperclip release.
+
+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 whether the file already exists:
+
+```bash
+ls releases/v{version}.md 2>/dev/null
+```
+
+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 Stable Range
+
+Find the last stable tag:
+
+```bash
+git tag --list 'v*' --sort=-version:refname | head -1
+git log v{last}..HEAD --oneline --no-merges
+```
+
+The planned stable version comes from one of:
+
+- 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 the Raw Inputs
+
+Collect release data from:
+
+1. git commits since the last stable tag
+2. `.changeset/*.md` files
+3. merged PRs via `gh` when available
+
+Useful commands:
+
+```bash
+git log v{last}..HEAD --oneline --no-merges
+git log v{last}..HEAD --format="%H %s" --no-merges
+ls .changeset/*.md | grep -v README.md
+gh pr list --state merged --search "merged:>={last-tag-date}" --json number,title,body,labels
+```
+
+## Step 3 — Detect Breaking Changes
+
+Look for:
+
+- destructive migrations
+- removed or changed API fields/endpoints
+- renamed or removed config keys
+- `major` changesets
+- `BREAKING:` or `BREAKING CHANGE:` commit signals
+
+Key commands:
+
+```bash
+git diff --name-only v{last}..HEAD -- packages/db/src/migrations/
+git diff v{last}..HEAD -- packages/db/src/schema/
+git 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
+```
+
+If the requested bump is lower than the minimum required bump, flag that before the release proceeds.
+
+## Step 4 — Categorize for Users
+
+Use these stable changelog sections:
+
+- `Breaking Changes`
+- `Highlights`
+- `Improvements`
+- `Fixes`
+- `Upgrade Guide` when needed
+
+Exclude purely internal refactors, CI changes, and docs-only work unless they materially affect users.
+
+Guidelines:
+
+- 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
+
+## Step 5 — Write the File
+
+Template:
+
+```markdown
+# v{version}
+
+> Released: {YYYY-MM-DD}
+
+## Breaking Changes
+
+## Highlights
+
+## Improvements
+
+## Fixes
+
+## Upgrade Guide
+```
+
+Omit empty sections except `Highlights`, `Improvements`, and `Fixes`, which should usually exist.
+
+## Step 6 — Review Before Release
+
+Before handing it off:
+
+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
+
+This skill never publishes anything. It only prepares the stable changelog artifact.