docs(release): document admin-pushed promotion and the one-time repository setup

Author: thymikee

CONTRIBUTING.md

@@ -95,18 +95,17 @@ stay unpublished. There are three channels:
 - **Nightly** (`npm install -g agent-device@nightly`): every few hours the workflow checks `main`.
   It publishes `X.Y.Z-nightly.<YYYYMMDD>.<run>` under the `nightly` dist-tag when `main`'s HEAD has
   changed since the last nightly, its CI passed, and no nightly shipped that UTC day. It then tags
-  the commit `v<nightly version>`. To publish one now, run **Release** with `channel: nightly`.
-- **Stable** (`latest`): run **Release** with `channel: stable`. It promotes the latest nightly's
-  commit, by default as the `X.Y.Z` that nightly previewed. Set `version` to release it under
-  another number. The run tags that commit `vX.Y.Z` and starts the stable run on the tag. The stable
-  run waits for approval in the `release` environment, then publishes the packages, drafts the GitHub
-  release with generated notes, attaches the iOS runner and Android helper assets, publishes the
-  release and the MCP Registry entry, and commits `main`'s next `-dev` version. Pushing a `vX.Y.Z`
-  tag yourself starts the same stable run for that commit.
+  the commit `nightly/v<nightly version>`. To publish one now, run **Release** on `main`.
+- **Stable** (`latest`): a repository admin runs `pnpm release:promote`. It pushes `vX.Y.Z` at the
+  latest nightly's commit, by default as the `X.Y.Z` that nightly previewed; pass a version, such as
+  `pnpm release:promote 0.22.0`, to release it under another number. The tag's **Release** run waits
+  for approval in the `release` environment, then publishes the packages, drafts the GitHub release
+  with generated notes, attaches the iOS runner and Android helper assets, publishes the release and
+  the MCP Registry entry, and commits `main`'s next `-dev` version.
 - **Dry run**: a pull request that changes release tooling builds and verifies every package with a
   nightly version, and publishes nothing.
 
-To retry a failed run, re-run its failed jobs. The publisher skips package versions that are already
+To retry a failed run, re-run its failed jobs, or run **Release** on the release tag. The publisher skips package versions that are already
 on npm, so a partial publish completes on the next attempt. To preview the packages locally, run
 `pnpm release:prepare`. It builds, verifies, and packs every public package into `.tmp/release`.
 
@@ -131,6 +130,40 @@ npm trust github @agent-device/<name> --file release.yml --repository callstack/
 npm access set mfa=publish @agent-device/<name>
 ```
 
+### One-time repository setup
+
+npm trusts every run of `release.yml` that reaches the `npm-publish` environment, so GitHub
+settings, not the workflow, decide who can publish. The plan job refuses to publish until the first
+three are in place. Apply them before granting npm trust:
+
+1. **Environment `npm-publish`** (Settings → Environments): deployment branches and tags limited to
+   the branch `main` and the tag pattern `v*`. No reviewers and no secrets, so nightlies run
+   unattended.
+2. **Environment `release`**: required reviewers. Turn on "Prevent self-review" only when another
+   maintainer can approve, because the admin who pushes the tag cannot approve their own run.
+3. **Tag ruleset** (Settings → Rules → Rulesets → New tag ruleset): active, targeting
+   `refs/tags/v*`, restricting creations, updates, and deletions, with only the Repository admin
+   role allowed to bypass. Nightly tags live under `nightly/` and stay outside it.
+4. **Actions** (Settings → Actions → General): workflow permissions set to read repository contents,
+   and "Allow GitHub Actions to create and approve pull requests" turned off.
+
+Confirm the result, then grant npm trust to each public package and, once a nightly has published,
+refuse token-based publishing:
+
+```bash
+gh api repos/callstack/agent-device/environments/npm-publish/deployment-branch-policies \
+  --jq '.branch_policies[] | "\(.type) \(.name)"'   # branch main, tag v*
+gh api repos/callstack/agent-device/environments/release \
+  --jq '.protection_rules[] | select(.type == "required_reviewers")'
+gh api repos/callstack/agent-device/rulesets --jq '.[] | select(.target == "tag") | .name'
+npm trust github <package> --file release.yml --repository callstack/agent-device \
+  --environment npm-publish --allow-publish --yes
+npm access set mfa=publish <package>
+```
+
+Anyone who can push to `main` can still change what the next nightly publishes; `main` does not
+require pull requests.
+
 ### The version on main never equals a published version
 
 `main` carries `X.Y.Z-dev`, naming the release it is building towards. Nightlies preview it as