ci(weekly): open the downloads pull request with a personal access token

.github/AGENTS.md

@@ -12,6 +12,8 @@ These are the same durable learnings the root [`AGENTS.md`](../AGENTS.md) record
 
 - The weekly npm downloads workflow reuses `automation/weekly-npm-downloads`; merge `origin/main` into that branch before committing a new snapshot so an open automation PR does not drift behind `main`.
 
+- The weekly npm downloads workflow pushes and opens its PR with the `WEEKLY_AUTOMATION_TOKEN` fine-grained personal access token (Contents and Pull requests read/write on this repository only), never `GITHUB_TOKEN`: a push or PR made with `GITHUB_TOKEN` leaves that PR's `pull_request` workflows at `action_required`, so every required check waits for a maintainer to approve the runs. Keep the workflow's own `GITHUB_TOKEN` read-only.
+
 - Cloudflare Workers Builds watch paths are represented by [`.github/cloudflare/docs-watch-paths.json`](../.github/cloudflare/docs-watch-paths.json). Keep the desired list a superset of every docs-build input, including both packages, `.node-version`, `.nvmrc`, and the existing docs/build inputs. Include the gate and configuration policy paths so a policy change forces a real Cloudflare build; the gate uses the union of the immutable merge-base and head policies so a PR cannot hide changes by narrowing its own list. Cloudflare `*` spans `/`, and the owner must sync and verify both live triggers through the documented MCP checklist or dashboard.
 
 - `pr.yml` keeps its privileged comment job on `workflow_run`, so GitHub always runs that job from the default branch. Its separate `pull_request` smoke job has read-only permissions and a fake GitHub client; it exercises the PR version's artifact round trip, TypeScript import, binding, and rendering without making API calls. Keep the smoke job free of write permissions and secrets. Its success does not prove production token delivery, so observe the first natural post-merge benchmark comment after changing the privileged job.

.github/workflows/weekly.yml

@@ -5,9 +5,13 @@ on:
   schedule:
     - cron: "17 3 * * 1"
 
+# Pushes and pull requests made with `GITHUB_TOKEN` leave the pull request's
+# `pull_request` workflows waiting for maintainer approval, so the required
+# checks never report on their own. A fine-grained personal access token
+# (`WEEKLY_AUTOMATION_TOKEN`) pushes and opens the pull request instead, and
+# `GITHUB_TOKEN` stays read-only.
 permissions:
-  contents: write
-  pull-requests: write
+  contents: read
 
 concurrency:
   group: update-weekly-npm-downloads
@@ -50,7 +54,7 @@ jobs:
       - name: Commit and push snapshot
         if: steps.snapshot.outputs.changed == 'true'
         env:
-          GH_TOKEN: ${{ github.token }}
+          GH_TOKEN: ${{ secrets.WEEKLY_AUTOMATION_TOKEN }}
         shell: bash
         run: |
           snapshot="$RUNNER_TEMP/npm-weekly-downloads.json"
@@ -84,7 +88,7 @@ jobs:
       - name: Open or update pull request
         if: steps.snapshot.outputs.changed == 'true'
         env:
-          GH_TOKEN: ${{ github.token }}
+          GH_TOKEN: ${{ secrets.WEEKLY_AUTOMATION_TOKEN }}
         shell: bash
         run: |
           pr_url="$(gh pr list --head "$UPDATE_BRANCH" --base main --state open --json url --jq '.[0].url')"

docs/README.md

@@ -21,7 +21,7 @@ The generator removes stale `docs/.generated/bundle-sizes.json`. It runs each pa
 
 The generator does not compile packages. Root install/prepare provides `dist`. After editing package source, run `pnpm build` or `pnpm --filter <package> build` before direct docs measurement.
 
-The homepage reads weekly npm totals from [`src/content/npm-weekly-downloads.json`](./src/content/npm-weekly-downloads.json). The `weekly / npm-downloads` workflow fetches and validates npm's latest seven-day totals each Monday, then opens or updates a pull request containing the snapshot. Documentation builds read only the checked-in file and never depend on npm's API.
+The homepage reads weekly npm totals from [`src/content/npm-weekly-downloads.json`](./src/content/npm-weekly-downloads.json). The `weekly / npm-downloads` workflow fetches and validates npm's latest seven-day totals each Monday, then opens or updates a pull request containing the snapshot. It pushes and opens that pull request with the `WEEKLY_AUTOMATION_TOKEN` Actions secret, a fine-grained personal access token limited to this repository with Contents and Pull requests read/write, so the pull request's required checks run without a maintainer approving them. Renew the token before it expires, or the weekly run fails. Documentation builds read only the checked-in file and never depend on npm's API.
 
 ## Markdown mirrors