docs(sdks): expand npm trusted publishing setup for new packages (#17441)

Author: ioannisj

contents/handbook/engineering/sdks/releases.mdx

@@ -147,16 +147,32 @@ Copy the release workflow from an existing SDK (e.g., [posthog-rs](https://githu
 
 This applies only to npm publishing (not other package registries).
 
-If your SDK publishes to npm using OIDC trusted publishing and the package has never been published before, run this initial setup once before allowing your GitHub Actions workflow to publish:
+If your SDK publishes to npm using OIDC trusted publishing, set it up before allowing your GitHub Actions workflow to publish.
 
-```bash
-npx setup-npm-trusted-publish @posthog/<package-name>
-```
+##### New package (never published before)
 
-If the package has already been published, you can configure trusted publishing directly in npm package settings instead.
+OIDC trusted publishing can only be _configured_ for a package that already exists on npm. For a brand-new package there's nothing to attach the trusted publisher to yet, so the workflow's very first publish can't use OIDC and will fail with a `404`.
+
+To avoid this, bootstrap the package and configure its trusted publisher before enabling the workflow:
+
+1. **Log in to npm** (`npm login`) as a member of the npm org.
+2. **Run `setup-npm-trusted-publish`** to publish a placeholder so the package exists on the registry. This is a manual, authenticated publish (not OIDC). The command is self-contained and publishes from its own temp directory using your global npm auth, so the working directory doesn't matter.
+
+   ```bash
+   npx setup-npm-trusted-publish @posthog/<package-name>
+   ```
+
+3. **Follow the CLI prompts to configure the Trusted Publisher** for the placeholder:
+   - Choose **GitHub Actions** as the publisher.
+   - Fill in the repo details (`PostHog/<repo>`), the release **workflow filename** (e.g. `release.yml`), and the **environment name** (e.g. `NPM Release`).
+   - Under **Allowed actions**, check **Allow npm publish**.
 
 This bootstraps npm trusted publishing for the package so future automated releases can publish successfully.
 
+##### Existing package
+
+If the package has already been published, you can configure trusted publishing directly in npm package settings instead.
+
 > **Casing matters when configuring the trusted publisher.** npm validates the GitHub organization, repository, and workflow filename against the values GitHub puts in the OIDC token, and those values are case-sensitive. The PostHog GitHub organization is `PostHog` (capital `P` and `H`) — entering `posthog` causes the publish to fail with a misleading `404 Not Found` from npm, even though the package and the workflow exist. Use `PostHog` exactly when setting up or editing the trusted publisher, both via `setup-npm-trusted-publish` and in the npm package settings UI.
 
 ### 7. Update the README