Document persistent npm authentication and improve release diagnostics

.github/workflows/publish.yml

@@ -38,6 +38,7 @@ jobs:
       - uses: actions/setup-node@v6
         with:
           node-version: 24
+          package-manager-cache: false
 
       - uses: oven-sh/setup-bun@v2
         with:
@@ -87,10 +88,10 @@ jobs:
 
       - name: Validate package
         if: github.event_name == 'workflow_dispatch' && inputs.dry_run
-        run: npm publish --dry-run --access public
+        run: npm publish --dry-run --access public --loglevel verbose
 
       - name: Publish package
         if: steps.registry.outputs.published != 'true' && (github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && !inputs.dry_run))
         env:
           NPM_TAG: ${{ github.event_name == 'workflow_dispatch' && inputs.npm_tag || 'latest' }}
-        run: npm publish --access public --provenance --tag "$NPM_TAG"
+        run: npm publish --access public --provenance --tag "$NPM_TAG" --loglevel verbose

CHANGELOG.md

@@ -3,7 +3,7 @@
 ## [2.1.1] - 2026-10-04
 
 - Fixed release verification for npm 12's package metadata format while retaining compatibility with earlier npm versions. Packed package names and versions are checked against the manifest, and publish dry runs still create and install real test artifacts.
-- First npm release of the AI SDK inspection tool. The 2.1.0 publication stopped during verification before uploading a package; this version includes all changes below.
+- Includes all AI SDK inspection tool changes below. The 2.1.0 publication stopped during verification before uploading a package.
 
 ## [2.1.0] - 2026-10-04
 

registry/README.md

@@ -6,6 +6,19 @@ The public integration guide is `https://zeroleaks.ai/docs/shield-sdk/providers/
 
 Before submitting, confirm that npm serves `@zeroleaks/shield@2.1.1` and the integration guide is live. The source repository, README, public docs, and published package must describe the same exports and supported SDK versions.
 
+Publishing uses the `NPM_TOKEN` Actions secret in the Shield repository's `npm` GitHub environment. The existing workflow configures npm authentication from that secret before publishing. Replace it with `gh secret set NPM_TOKEN --repo ZeroLeaks/shield --env npm`; paste the credential into the hidden prompt, and keep it out of source files.
+
+The workflow also supports [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) as an alternative. An npm package administrator can configure it in the package's [trusted publisher settings](https://www.npmjs.com/package/@zeroleaks/shield/access). Use the exact GitHub owner `ZeroLeaks`, repository `shield`, workflow filename `publish.yml`, and environment `npm`. Permit direct `npm publish`; staged-only permission will not publish this release. The workflow already uses GitHub-hosted runners, Node 24, current npm, and `id-token: write`.
+
+To retry a release, run the current workflow and verify the registry version after it succeeds. Verbose npm logs report the OIDC exchange reason if authentication fails:
+
+```bash
+gh workflow run publish.yml --repo ZeroLeaks/shield --ref master -f dry_run=false -f npm_tag=latest
+npm view @zeroleaks/shield@2.1.1 version
+```
+
+Confirm the integration guide is deployed before submitting upstream. The app documentation PR requires a review before production deployment: https://github.com/x1xhlol/zeroleaks-v2/pull/229.
+
 Run the release checks from the Shield repository:
 
 ```bash