docs clarify npm trusted publishing prerequisites

Author: plutoless

AGENTS.md

@@ -258,6 +258,7 @@ packaging/npm/
 6. Smoke-tests the published wrapper with `npx --yes agoraio-cli@<tag> --version` (retry/backoff for registry propagation)
 
 **Prerequisites:**
+- npm package names already exist on the registry before relying on trusted publishing.
 - npm **Trusted Publisher** configured on each package (`agoraio-cli` and all `agoraio-cli-*`), pointing at repo `AgoraIO/cli` and workflow `release.yml`.
 - `id-token: write` workflow permission (already set in `release.yml`) — required for trusted publishing and provenance.
 

CHANGELOG.md

@@ -17,6 +17,7 @@ Earlier entries pre-date this convention and only carry their version's compare
 
 ### Fixed
 
+- Clarify that npm release publishing uses trusted publishing only and requires every npm package to exist before release automation runs.
 - Update GoReleaser Cosign signing to emit `checksums.txt.sigstore.json` with `--bundle`, matching Cosign's current bundle-based signing flow.
 
 ## [0.2.2] - 2026-05-26

RELEASING.md

@@ -25,7 +25,7 @@ The release workflow (`.github/workflows/release.yml`) then:
    - Publishes the six per-platform packages with `npm publish --provenance`
    - Publishes the wrapper package (`agoraio-cli`) with `npm publish --provenance`
    - Runs a post-publish smoke test: `npx --yes agoraio-cli@<tag> --version` with retry/backoff to handle registry propagation
-   - Authenticates via [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC from GitHub Actions — no `NPM_TOKEN` secret)
+   - Authenticates only via [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) (OIDC from GitHub Actions)
    - Requires `id-token: write` workflow permission (already set in `release.yml`)
 
 3. **Apt repository** job (triggered by the published release):
@@ -63,6 +63,7 @@ The release workflow exposes a `workflow_dispatch` trigger that runs the npm pub
 
 Before tagging the first real release that ships npm, confirm:
 
+- [ ] Each npm package exists on npm. Trusted publishing can only be configured after the package exists.
 - [ ] Each npm package has a **Trusted Publisher** configured on [npmjs.com](https://www.npmjs.com) (Package → Settings → Trusted Publisher → GitHub Actions):
   - Repository: `AgoraIO/cli`
   - Workflow filename: `release.yml`