@usepowerplant/cli 0.4.4 → 0.4.6

package/README.md

@@ -24,7 +24,11 @@ re-run at any time — finished steps are skipped with a note:
    ones in scope. If recent sessions name repositories under a macOS-protected
    location such as Documents, init lists the location and asks before reading
    Git metadata there; declining leaves those sessions local. The service
-   starts on login and keeps itself running.
+   starts on login and keeps itself running. On macOS, init also installs
+   the Powerplant menu bar app from this package into `~/Applications` and
+   launches it; the app registers itself to start at login (turn that off
+   from its More menu), and the background service keeps it on the same
+   version as the CLI after every update.
 3. **Add MCP to your agents.** Init lists the agents it found — Claude Code,
    Codex, and Cursor — as checked boxes. They all start selected; use the arrow
    keys and Space to turn off any you want to skip, then press Enter (`--yes`,
@@ -98,6 +102,9 @@ day-to-day upload path on machines that can't run it; asked for explicitly, it
 still runs while paused and says so. `disconnect` is the
 inverse of `connect`: it removes each agent's Powerplant MCP entry and the
 sign-in stored with it, and agents that were never connected just say so.
+Use `powerplant disconnect --client claude` to remove only Claude's connection.
+The `--client` option also accepts `codex` and `cursor`, and can be repeated.
+Omitting it disconnects all detected agents.
 
 ## Updating
 
@@ -136,38 +143,120 @@ it is no longer tested or fixed, so update when you see it.
 
 ### How a release reaches production
 
-Every release is published to npm as `latest`. Machines pinned to the
-staging environment (and our own development and agent machines) follow
-npm, so a release soaks 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 with the version; production 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, and no 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 soak
+for each environment runs whatever copy `init` was run from. To try
 releases on staging while production keeps the promoted version, give
 staging its own copy under its own npm prefix and set it up from there:
 
 ```bash
-npm install -g --prefix ~/.powerplant-staging @usepowerplant/cli
+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.
+
 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 npm's newest release while the production
+`~/.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