fix: address agent review feedback

Changes based on parallel review by 4 agents (Kara, Dave, Jason, Gray):

- Add inline comment explaining why SHOPIFY_GH_ACCESS_TOKEN is needed
  instead of GITHUB_TOKEN, and documenting its expected scope
- Add permission comments (contents, pull-requests, id-token)
- Add rollback step to verify no stale .changeset/*.md files exist,
  which would cause the release workflow to open a release PR instead
  of a clean rollback
- Add .env to .gitignore (mitigates @changesets/changelog-github
  calling dotenv.config() unconditionally at import time)

Author: kdaviduik

.github/workflows/npm-release.yml

@@ -18,9 +18,9 @@ jobs:
     runs-on: ubuntu-latest
     if: github.repository_owner == 'Shopify'
     permissions:
-      contents: write
-      pull-requests: write
-      id-token: write
+      contents: write      # push version commits, create GitHub releases
+      pull-requests: write # create/update the "[ci] release" PR
+      id-token: write      # OIDC for npm provenance attestation
     steps:
       - name: Checkout
         uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
@@ -49,6 +49,12 @@ jobs:
           commit: '[ci] release'
           title: '[ci] release'
         env:
+          # A PAT (not the built-in GITHUB_TOKEN) is required here. GitHub
+          # Actions blocks events from GITHUB_TOKEN from triggering workflows,
+          # so merging the release PR would not re-trigger this workflow for
+          # the publish step. SHOPIFY_GH_ACCESS_TOKEN is a GitHub App token
+          # scoped to this repo only (contents:write, pull-requests:write),
+          # rotated every 2 hours via github-actions-access-provider.
           GITHUB_TOKEN: ${{ secrets.SHOPIFY_GH_ACCESS_TOKEN }}
           NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.gitignore

@@ -21,6 +21,10 @@ _site
 /.vscode
 .DS_Store
 
+# Environment files
+.env
+.env.*
+
 # TypeScript build artifacts
 *.tsbuildinfo
 /dist-types

CONTRIBUTING.md

@@ -37,7 +37,11 @@ If your PR doesn't need a new npm release (docs-only changes, test updates, CI c
 Follow these steps to roll back the `latest` CDN version without publishing a normal npm release.
 
 1. Create a branch from `main` and revert the faulty code changes
-2. Do **not** include a changeset file
+2. Do **not** include a changeset file. Verify no stale `.changeset/*.md` files exist (other than `README.md`):
+   ```
+   ls .changeset/*.md
+   ```
+   If any exist, delete them — stale changesets would cause the release workflow to open a release PR instead of a clean rollback.
 3. Append `-ROLLBACK` to the version in `package.json` (e.g., `3.0.6` → `3.0.6-ROLLBACK`)
 4. Run `pnpm install` to update the lockfile
 5. Stage and commit your changes