docs: note that a first npm publish is manual under trusted publishing

AGENTS.md

@@ -101,10 +101,11 @@ These rules exist because Shaders doubles as a shader-learning project for its a
      2. Confirm zero listeners on each port. If one survives, `kill -9` it. Measured 2026-09-04: `next dev` wedged at full CPU three times after a batch of edits to `apps/docs/src/content`, stopped answering every route, and ignored SIGTERM. A Playwright run then reuses the wedged server and hangs forever, because `reuseExistingServer` only checks that the port answers a connection.
      3. Delete that app's `.next`.
      4. Start the server. Deleting `.next` while a server boots gives a 500 on a missing `routes-manifest.json`.
-- **npm publish uses OIDC trusted publishing**, and `pnpm publish` always delegates the actual PUT to whatever `npm` is on PATH. The working combination is pnpm 10 plus `npm install -g npm@11`. Three things break it:
+- **npm publish uses OIDC trusted publishing**, and `pnpm publish` always delegates the actual PUT to whatever `npm` is on PATH. The working combination is pnpm 10 plus `npm install -g npm@11`. Four things break it:
   - npm 10 has no OIDC, which gives ENEEDAUTH.
   - npm 12 rejects pnpm's forwarded `--git-checks`, which gives EUNKNOWNCONFIG.
   - A `registry-url` in setup-node writes an empty-token authline that skips OIDC, so the PUT goes out anonymous and comes back masked as E404.
+  - A package that has never been published, which also gives ENEEDAUTH. The trusted publisher is configured on the package's settings page on npmjs.com, and a package has no page until its first version exists, so the workflow's OIDC exchange has nothing to match. Publish the first version by hand. Run `npm login` from a directory outside the repo, because the root `devEngines` pin rejects bare `npm` inside it, then run `pnpm publish` from the package directory. Then add the trusted publisher on npmjs.com, with organization `campdotdev`, repository `shaders`, workflow `release.yml`, and "Allow npm publish" ticked, because `changeset publish` calls plain `npm publish` rather than the staged flow. Both packages get the same entry, because the token names the workflow and not the package directory. `changeset publish` creates git tags only after it publishes, so after a manual first publish run `pnpm exec changeset tag` and push the tags by hand. Measured 2026-09-08 on 0.19.0.
 
   E404 or ENEEDAUTH on publish means the auth chain failed, not that the package is missing.
 - **Dev-only routes are named `page.dev.tsx` and need `INCLUDE_DEV_ROUTES=1`.** The docs site is `output: 'export'` with no route filtering, so anything the router can see lands in `out/`, and `pagefind --site out` then indexes it. Unlinked debugging pages were showing up in site search on the deployed site. `next.config.ts` adds `dev.tsx` and `dev.ts` to `pageExtensions` only when that env var is `1`, so a plain `next build` cannot see them. Three things have to stay in sync if you touch this: