@photon-ai/cli 2.1.0 → 2.3.0-staging.42193655517.1

package/README.md

@@ -332,4 +332,10 @@ See [`docs/cli-design.md`](docs/cli-design.md) and [`docs/cli-build-plan.md`](do
 
 ## Releases
 
-Tagged via PR labels. Add the `release` label to any PR; on merge to `main`, the [Release workflow](.github/workflows/release.yaml) (a thin caller of [`photon-hq/buildspace`'s `typescript-service-release`](https://github.com/photon-hq/buildspace)) generates a version + notes, bumps `package.json`, creates a GitHub Release, and publishes to npm. Standalone binaries are uploaded by [`release-binaries.yaml`](.github/workflows/release-binaries.yaml) on each release.
+Every push to `main` runs the [Release workflow](.github/workflows/release.yaml) to verify and publish a staging candidate through the pinned [Buildspace package workflows](https://github.com/photon-hq/buildspace/tree/c1fb06e4ae457a8e053642a914bd37b8f5ce9e1b/.github/workflows). Manual dispatch defaults to `dry-run`, which verifies and packs without publishing or creating tags or Releases. To release, dispatch `promote` from `main` with the staging version and obtain approval in the `production` environment; promotion publishes the stored candidate under npm's stable `latest` tag without rebuilding or committing a source version bump. A successful new promotion calls [`release-binaries.yaml`](.github/workflows/release-binaries.yaml) and [`docs-reference.yml`](.github/workflows/docs-reference.yml) with that exact stable version.
+
+The pack script builds each channel in a temporary copy with its release version, checks that the archive contains the declared package entry points and binaries, and runs the packed CLI's `--version`. The source manifest and lockfile stay unchanged.
+
+Before the first npm publication, an npm administrator must [configure trusted publishing](https://docs.npmjs.com/trusted-publishers/) for `photon-hq/cli`, caller workflow `release.yaml`, and two environment-specific entries: `staging` and `production`, each allowing `npm publish` and `npm dist-tag`. Publishing uses GitHub OIDC; these workflows do not use `NPM_TOKEN`. Keep any legacy token until the first real promotion succeeds and no active legacy consumer or documented rollback needs it.
+
+The first staging run can create `staging` automatically. Before the first production promotion, a repository administrator must run the [Buildspace environment setup command](https://github.com/photon-hq/buildspace/blob/main/README.md#package-stage-and-promote). The command restricts both environments to `main` and requires at least one production reviewer, using CODEOWNERS by default; append `@USER` or `@ORG/TEAM` after the repository argument if CODEOWNERS supplies no reviewers. Without reviewers, the command exits before changing either environment. [Required reviewers in private repositories need GitHub Enterprise](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments). Production binary and documentation jobs also need the existing release and docs-app permissions.