@usepowerplant/cli 0.4.12 → 0.4.14

package/README.md

@@ -1,3 +1,9 @@
+<!--
+This file is the public npm page of @usepowerplant/cli. Write only what a
+customer needs. Team procedures go in RELEASING.md, which npm does not publish.
+Rule: docs/client-engineering-rules.md, "Releases".
+-->
+
 # @usepowerplant/cli
 
 Set up a machine for [Powerplant](https://powerplant.sh): enroll it into
@@ -19,7 +25,7 @@ re-run at any time — finished steps are skipped with a note:
 1. **Enroll this machine.** Your browser opens so you can approve the
    machine into your org. On macOS, the credential is encrypted in a local
    file with its key in Keychain; other platforms use a file only your user
-   can read. See [credential storage and reset](../../README.md#quick-staging-reset).
+   can read.
 2. **Install the background service.** The sync service watches your local
    coding-agent sessions (Claude Code, Codex, and Cursor) and uploads the
    ones in scope. If recent sessions name repositories under a macOS-protected
@@ -119,8 +125,10 @@ powerplant update
 That reinstalls `@usepowerplant/cli` with whichever package manager put it
 on this machine (npm, pnpm, bun, or yarn), so the copy that is running is the
 copy that gets replaced, then restarts the background sync onto the new
-version. Running the manager's own global install yourself works too: the
-service notices the new version on disk and restarts itself within moments.
+version. When this machine already has the newest version available to it,
+`update` says so and changes nothing. Running the manager's own global
+install yourself works too: the service notices the new version on disk and
+restarts itself within moments.
 When the install can't be replaced this way (a folder only an administrator
 can write, or a layout the CLI doesn't recognise), `update` says why and
 prints the command to run instead. `powerplant status` tells you when a
@@ -144,134 +152,17 @@ The one exception is a registry that does not serve the release yet (npm's
 cache can lag a publish by a few minutes): the sync tries that release
 again on its next hourly checks, up to three times, and the menu says so.
 
+Powerplant offers your machine a release only after the team has tested
+it, so the version it offers can be older than the newest version listed on
+npm. Powerplant never offers or automatically installs a version older
+than the one you have.
+
 Powerplant also publishes the oldest version it still supports. When yours
 is older, `powerplant status`, `powerplant doctor`, the menu bar app, and
 the sync service log all say so and point you at `powerplant update`. Nothing
 stops working on that notice — an unsupported version keeps syncing, but
 it is no longer tested or fixed, so update when you see it.
 
-### How a release reaches production
-
-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. Promote only
-   after the workflow's "Wait until npm serves the release" step is green:
-   npm's CDN caches the package document for about five minutes after a
-   publish, and a production machine that checks inside that window gets
-   "no matching version" and waits an hour to try again.
-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
-staging its own copy under its own npm prefix and set it up from there:
-
-```bash
-npm install -g --prefix ~/.powerplant-staging @usepowerplant/cli@next
-~/.powerplant-staging/bin/powerplant init --env staging
-```
-
-`init --env staging` registers its own MCP entry, `powerplant-staging`, in each
-selected agent, beside the production `powerplant` entry. Agents see its tools
-as `mcp__powerplant-staging__*`. A CLI older than this change registered
-staging as `powerplant`: if that entry still points at staging, run a bare
-`powerplant connect` from your production install once to restore it. 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 the `next` channel while the production
-install follows the promoted one. Run staging commands through that path,
-`~/.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
 
 Releases up to 0.2.1 were published as `@powerplant-sh/cli`. That package