feat: add npm nightly release channel (#2126)

docs/run-as-a-service.md

@@ -1,6 +1,12 @@
 # Run Kandev as a Service
 
-Install Kandev as an OS-managed service (systemd on Linux, launchd on macOS) so it auto-starts and stays running. User-mode services installed by `kandev service install` can self-update from the System → Updates page. Non-service installs and `--system` services still update manually: `npm i -g kandev@latest` or `brew upgrade kandev`, then re-run `kandev service install`.
+Install Kandev as an OS-managed service (systemd on Linux, launchd on macOS) so it auto-starts and stays running. User-mode services installed by `kandev service install` can self-update from the System → Updates page. A verified managed global-npm user service can select Stable (the default) or the npm Nightly channel there. An npx-launched service has the same controls, but its executable lives in npm's disposable cache; use it only as a temporary or recovery path, and prefer global npm for persistent services. Homebrew, non-service, local-checkout, and `--system` installs remain Stable-only.
+
+Manual updates must preserve the install type and selected channel: global npm uses `kandev@latest`
+for Stable or `kandev@nightly` for Nightly; the temporary npx recovery path accepts the same tags;
+Homebrew uses `brew upgrade kandev`; and a local checkout is rebuilt with `make service-install`.
+Reuse custom `--port`, `--home-dir`, and `--no-boot-start` (Linux user mode only) values on
+`service install`; `service restart` carries only `--system` when applicable.
 
 This guide assumes you've already installed kandev via [Homebrew or npm](../apps/cli/README.md#quick-start) and that `kandev` works when run interactively.
 
@@ -96,18 +102,40 @@ kandev service config [--system]
 
 If Kandev is running as a user-mode service installed by `kandev service install`, open **Settings → System → Updates** and use **Apply update** when it appears. The button is shown only when the backend can prove it is running from a kandev-managed service unit/plist with valid service metadata.
 
-Both npm runtime packages and Homebrew install kandev under versioned package-manager paths. Manual upgrades replace those paths, so the unit file must be refreshed afterward.
+Package-manager installs use versioned paths. Manual upgrades replace those paths, so a service unit must be refreshed afterward.
 
-**Manual fix:** re-run install. It's idempotent.
+Use the commands for the original install type:
 
 ```bash
-npm i -g kandev@latest          # or: brew upgrade kandev
-kandev service install          # rewrites the unit with the new paths
+# Reuse these install-time options only if the original service used them:
+# --home-dir /path/to/kandev-home --port 38429
+# --no-boot-start  # Linux user mode only
+# Keep latest for Stable; change to nightly when the saved channel is Nightly.
+CHANNEL_TAG=latest
+
+# Global npm user service
+npm i -g "kandev@$CHANNEL_TAG"
+kandev service install  # append original install-time options here
+kandev service restart
+
+# Temporary npx recovery path. This points into npm's disposable cache; do not
+# rely on it for a persistent service. Move to global npm when recovery is complete.
+npx -y "kandev@$CHANNEL_TAG" service install  # append original install-time options here
+npx -y "kandev@$CHANNEL_TAG" service restart
+
+# Homebrew user service (Stable only)
+brew upgrade kandev
+kandev service install  # append original install-time options here
+kandev service restart
+
+# Local checkout service
+make service-install HOME_DIR=/path/to/kandev-home PORT=38429 NO_BOOT_START=1  # preserve values when used
+make service-restart
 ```
 
 If you launch `kandev` interactively after an upgrade, it will detect a stale unit and print a one-line reminder. You can also check with `kandev service config` to see the paths that would be baked in by the next install.
 
-System services (`kandev service install --system`) do not expose UI self-update. Update them from a privileged shell, then re-run `sudo kandev service install --system`.
+System services (`kandev service install --system`) do not expose UI self-update. Update them with their original package manager from a privileged shell, then rerun the matching executable. Preserve custom install-time flags on `service install --system`; use only `--system` on `service restart --system`.
 
 ## Linux Boot-Start (`loginctl enable-linger`)
 
@@ -193,22 +221,20 @@ This happens with `--system` if `SUDO_USER` isn't set (e.g. you logged in as roo
 
 The OS service manager keeps running whatever `ExecStart` it has — it doesn't know about npm/brew upgrades. For managed user services, use **Apply update** on the Updates page. Otherwise, **always re-run `kandev service install` after an upgrade** so the unit picks up the new paths, then `kandev service restart` to pick up new code.
 
+On a managed global-npm user service (or a temporary cache-backed npx service), **Settings → System
+→ Updates** also owns the install-wide Stable/Nightly choice. Nightly follows npm's
+`kandev@nightly` tag; save the choice before applying the exact version shown. To recover, select
+Stable and apply, or manually install `kandev@latest`, reinstall the service, and restart it. There
+is no Homebrew or Desktop Nightly channel.
+
 ## Updating: TL;DR
 
-```bash
-# Option A: managed user service
-# Use Settings -> System -> Updates -> Apply update
-
-# Option B: manual / system service
-# 1. Update the binary
-npm i -g kandev@latest          # or: brew upgrade kandev
-
-# 2. Refresh the unit file (rewrites paths to point at the new version)
-kandev service install          # add --system if that's what you used originally
-
-# 3. (install does this automatically) Verify it came back up
-kandev service status
-```
+- Managed global-npm user service: use **Settings → System → Updates → Apply update**. Eligible services can first save Stable or Nightly.
+- Manual global npm service: install `kandev@latest` for Stable or `kandev@nightly` for Nightly, then run `kandev service install` with the original install-time options and plain `kandev service restart`.
+- Temporary npx recovery: run `npx -y kandev@latest service install` for Stable or replace `latest` with `nightly`, then rerun the matching npx `service restart`. The unit points into `~/.npm/_npx`; migrate to global npm rather than relying on this cache-backed path for a persistent service.
+- Manual Homebrew service: run `brew upgrade kandev`, then `kandev service install` with the original install-time options and plain `kandev service restart`.
+- Local checkout service: preserve `HOME_DIR`, `PORT`, and `NO_BOOT_START` values on `make service-install`; then run `make service-restart` without them.
+- System service: use the matching manual path through a privileged shell; retain `--system` on both service commands and put other original options only on `service install`.
 
 ## Uninstalling