codebyplan 1.5.1 → 1.9.0

package/templates/skills/cbp-ship/reference/gh-cli-shipment-commands.md

@@ -0,0 +1,283 @@
+# GitHub CLI — Shipment Commands
+
+Commands `/cbp-ship` actually runs, organised by surface. Authoritative reference: <https://cli.github.com/manual>. Each section: exact command, flags we use, JSON shape (where applicable), common errors.
+
+## 1. Pull Requests
+
+### `gh pr create` — open a PR
+
+```bash
+gh pr create --base main --head "$BRANCH" \
+  --title "$TITLE" --body-file .claude/tmp/pr-body.md --draft
+```
+
+| Flag | Purpose |
+|------|---------|
+| `--base <branch>` | Target. CBP ships `feat/* -> main`; always set explicitly. |
+| `--head <branch>` | Source. Defaults to current; pass explicitly with `--repo`. |
+| `--title` | One-line title. Obey `rules/git-workflow.md` (no Claude attribution). |
+| `--body-file <path>` | Multiline body. Preferred over `--body`. |
+| `--draft` | Open in draft. CBP default for non-trivial PRs. |
+| `--reviewer @me,user,team/slug` | Optional. |
+| `--label`, `--assignee`, `--milestone`, `--project` | Optional metadata. |
+| `--fill` | Use commit subject + body as title/body. |
+| `--repo OWNER/REPO` | Required outside the checkout. |
+
+Output: prints the URL on stdout (no JSON). Capture the PR number with `gh pr view --json number`.
+
+Common errors:
+
+- `A pull request already exists for ...` — branch has an open PR; use `gh pr view`.
+- `must provide --title and --body (or --fill)` — non-TTY without flags.
+- `Head sha can't be blank` — branch not pushed; `git push -u origin <branch>` first.
+
+### `gh pr view` — read PR state
+
+```bash
+gh pr view "$PR_NUMBER" \
+  --json number,state,mergeable,mergeStateStatus,headRefOid,baseRefName,reviewDecision,statusCheckRollup,url \
+  --jq .
+```
+
+| Field | Type | Use |
+|-------|------|-----|
+| `state` | `OPEN`/`CLOSED`/`MERGED` | Gate further actions |
+| `mergeable` | `MERGEABLE`/`CONFLICTING`/`UNKNOWN` | Pre-merge gate |
+| `mergeStateStatus` | `CLEAN`/`BLOCKED`/`BEHIND`/`DIRTY`/`UNSTABLE`/`HAS_HOOKS` | Why merge is blocked |
+| `headRefOid` | sha | Pin a `--match-head-commit` merge |
+| `reviewDecision` | `APPROVED`/`CHANGES_REQUESTED`/`REVIEW_REQUIRED` | Review gate |
+| `statusCheckRollup` | array | Per-check status; filter with `--jq` |
+
+Pass `--json` with no value to discover the full field list.
+
+### `gh pr merge` — merge a PR
+
+```bash
+gh pr merge "$PR_NUMBER" --merge --delete-branch --match-head-commit "$HEAD_OID"
+```
+
+| Flag | Purpose |
+|------|---------|
+| `--merge`/`--squash`/`--rebase` | Strategy. CBP default is `--merge`. `--rebase` often blocked by branch protection. |
+| `--auto` | Auto-merge once required checks pass. |
+| `--delete-branch` (`-d`) | Delete head after merge. Always set for `feat/*`. |
+| `--admin` | Bypass branch protection. Reserved for emergency hotfixes; never default. |
+| `--match-head-commit <oid>` | Refuse merge if HEAD has moved. Use `headRefOid` from `gh pr view`. |
+| `--subject`, `--body` | Override merge commit message. |
+
+Common errors:
+
+- `Pull request is not mergeable: <reason>` — inspect `mergeStateStatus`. `BLOCKED` = required checks/reviews missing.
+- `auto-merge is not allowed for this repository` — repo disables it; remove `--auto`.
+- HTTP 405 on protected branches without `--admin` — expected; do NOT auto-escalate.
+
+## 2. Releases
+
+### `gh release create`
+
+```bash
+gh release create "$TAG" --title "$TITLE" --notes-file CHANGELOG-fragment.md \
+  --target "$COMMIT_SHA" --latest ./dist/*.tar.gz ./dist/*.zip
+```
+
+Argument order: `gh release create <tag> [<asset>...]`. Tag is positional + required.
+
+| Flag | Purpose |
+|------|---------|
+| `--title` (`-t`) | Title. Defaults to tag. |
+| `--notes-file` (`-F`) | Notes from file. `-` for stdin. |
+| `--generate-notes` | Auto-generate via API; combinable with `--notes-file` (file content goes above generated). |
+| `--target <branch-or-sha>` | Tag-target if tag does not exist. |
+| `--draft` (`-d`) | Save as draft. CBP default for human review. |
+| `--prerelease` (`-p`) | Prerelease flag. |
+| `--latest` / `--latest=false` | Mark/unmark as Latest. |
+| `--verify-tag` | Refuse if tag does not exist remotely. |
+| `--discussion-category <name>` | Open a discussion. |
+| `--fail-on-no-commits` | Abort if no new commits since last release. |
+
+Asset upload: paths after the tag. Custom labels via `'/path/to/file.zip#Display Label'`.
+
+Common errors:
+
+- `tag already exists` (without `--target`) — local tag points to different sha; `git push --tags` or `git tag -d` + recreate.
+- `validation failed: name has already been taken` — use `gh release edit` or `gh release delete` first.
+- `could not find tag` with `--verify-tag` — push the tag first.
+
+### `gh release view`
+
+```bash
+gh release view "$TAG" --json tagName,name,isDraft,isLatest,isPrerelease,publishedAt,url,assets --jq .
+```
+
+JSON fields: `tagName`, `name`, `body`, `isDraft`, `isLatest`, `isPrerelease`, `publishedAt`, `url`, `tarballUrl`, `zipballUrl`, `assets[].{name,size,downloadCount,url}`.
+
+### `gh release delete`
+
+```bash
+gh release delete "$TAG" --yes --cleanup-tag
+```
+
+`--yes` skips confirmation (required non-TTY). `--cleanup-tag` also deletes the underlying git tag. `release not found` is a soft failure — treat as already-clean.
+
+## 3. Secrets
+
+### `gh secret list`
+
+```bash
+gh secret list --repo "$OWNER/$REPO"
+gh secret list --org "$ORG"
+gh secret list --env "$ENV" --repo "$OWNER/$REPO"
+```
+
+Output is tab-separated `NAME UPDATED`. No `--json`. Secret values are never returned.
+
+### `gh secret set`
+
+```bash
+echo -n "$VALUE" | gh secret set MY_SECRET                                            # repo-level
+gh secret set --env-file .env.production                                              # bulk from dotenv
+echo -n "$VALUE" | gh secret set MY_SECRET --env production                           # environment
+echo -n "$VALUE" | gh secret set MY_SECRET --org myorg --visibility selected --repos repo1,repo2
+echo -n "$VALUE" | gh secret set MY_SECRET --app dependabot                           # dependabot
+```
+
+Scope matrix:
+
+| Flag combo | Scope | Token scope |
+|------------|-------|-------------|
+| (none) | Repository | `repo` |
+| `--env <name>` | Repository environment (env must exist) | `repo` |
+| `--org <name> --visibility all`/`private` | Org-wide | `admin:org` |
+| `--org <name> --visibility selected --repos a,b` | Org allow-list | `admin:org` |
+| `--app actions` (default) / `dependabot` / `codespaces` | Per-application surface | as above |
+
+Input precedence: `--body <value>` > stdin > interactive prompt. Prefer stdin to keep values out of process listings and shell history.
+
+Common errors:
+
+- `HTTP 404` with `--env` — environment must exist (`gh api repos/{o}/{r}/environments/{name} --method PUT`).
+- `HTTP 422: visibility 'selected' requires --repos` — supply allow-list.
+- `HTTP 403` against `--org` — `gh auth refresh --scopes admin:org`.
+
+## 4. Workflow Runs
+
+### `gh run list`
+
+```bash
+gh run list --workflow ci.yml --branch "$BRANCH" --limit 10 \
+  --json databaseId,status,conclusion,headSha,event,createdAt,workflowName,url \
+  --jq '.[] | select(.conclusion != "success")'
+```
+
+Flags: `--workflow` (filename/ID/name), `--branch`, `--user`, `--status`, `--event`, `--limit` (default 20), `--created`, `--json`, `-R/--repo`.
+
+JSON fields: `attempt`, `conclusion`, `createdAt`, `databaseId`, `displayTitle`, `event`, `headBranch`, `headSha`, `name`, `number`, `startedAt`, `status`, `updatedAt`, `url`, `workflowDatabaseId`, `workflowName`.
+
+`status`: `queued`, `in_progress`, `completed`, `requested`, `waiting`. `conclusion` (when `status=completed`): `success`, `failure`, `cancelled`, `skipped`, `timed_out`, `action_required`, `neutral`, `stale`.
+
+### `gh run watch`
+
+```bash
+gh run watch "$RUN_ID" --exit-status --interval 5 --compact
+```
+
+| Flag | Purpose |
+|------|---------|
+| `--exit-status` | Non-zero on failure. Required for `set -e`. |
+| `--interval <sec>` (`-i`) | Poll interval (default 3). Bump to 5-10 for long runs. |
+| `--compact` | Show only failed/relevant steps. |
+| `-R/--repo` | Override repo. |
+
+Never omit `RUN_ID` in `/cbp-ship` — without it the command prompts (no TTY).
+
+### `gh run view`
+
+```bash
+gh run view "$RUN_ID" --json status,conclusion,jobs,workflowName,url --jq .   # summary
+gh run view "$RUN_ID" --log-failed                                            # failed-step logs
+gh run view --job "$JOB_ID" --log                                             # one job
+gh run view "$RUN_ID" --exit-status                                           # script-friendly
+```
+
+JSON fields: same as `run list` plus `jobs`. `jobs[].{databaseId,name,status,conclusion,steps[].{name,conclusion,number}}` — canonical drill-down from a failed run to the responsible step.
+
+Common errors:
+
+- `could not find any workflow run with ID <x>` — wrong repo or expired; verify with `gh run list -R <repo>`.
+- `--log-failed` empty while in progress — pair with `gh run watch` first.
+- Logs older than 90 days unavailable (GitHub-side retention).
+
+## 5. Deployments API (Non-Vercel)
+
+For non-Vercel deploy targets, `/cbp-ship` records deploys via the GitHub Deployments API using `gh api`. There is no `gh deployment` subcommand.
+
+### Create a deployment
+
+```bash
+gh api "repos/$OWNER/$REPO/deployments" --method POST \
+  -f ref="$COMMIT_SHA" -f environment=production -f description="ship: $TAG" \
+  -F auto_merge=false -f required_contexts='[]'
+```
+
+- `-f key=value` — string field.
+- `-F key=value` — typed field (`true`/`false`/`null`/integer auto-converted).
+- `required_contexts='[]'` — empty JSON array as a string to skip status-check gating.
+- `--input <file>` — for complex payloads, pass JSON from file.
+
+Response (excerpt):
+
+```json
+{
+  "id": 12345678,
+  "url": "https://api.github.com/repos/.../deployments/12345678",
+  "sha": "abc123...",
+  "ref": "main",
+  "environment": "production",
+  "statuses_url": "https://api.github.com/repos/.../deployments/12345678/statuses"
+}
+```
+
+Capture `id` for status follow-ups.
+
+### Update deployment status
+
+```bash
+gh api "repos/$OWNER/$REPO/deployments/$DEPLOYMENT_ID/statuses" --method POST \
+  -f state=success -f environment_url="https://app.example.com" \
+  -f log_url="https://github.com/.../actions/runs/$RUN_ID" -f description="Live"
+```
+
+`state` values: `error`, `failure`, `inactive`, `in_progress`, `queued`, `pending`, `success`. Only `success` and `inactive` are terminal in the UI.
+
+### List deployments
+
+```bash
+gh api "repos/$OWNER/$REPO/deployments?environment=production&per_page=10" \
+  --jq '.[] | {id, sha, created_at, ref}'
+```
+
+Combine `--paginate` for full history, but bound it — Deployments grow unbounded.
+
+Common errors:
+
+- `HTTP 422: required_contexts is invalid` — pass `'[]'` literal with `-f`.
+- `HTTP 422: Conflict merging <ref>` — `auto_merge` defaulted to true; pass `-F auto_merge=false`.
+- `HTTP 404` — ref does not exist remotely, or token lacks `repo_deployment` (subset of `repo`).
+
+## Quick-Reference: What `/cbp-ship` Calls
+
+| Phase | Command |
+|-------|---------|
+| Open PR | `gh pr create --base ... --head ... --title ... --body-file ... --draft` |
+| Wait for checks | `gh run watch $RUN_ID --exit-status --interval 5` |
+| Inspect failure | `gh run view $RUN_ID --log-failed` |
+| Pre-merge gate | `gh pr view $PR --json mergeable,mergeStateStatus,reviewDecision,headRefOid` |
+| Merge | `gh pr merge $PR --merge --delete-branch --match-head-commit $OID` |
+| Cut release | `gh release create $TAG --title ... --notes-file ... --target $SHA --latest` |
+| Record deploy (non-Vercel) | `gh api repos/.../deployments --method POST -f ref=$SHA -f environment=production` |
+
+## Pairs With
+
+- [gh-cli-overview.md](./gh-cli-overview.md) — install, auth, config locations
+- `/cbp-ship` skill — orchestrator that sequences these calls
+- `.claude/rules/git-workflow.md` — branch/commit conventions enforced before any of these commands run

