@usepowerplant/cli 0.4.5 → 0.4.6

package/README.md

@@ -143,26 +143,66 @@ it is no longer tested or fixed, so update when you see it.
 
 ### How a release reaches production
 
-Every release is published to npm's `next` dist-tag. Machines pinned to
-the staging environment (and our own development and agent machines)
-follow `next`, so a release runs on our own machines first. Production
-machines never follow npm: they ask the production API which version is
-promoted and install exactly that, pinned. When a release has held up on
-staging, dispatch the Promote CLI workflow (leave the version blank to
-promote what `next` points at) with a current one-time code for the
-`forestwalklabs` npm account from 1Password: it moves npm's `latest` to
-the same artifact staging tested, so a fresh `npm install -g` always gets
-exactly what production runs, and points production machines at it;
-machines with automatic updates install it within the hour, and everyone
-else sees it in the menu bar and `powerplant status`. Until something is
-promoted, production sees no update at all, only the supported-version
-floor. Promoting an older version than the current one is a hold:
-production stops advancing, `latest` moves back for new installs, and no
-enrolled machine downgrades. A bad release is undone by a new release and
-a new promotion.
+The same CLI package serves every environment. Staging, development, and
+agent installs follow npm's `next` tag; enrolled production installs follow
+the exact version promoted through the production API. Fresh installs
+without a tag resolve npm's `latest`. Use a separate staging install below
+to test `next` while keeping your production install on its promoted version.
+
+1. **Release.** The "Release CLI to next" workflow (GitHub Actions,
+   manual) builds the CLI, signs and notarizes the menu bar app into the
+   package, and publishes to the `next` tag. Staging, development, and
+   agent installs with automatic updates enabled check at boot and hourly
+   while the service is running. Sleeping machines, disabled updates, and
+   failed installs can leave a machine behind. Verify the installed staging
+   version and exercise sync and the menu actions you changed before
+   promoting; elapsed time alone is not evidence of testing.
+2. **Promote.** From a repo checkout with npm package access and `gh`
+   signed in, name the version you tested:
+
+   ```bash
+   pnpm cli:promote:release 0.5.0
+   ```
+
+   Or, if `next` still points at that tested version:
+
+   ```bash
+   pnpm cli:promote:release
+   ```
+
+   Omitting the version resolves `next` when the command runs.
+   The script moves npm's `latest` from your terminal, with your security
+   key in the browser (npm requires a live second factor for every
+   dist-tag move, so no CI credential can do this half), then dispatches
+   the Promote CLI workflow, which verifies the tag and points production
+   machines at the same artifact. The script watches the workflow; confirm
+   the pointer write succeeded before calling the promotion complete.
+   If the tag moved but that write failed, fresh installs are ahead of
+   enrolled machines. Re-dispatch **the same version**, then check that run:
+
+   ```bash
+   gh workflow run promote-cli.yml -f version=0.5.0
+   ```
+
+   A failed Slack announcement after a successful pointer write does not
+   undo promotion. Read the failed step before retrying.
+3. **Adopt.** Running production services with automatic updates enabled
+   check for the promoted version at boot and hourly. Other users can
+   update from the menu bar or `powerplant update`; `powerplant status`
+   reports the available version. Until something is promoted, production
+   sees no update target, only the supported-version floor.
+
+Promoting an older version is the brake: production holds there, `latest`
+moves back for new installs, and no enrolled machine ever downgrades. A
+bad release is undone by a new release and a new promotion.
 
 ### Staging beside production on one Mac
 
+Use production for day-to-day team work. Staging is for testing enrollment,
+onboarding, and releases. See the [internal machine setup guide](../../README.md#set-up-your-machine)
+for access and data boundaries: running sync in both environments uploads
+and processes eligible sessions twice.
+
 A machine has one global `powerplant` by default, and the background sync
 for each environment runs whatever copy `init` was run from. To try
 releases on staging while production keeps the promoted version, give
@@ -173,6 +213,12 @@ npm install -g --prefix ~/.powerplant-staging @usepowerplant/cli@next
 ~/.powerplant-staging/bin/powerplant init --env staging
 ```
 
+`init --env staging` also points each selected agent's shared `powerplant`
+MCP connection at staging. Separate npm prefixes do not isolate that entry.
+After testing, run `powerplant connect` from your production install to
+restore the agents' production connection; the staging sync service keeps
+running. Include `--env staging` on every staging command.
+
 The `@next` pin matters: a bare install resolves `latest`, the production
 channel, so the new staging copy would start on the promoted release and
 test nothing until its first update.
@@ -181,9 +227,36 @@ The staging daemon runs that copy and updates it in place (the updater
 pins npm to the prefix the running copy lives under), so
 `~/.powerplant-staging` follows the `next` channel while the production
 install follows the promoted one. Run staging commands through that path,
-`~/.powerplant-staging/bin/powerplant status --env staging`, or put the
-directory on your PATH after the production one. `powerplant doctor` names
-the install it is running from.
+`~/.powerplant-staging/bin/powerplant status --env staging`.
+Use `~/.powerplant-staging/bin/powerplant update --env staging` to update
+now, then `~/.powerplant-staging/bin/powerplant doctor --env staging` to
+check the installed version, service, and install location.
+
+### Menu bar apps during release testing
+
+The npm package, including `@next`, contains **Powerplant.app**, the
+production app. Only production `init` installs it and the production
+service refreshes it after CLI updates. Staging `init` does neither.
+
+Run **Powerplant Staging.app** separately, alongside production. Its icon
+has an "S", and it uses the CLI at `~/.powerplant-staging/bin/powerplant`
+when present. Follow the menu bar app's [local build instructions](../../apps/menubar/README.md#development)
+or [signed release instructions](../../apps/menubar/README.md#release).
+Rebuild or replace that staging app when testing native app changes;
+updating the staging CLI does not update it. This tests the staging variant,
+not the exact signed production bundle embedded in the npm package.
+
+### Web and API promotion is separate
+
+Merges to `main` deploy to staging automatically. The
+[Promote to Production workflow](../../.github/workflows/promote.yml) can
+promote the live staging API commit after its E2E check passes, with the
+production schema and web build from that commit. Automatic runs happen
+on CI completion and an hourly catch-up during weekdays, 09:00 to before
+16:00 America/Vancouver, unless `AUTO_PROMOTE_PAUSED=true`. A manual
+workflow dispatch can promote outside that window. Staging does not wait
+indefinitely for manual QA. This workflow does not promote the CLI;
+`pnpm cli:promote:release` does not deploy the web or API.
 
 ### Moving from @powerplant-sh/cli