chore: migrate to npm Trusted Publishers for secure publishing

Switched from NPM_TOKEN to npm Trusted Publishers (OIDC):
- No more token rotation every 90 days
- Packages now published with cryptographic provenance
- Updated workflow to use --provenance flag
- Updated docs with setup instructions

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: PatrickSys

.github/workflows/release-please.yml

@@ -8,6 +8,7 @@ permissions:
   contents: write
   pull-requests: write
   issues: write
+  id-token: write  # REQUIRED for npm provenance
 
 jobs:
   release-please:
@@ -59,8 +60,10 @@ jobs:
           pnpm test
           pnpm build
 
-      - name: Publish
+      - name: Publish to npm with provenance
         if: ${{ steps.release.outputs.release_created && env.SKIP_PUBLISH != 'true' }}
-        run: pnpm publish --access public --no-git-checks
+        run: pnpm publish --access public --no-git-checks --provenance
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          # Note: Keep NPM_TOKEN during transition for fallback
+          # Remove after verifying OIDC works for one successful publish

RELEASING.md

@@ -7,23 +7,35 @@ We use a clean OSS-style flow:
 - PRs merge into `master` (nothing publishes on merge)
 - A release is created by a dedicated **Release PR** opened/updated automatically
 - When the Release PR is merged, CI creates a git tag like `v1.2.3`
-- When a release tag is created, CI publishes to npm automatically
+- npm publish happens automatically in the same workflow run
+- Packages are published with provenance attestations (supply chain security)
 
 ## One-time setup (maintainers)
 
-1. Add a repository secret: `NPM_TOKEN`
-   - Create an npm access token with publish rights for `codebase-context`
-   - Add it in GitHub: Settings > Secrets and variables > Actions > New repository secret
-   - If your npm tokens expire (for example after 90 days), rotate the token and update this secret before it expires
+### 1. Configure npm Trusted Publisher (Provenance)
 
-2. (Recommended) Protect `master`
-   - Require PRs (no direct pushes)
-   - Require the `Tests` workflow to pass
+On npmjs.com:
+1. Navigate to https://www.npmjs.com/package/codebase-context/access
+2. Scroll to "Publishing access" → "Trusted publishers"
+3. Configure GitHub Actions:
+   - Organization: PatrickSys
+   - Repository: codebase-context
+   - Workflow: release-please.yml
+   - Environment: (leave empty)
 
-3. Allow Release Please to open PRs
-   - GitHub: Settings > Actions > General
-   - Set Workflow permissions to "Read and write"
-   - Enable "Allow GitHub Actions to create and approve pull requests"
+This enables OIDC authentication and automatic provenance generation.
+No NPM_TOKEN needed! No token rotation!
+
+### 2. (Recommended) Protect `master`
+
+- Require PRs (no direct pushes)
+- Require the `Tests` workflow to pass
+
+### 3. Allow Release Please to open PRs
+
+GitHub: Settings > Actions > General
+- Set Workflow permissions to "Read and write"
+- Enable "Allow GitHub Actions to create and approve pull requests"
 
 ## Normal release flow
 
@@ -38,7 +50,46 @@ We use a clean OSS-style flow:
 3. When you're ready to ship, merge the Release PR.
    - This creates a git tag `vX.Y.Z` and a GitHub Release
    - The `Release Please` workflow publishes to npm as part of the same run
+   - Provenance attestation is generated automatically
+
+## Verifying a release
+
+After merging a release PR:
+
+1. Check GitHub Actions workflow completed successfully
+2. Verify package on npm: `npm view codebase-context@X.Y.Z`
+3. Verify provenance: `npm view codebase-context@X.Y.Z --json | jq .dist`
+4. Check for `attestations` field in npm package metadata
+5. Verify tag exists: `git fetch --tags && git tag | grep vX.Y.Z`
+
+## Troubleshooting
+
+**"Version already published" in workflow logs**
+- This is normal behavior (idempotency protection)
+- The version was already published successfully
+
+**Workflow fails at "Quality gates"**
+- Run `pnpm lint`, `pnpm format:check`, `pnpm type-check`, `pnpm test` locally
+- Fix issues and push to the release PR branch
+- Workflow will re-run automatically
+
+**Provenance not appearing**
+1. Verify trusted publisher configuration on npmjs.com matches exactly:
+   - Organization: PatrickSys (case-sensitive)
+   - Repository: codebase-context
+   - Workflow: release-please.yml
+2. Check workflow has `id-token: write` permission
+3. Verify npm CLI version ≥ 11.5.1 in workflow logs
+4. Ensure `--provenance` flag is in publish command
+
+## Legacy: NPM_TOKEN (no longer needed)
+
+npm Trusted Publishers uses OIDC authentication. No token management required.
 
-## Notes
+If you need to use a token (e.g., for local testing):
+1. Create an npm access token with publish rights
+2. Add it as GitHub secret: `NPM_TOKEN`
+3. Add to workflow: `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}`
+4. Tokens expire every 90 days and must be rotated
 
-- If a version is already published on npm, CI skips the publish step (useful when seeding historical tags).
+**Not recommended for production workflows in 2026.**