package/templates/skills/cbp-ship/reference/npm-publish-monorepo.md

@@ -0,0 +1,252 @@
+# Monorepo Publishing — pnpm Workspaces
+
+Publishing one or more packages from a pnpm workspace. Workspace layout, `pnpm publish` vs `npm publish`, per-package `publishConfig`, version-management tools (changesets vs release-please), public/private separation, pre-publish gates.
+
+## Workspace Layout
+
+A typical pnpm monorepo with mixed published and internal packages:
+
+```
+repo/
+├── pnpm-workspace.yaml
+├── package.json                # private: true; root tooling only
+├── packages/
+│   ├── published/
+│   │   ├── cli/                # @codebyplan/cli — published
+│   │   ├── design-tokens/
+│   │   └── auth/
+│   └── internal/
+│       ├── eslint-config/      # @codebyplan/eslint-config — private
+│       └── tsconfig/
+└── apps/
+    ├── web/                    # not published
+    └── backend/
+```
+
+`pnpm-workspace.yaml`:
+
+```yaml
+packages:
+  - "packages/*/*"
+  - "apps/*"
+```
+
+`packages/published/*` vs `packages/internal/*` is **organisational**. What keeps internal packages off the registry is `"private": true` in their `package.json` — pnpm refuses to publish private packages and skips them silently in `pnpm -r publish`.
+
+## Root `package.json`
+
+Always private at the root — never accidentally publish the workspace meta-package:
+
+```json
+{
+  "name": "codebyplan-monorepo",
+  "private": true,
+  "scripts": {
+    "build": "turbo run build",
+    "test": "turbo run test",
+    "lint:packages": "turbo run lint:package",
+    "release": "changeset publish"
+  }
+}
+```
+
+## Per-Package `package.json`
+
+A published workspace package needs `publishConfig`:
+
+```json
+{
+  "name": "@codebyplan/cli",
+  "version": "1.4.2",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": { "codebyplan": "./dist/cli.js" },
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=20" },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codebyplan/codebyplan.git",
+    "directory": "packages/published/cli"
+  }
+}
+```
+
+Notes:
+
+- `repository.directory` tells the registry which subfolder this package lives in. Required for provenance attestations to validate.
+- `publishConfig.access: "public"` is required for scoped packages (`@codebyplan/*`). Without it the first publish fails with `402 Payment Required`.
+- `publishConfig.provenance: true` is the package.json equivalent of `--provenance` on the CLI.
+
+An internal package just sets `"private": true`:
+
+```json
+{
+  "name": "@codebyplan/eslint-config",
+  "version": "0.0.0",
+  "private": true,
+  "main": "./index.js"
+}
+```
+
+## `pnpm publish` vs `npm publish`
+
+| Capability | `pnpm publish` | `npm publish` |
+|------------|----------------|----------------|
+| Recursive (`-r`) — publish all changed packages | Yes | No |
+| `--filter` to scope to a subset | Yes | No |
+| Auto-includes workspace root `LICENSE` | Yes | No |
+| Rewrites `workspace:*` deps to actual versions in tarball | Yes — automatic | No |
+| `--no-git-checks` | Yes | No |
+| OIDC trusted publishing | Yes (npm CLI underneath) | Yes |
+
+For a pnpm monorepo, **always use `pnpm publish`** — `npm publish` will leak `workspace:*` protocol strings into the published tarball and consumers will get install errors.
+
+`pnpm publish -r` only publishes packages whose `version` is not already on the registry — safe to run repeatedly.
+
+## Version Management — Changesets vs release-please
+
+Two dominant tools. Both work with pnpm + GitHub Actions OIDC.
+
+### Changesets
+
+Maintainer-friendly — every PR adds a `.changeset/*.md` file declaring intent:
+
+```
+.changeset/funky-tigers-dance.md
+---
+"@codebyplan/cli": minor
+"@codebyplan/auth": patch
+---
+
+Added --provenance flag to publish command. Auth payload now includes scope.
+```
+
+Workflow:
+
+1. `pnpm changeset` while authoring a PR. Pick affected packages and bump types.
+2. PR merges to main. Changesets GitHub Action opens (or updates) a "Version Packages" PR that consumes pending changesets, bumps versions, regenerates CHANGELOGs.
+3. Merging the Version Packages PR triggers `pnpm changeset publish` → calls `pnpm publish -r` for every bumped package.
+
+`.changeset/config.json` essentials:
+
+```json
+{
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": ["@codebyplan/web", "@codebyplan/backend"]
+}
+```
+
+`ignore` excludes apps that are deployed but never published.
+
+Strengths: explicit intent per change; supports linked/fixed package groups; rich CHANGELOG output. Weaknesses: every PR must remember to add a changeset (the bot enforces this).
+
+### release-please
+
+Conventional-commit-driven — version is inferred from commit messages (`feat:` → minor, `fix:` → patch, `feat!:` or `BREAKING CHANGE:` → major):
+
+1. Developer writes conventional-commit messages.
+2. release-please GitHub Action watches main, opens a release PR per package summarising commits since the last tag.
+3. Merging the release PR creates a git tag, GitHub release, and triggers a separate publish workflow.
+
+`release-please-config.json`:
+
+```json
+{
+  "packages": {
+    "packages/published/cli": { "release-type": "node" },
+    "packages/published/auth": { "release-type": "node" }
+  },
+  "plugins": ["node-workspace"]
+}
+```
+
+The `node-workspace` plugin keeps `workspace:*` deps in sync across the bump.
+
+Strengths: zero per-PR ceremony when commit hygiene is enforced. Weaknesses: monorepo config is more involved; granular bump control is harder.
+
+### Picking one
+
+- Conventional commits enforced → release-please.
+- Want explicit per-PR intent and rich CHANGELOGs → Changesets.
+- OSS / mixed contributors → Changesets (the bot reminds people).
+
+CodeByPlan uses Changesets for `packages/published/*`.
+
+## Pre-Publish Gates
+
+Run these in CI before `pnpm publish -r`:
+
+| # | Gate | Command |
+|---|------|---------|
+| 1 | Build | `pnpm -r --filter "./packages/published/*" build` |
+| 2 | Test | `pnpm -r --filter "./packages/published/*" test` |
+| 3 | publint | `pnpm -r --filter "./packages/published/*" exec publint` |
+| 4 | attw | `pnpm -r --filter "./packages/published/*" exec attw --pack .` |
+| 5 | Dry-run pack | `pnpm -r --filter "./packages/published/*" publish --dry-run` |
+
+[publint](https://publint.dev) catches missing `exports`, broken `main` pointers, type-definition exclusion, ESM/CJS misalignment. [Are The Types Wrong](https://arethetypeswrong.github.io/) validates that the published tarball resolves correctly under both CJS and ESM consumers across conditional-export combinations.
+
+The dry-run output lists every file that would be in the tarball plus total size. Compare against `files` in `package.json` — anything outside `files` means the glob is wrong (or `.npmignore` is interfering).
+
+`pnpm publish -r` skips already-published versions automatically, but for clarity:
+
+```bash
+pnpm -r --filter "./packages/published/*" exec sh -c \
+  'npm view "$npm_package_name@$npm_package_version" version 2>/dev/null \
+   && echo "ALREADY PUBLISHED" && exit 1 || true'
+```
+
+Wire gates 3-4 as a turbo task in each package's `package.json`:
+
+```json
+{
+  "scripts": {
+    "lint:package": "publint && attw --pack ."
+  }
+}
+```
+
+Then in CI before publish: `pnpm turbo run lint:package`.
+
+## Public / Private Separation Recap
+
+| Layer | Mechanism | Purpose |
+|-------|-----------|---------|
+| Folder convention | `packages/published/*` vs `packages/internal/*` | Human signal |
+| `private: true` | `package.json` per internal package | Hard block — pnpm refuses to publish |
+| Changesets `ignore` | `.changeset/config.json` | Keeps deployed apps off the version PR |
+| Workspace dep protocol | `"@codebyplan/foo": "workspace:*"` | Internal deps stay internal; pnpm rewrites at publish time |
+
+When an internal package is published by mistake:
+
+1. `npm unpublish @scope/pkg@x.y.z` within 72 hours, OR
+2. `npm deprecate @scope/pkg@"<= x.y.z" "Internal package — do not use"` after that.
+
+Then add `"private": true` and ship.
+
+## Sources
+
+- [pnpm — publish](https://pnpm.io/cli/publish)
+- [pnpm — workspaces](https://pnpm.io/workspaces)
+- [npm Docs — package.json](https://docs.npmjs.com/cli/v10/configuring-npm/package-json)
+- [Changesets](https://github.com/changesets/changesets)
+- [release-please](https://github.com/googleapis/release-please)
+- [publint](https://publint.dev/)
+- [Are The Types Wrong](https://arethetypeswrong.github.io/)
+- [npm CLI source](https://github.com/npm/cli)

package/templates/skills/cbp-ship/reference/npm-publish-oidc-trusted.md

@@ -0,0 +1,157 @@
+# npm OIDC Trusted Publishing
+
+Modern publish flow: no NPM_TOKEN, no leak risk. npm trusts a short-lived OIDC token issued by your CI provider. Provenance attestations are generated automatically and recorded in a public transparency ledger (Sigstore).
+
+This is the **default publish path for `/cbp-ship`** when the npm-package surface is in play — it's the publish path the orchestrator should reach for first.
+
+## How It Works
+
+1. CI job starts. The CI provider (GitHub Actions, GitLab CI, CircleCI) mints a short-lived OIDC ID token signed with its public key.
+2. `npm publish` reads the OIDC token from the runner and exchanges it with the npm registry for a one-shot publish credential.
+3. npm validates the OIDC token's claims — `repository`, `workflow`, `ref`, `aud` — against the trusted-publisher rule registered for the package.
+4. If the claims match, the publish is accepted. If not, the publish is rejected with `403`.
+5. (GitHub Actions / GitLab only) npm automatically generates a Sigstore provenance attestation linking the published tarball to the exact commit, workflow file, and runner image that built it. The attestation is logged to the [Rekor transparency ledger](https://search.sigstore.dev/).
+
+The OIDC token's lifetime is measured in minutes; it is bound to the workflow run; it cannot be replayed. There is nothing for an attacker to exfiltrate from the runner that survives the job.
+
+## Supported Providers
+
+| Provider | OIDC | Auto-provenance |
+|----------|------|-----------------|
+| GitHub Actions (GitHub-hosted runners) | Yes | Yes |
+| GitLab CI/CD (GitLab.com shared runners) | Yes | Yes |
+| CircleCI cloud | Yes | No (must pass `--provenance` manually with extra setup) |
+| Self-hosted runners (any provider) | Not supported | Not supported |
+
+Self-hosted runners cannot use trusted publishing today — the npm registry does not yet validate signing certificates from non-cloud OIDC issuers.
+
+## Setup — GitHub Actions
+
+### Step 1 — Register the trusted publisher on npmjs.com
+
+1. Sign in at https://www.npmjs.com.
+2. Navigate to your package: `npmjs.com/package/<your-pkg>`.
+3. Settings → **Trusted Publishers** → **Add publisher**.
+4. Select **GitHub Actions**, then fill in:
+   - **Organization or user**: e.g. `codebyplan`
+   - **Repository**: e.g. `codebyplan`
+   - **Workflow filename**: e.g. `release.yml` (just the filename, not the full path)
+   - **Environment** (optional): e.g. `production` — restricts to runs scoped to a GitHub Actions environment
+
+If the package does not yet exist on the registry, you must publish it once with a classic token before you can register a trusted publisher (npm requires the package to exist to attach a trust rule).
+
+### Step 2 — Update the workflow
+
+Add `id-token: write` to the job's permissions and use a recent npm CLI (≥9.5.0; npm 10+ is recommended).
+
+```yaml
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read       # checkout
+      id-token: write      # OIDC — required for trusted publishing
+      attestations: write  # required for provenance attestations
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+
+      - run: pnpm install --frozen-lockfile
+
+      - run: pnpm build
+
+      - run: pnpm test
+
+      - name: Verify publish (dry run)
+        run: pnpm publish --dry-run --access public
+
+      - name: Lint package shape
+        run: |
+          pnpm dlx publint
+          pnpm dlx @arethetypeswrong/cli --pack
+
+      - name: Publish to npm
+        run: pnpm publish --access public --provenance --no-git-checks
+```
+
+Notes:
+
+- **No `NODE_AUTH_TOKEN` env var.** That's the entire point — there is no token to leak. The `setup-node` action wires up `.npmrc` to the registry URL; OIDC handshake happens inside `npm publish`.
+- `--provenance` is **automatic** on GitHub Actions OIDC publishes (npm enables it implicitly), but passing the flag is harmless and makes intent explicit. `publishConfig.provenance: true` in `package.json` is the third equivalent.
+- `--no-git-checks` (pnpm-only) bypasses the "current branch must be the publish branch, working tree must be clean" check. Safe in CI where the runner has a fresh clone at a tag.
+
+## Provenance Attestations
+
+A provenance attestation is a JSON document signed by Sigstore that describes:
+
+- The source repository URL and the exact commit SHA that was built.
+- The workflow file path and the run ID.
+- The builder identity (e.g. `https://github.com/actions/runner`).
+- The npm package name, version, and tarball SHA.
+
+After publish, the npm registry shows a "Provenance" badge on the package page linking to the Sigstore record.
+
+### Verifying attestations as a consumer
+
+```bash
+npm audit signatures
+```
+
+This walks every dependency in the current project, checks the registry signature on each tarball, and validates any provenance attestations. A failure means either the package was tampered with after publish or its signing identity changed unexpectedly.
+
+For a single package without installing it:
+
+```bash
+npm view <pkg> --json | jq '.dist.attestations'
+```
+
+Returns the URL of the attestation bundle on the registry; the bundle is a Sigstore-format JSON that can be verified with `cosign` or the `sigstore-js` library.
+
+## Comparison vs Classic NPM_TOKEN
+
+| Aspect | Classic NPM_TOKEN | OIDC Trusted Publishing |
+|--------|-------------------|--------------------------|
+| Secret stored in CI | Yes — long-lived token | No |
+| Rotation burden | Manual; forgotten tokens are common | None — every publish mints a fresh credential |
+| Leak blast radius | Token works from anywhere until revoked | Credential expires in minutes; bound to one workflow run |
+| Provenance | Manual `--provenance` + extra setup | Automatic on GitHub Actions / GitLab |
+| Setup complexity | Generate token, paste into CI secrets | One-time npm web UI registration |
+| Works on self-hosted runners | Yes | No (today) |
+| Works locally | Yes | No (no OIDC issuer) |
+
+Classic tokens still have a place: local release machines, self-hosted runners, providers npm doesn't trust yet. For everything else, OIDC is the default in 2026.
+
+## Failure Modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `403 Forbidden — OIDC publish requires id-token: write` | Workflow missing the permission | Add `permissions.id-token: write` to the job |
+| `403 — trusted publisher mismatch` | Workflow filename, repo, or org doesn't match the rule | Re-check the trusted-publisher rule on npmjs.com matches `${{ github.repository }}` and `${{ github.workflow_ref }}` exactly |
+| `Provenance generation failed: repository field mismatch` | `package.json` `repository.url` doesn't match the GitHub repo URL | Set `"repository": { "type": "git", "url": "git+https://github.com/<org>/<repo>.git" }` (case-sensitive) |
+| Attestations missing on the registry page | Used CircleCI without manual provenance setup | Either accept (CircleCI limitation) or migrate to GitHub Actions / GitLab |
+| `OIDC token unavailable` from a self-hosted runner | Trusted publishing not supported there | Fall back to a granular token, or move the publish job to a GitHub-hosted runner |
+
+## Sources
+
+- [npm Docs — Trusted publishers](https://docs.npmjs.com/trusted-publishers)
+- [npm Docs — Generating provenance statements](https://docs.npmjs.com/generating-provenance-statements)
+- [npm Docs — npm audit signatures](https://docs.npmjs.com/cli/v10/commands/npm-audit)
+- [Sigstore](https://www.sigstore.dev/) — signing infrastructure
+- [npm CLI source](https://github.com/npm/cli)