CLI upgrade path gap: no working self-update for installed users

[justinhelmer]

Problem

Once a user installs the CLI, there is no working path that gets them onto a newer version. New installs are fine — the install script (polylanedotcom/src/assets/install-v0.2.sh) resolves releases/latest at download time, so a fresh curl install/v0.2.sh | bash always pulls the newest release. But an already-installed user has no automatic signal or one-command upgrade, so they can sit on a stale version indefinitely.

Concretely, three gaps:

1. The passive update nudge is dead code. checkForUpdateAsync() (src/commands/update.ts:69) exists to surface "update available" during normal use, but nothing in the command runner calls it (grep for checkForUpdateAsync finds only its definition). So a user gets zero signal they're outdated unless they explicitly run polylane update.

2. polylane update is check-only. It prints Update available: X and tells the user to run npm install -g @coreplane/polylane@X or brew upgrade polylane (src/commands/update.ts ~L60). It never performs the update, and it doesn't mention the re-run-the-installer path (curl -fsSL https://polylane.com/install/v0.2.sh | bash), which is idempotent and is how most curl-installed users actually got the binary.

3. Version source mismatch between install and update. The installer checks GitHub Releases (api.github.com/repos/<repo>/releases/latest), while update checks npm (registry.npmjs.org/@coreplane/polylane/latest). If the release pipeline publishes to the two at different times (or one and not the other), the two paths disagree about what "latest" is, and the upgrade command a curl-installed user is told to run (npm/brew) may not even match how they installed.

Impact

Users who installed via curl … | bash — the primary onboarding funnel for 0.2.x — have no in-product way to learn they're behind and no single command to fix it. As we ship 0.2.x point releases (e.g. v0.2.9 today), the installed base fragments across versions silently.

Proposed direction (not prescriptive)

• Wire the nudge. Call checkForUpdateAsync() from the root command runner (cached, non-blocking, CI-suppressed as it already is) so normal invocations print a one-line "update available: run X" hint on stderr.
• Make update actionable. Either have polylane update perform the upgrade for curl-installed users (re-invoke the install script, or the matching package-manager command based on how it was installed), or at minimum add the curl … install/v0.2.sh | bash re-run line to its output so there is always a copy-paste path that matches the install method.
• Reconcile the version source. Confirm the release pipeline publishes to GitHub Releases and npm together, and have the installer and update read a single source of truth (or at least document why they differ and ensure they can't disagree).

References

• src/commands/update.ts — updateCommand (check-only) and unwired checkForUpdateAsync()
• polylanedotcom/src/assets/install-v0.2.sh:217-247 — GitHub-releases version resolution (POLYLANE_VERSION pin vs releases/latest), idempotent re-run skip
• Umbrella: coreplanelabs/nominal#1165 (unified onboarding)