nodmix 2026.5.25

package/docs/install/uninstall.md

@@ -0,0 +1,131 @@
+---
+summary: "Uninstall Nodmix completely (CLI, service, state, workspace)"
+read_when:
+  - You want to remove Nodmix from a machine
+  - The gateway service is still running after uninstall
+title: "Uninstall"
+---
+
+Two paths:
+
+- **Easy path** if `nodmix` is still installed.
+- **Manual service removal** if the CLI is gone but the service is still running.
+
+## Easy path (CLI still installed)
+
+Recommended: use the built-in uninstaller:
+
+```bash
+nodmix uninstall
+```
+
+Non-interactive (automation / npx):
+
+```bash
+nodmix uninstall --all --yes --non-interactive
+npx -y nodmix uninstall --all --yes --non-interactive
+```
+
+Manual steps (same result):
+
+1. Stop the gateway service:
+
+```bash
+nodmix gateway stop
+```
+
+2. Uninstall the gateway service (launchd/systemd/schtasks):
+
+```bash
+nodmix gateway uninstall
+```
+
+3. Delete state + config:
+
+```bash
+rm -rf "${NODMIX_STATE_DIR:-$HOME/.nodmix}"
+```
+
+If you set `NODMIX_CONFIG_PATH` to a custom location outside the state dir, delete that file too.
+
+4. Delete your workspace (optional, removes agent files):
+
+```bash
+rm -rf ~/.nodmix/workspace
+```
+
+5. Remove the CLI install (pick the one you used):
+
+```bash
+npm rm -g nodmix
+pnpm remove -g nodmix
+bun remove -g nodmix
+```
+
+6. If you installed the macOS app:
+
+```bash
+rm -rf /Applications/Nodmix.app
+```
+
+Notes:
+
+- If you used profiles (`--profile` / `NODMIX_PROFILE`), repeat step 3 for each state dir (defaults are `~/.nodmix-<profile>`).
+- In remote mode, the state dir lives on the **gateway host**, so run steps 1-4 there too.
+
+## Manual service removal (CLI not installed)
+
+Use this if the gateway service keeps running but `nodmix` is missing.
+
+### macOS (launchd)
+
+Default label is `ai.nodmix.gateway` (or `ai.nodmix.<profile>`; legacy `com.nodmix.*` may still exist):
+
+```bash
+launchctl bootout gui/$UID/ai.nodmix.gateway
+rm -f ~/Library/LaunchAgents/ai.nodmix.gateway.plist
+```
+
+If you used a profile, replace the label and plist name with `ai.nodmix.<profile>`. Remove any legacy `com.nodmix.*` plists if present.
+
+### Linux (systemd user unit)
+
+Default unit name is `nodmix-gateway.service` (or `nodmix-gateway-<profile>.service`):
+
+```bash
+systemctl --user disable --now nodmix-gateway.service
+rm -f ~/.config/systemd/user/nodmix-gateway.service
+systemctl --user daemon-reload
+```
+
+### Windows (Scheduled Task)
+
+Default task name is `Nodmix Gateway` (or `Nodmix Gateway (<profile>)`).
+The task script lives under your state dir.
+
+```powershell
+schtasks /Delete /F /TN "Nodmix Gateway"
+Remove-Item -Force "$env:USERPROFILE\.nodmix\gateway.cmd"
+```
+
+If you used a profile, delete the matching task name and `~\.nodmix-<profile>\gateway.cmd`.
+
+## Normal install vs source checkout
+
+### Normal install (install.sh / npm / pnpm / bun)
+
+If you used `https://nodmix.ai/install.sh` or `install.ps1`, the CLI was installed with `npm install -g nodmix@latest`.
+Remove it with `npm rm -g nodmix` (or `pnpm remove -g` / `bun remove -g` if you installed that way).
+
+### Source checkout (git clone)
+
+If you run from a repo checkout (`git clone` + `nodmix ...` / `bun run nodmix ...`):
+
+1. Uninstall the gateway service **before** deleting the repo (use the easy path above or manual service removal).
+2. Delete the repo directory.
+3. Remove state + workspace as shown above.
+
+## Related
+
+- [Install overview](/install)
+- [Migration guide](/install/migrating)

package/docs/install/updating.md

@@ -0,0 +1,280 @@
+---
+summary: "Updating Nodmix safely (global install or source), plus rollback strategy"
+read_when:
+  - Updating Nodmix
+  - Something breaks after an update
+title: "Updating"
+---
+
+Keep Nodmix up to date.
+
+## Recommended: `nodmix update`
+
+The fastest way to update. It detects your install type (npm or git), fetches the latest version, runs `nodmix doctor`, and restarts the gateway.
+
+```bash
+nodmix update
+```
+
+To switch channels or target a specific version:
+
+```bash
+nodmix update --channel beta
+nodmix update --channel dev
+nodmix update --tag main
+nodmix update --dry-run   # preview without applying
+```
+
+`nodmix update` does not accept `--verbose`. For update diagnostics, use
+`--dry-run` to preview the planned actions, `--json` for structured results, or
+`nodmix update status --json` to inspect channel and availability state. The
+installer has its own `--verbose` flag, but that flag is not part of
+`nodmix update`.
+
+`--channel beta` prefers beta, but the runtime falls back to stable/latest when
+the beta tag is missing or older than the latest stable release. Use `--tag beta`
+if you want the raw npm beta dist-tag for a one-off package update.
+
+For managed plugins, beta-channel fallback is a warning: the core update can
+still succeed while a plugin uses its recorded default/latest release because no
+plugin beta is available.
+
+See [Development channels](/install/development-channels) for channel semantics.
+
+## Switch between npm and git installs
+
+Use channels when you want to change the install type. The updater keeps your
+state, config, credentials, and workspace in `~/.nodmix`; it only changes
+which Nodmix code install the CLI and gateway use.
+
+```bash
+# npm package install -> editable git checkout
+nodmix update --channel dev
+
+# git checkout -> npm package install
+nodmix update --channel stable
+```
+
+Run with `--dry-run` first to preview the exact install-mode switch:
+
+```bash
+nodmix update --channel dev --dry-run
+nodmix update --channel stable --dry-run
+```
+
+The `dev` channel ensures a git checkout, builds it, and installs the global CLI
+from that checkout. The `stable` and `beta` channels use package installs. If the
+gateway is already installed, `nodmix update` refreshes the service metadata
+and restarts it unless you pass `--no-restart`.
+
+For package installs with a managed Gateway service, `nodmix update` targets
+the package root used by that service. If the shell `nodmix` command comes
+from a different install, the updater prints both roots and the managed service
+Node path. The package update uses the package manager that owns the service
+root and checks the managed service Node against the target release engine
+before replacing the package.
+
+## Alternative: re-run the installer
+
+```bash
+curl -fsSL https://nodmix.ai/install.sh | bash
+```
+
+Add `--no-onboard` to skip onboarding. To force a specific install type through
+the installer, pass `--install-method git --no-onboard` or
+`--install-method npm --no-onboard`.
+
+If `nodmix update` fails after the npm package install phase, re-run the
+installer. The installer does not call the old updater; it runs the global
+package install directly and can recover a partially updated npm install.
+
+```bash
+curl -fsSL https://nodmix.ai/install.sh | bash -s -- --install-method npm
+```
+
+To pin the recovery to a specific version or dist-tag, add `--version`:
+
+```bash
+curl -fsSL https://nodmix.ai/install.sh | bash -s -- --install-method npm --version <version-or-dist-tag>
+```
+
+## Alternative: manual npm, pnpm, or bun
+
+```bash
+npm i -g nodmix@latest
+```
+
+Prefer `nodmix update` for supervised installs because it can coordinate the
+package swap with the running Gateway service. If you update manually on a
+supervised install, stop the managed Gateway before the package manager starts.
+Package managers replace files in place, and a running Gateway can otherwise try
+to load core or plugin files while the package tree is temporarily half-swapped.
+Restart the Gateway after the package manager finishes so the service picks up
+the new install.
+
+For a root-owned Linux system-global install, if `nodmix update` fails with
+`EACCES` and you recover with system npm, keep the Gateway stopped through the
+manual package replacement. Use the same `nodmix` profile flags or environment
+you normally use for that Gateway. Replace `/usr/bin/npm` with the system npm
+that owns the root-owned global prefix on your host:
+
+```bash
+nodmix gateway stop
+sudo /usr/bin/npm i -g nodmix@latest
+nodmix gateway install --force
+nodmix gateway restart
+```
+
+Then verify the service:
+
+```bash
+nodmix --version
+curl -fsS http://127.0.0.1:18789/readyz
+nodmix plugins list --json
+nodmix gateway status --deep --json
+nodmix doctor --lint --json
+```
+
+When `nodmix update` manages a global npm install, it installs the target into
+a temporary npm prefix first, verifies the packaged `dist` inventory, then swaps
+the clean package tree into the real global prefix. That avoids npm overlaying a
+new package onto stale files from the old package. If the install command fails,
+Nodmix retries once with `--omit=optional`. That retry helps hosts where native
+optional dependencies cannot compile, while keeping the original failure visible
+if the fallback also fails.
+
+Nodmix-managed npm update and plugin-update commands also clear npm
+`min-release-age` quarantine for the child npm process. npm may report that
+policy as a derived `before` cutoff; both are useful for general supply-chain
+quarantine policies, but an explicit Nodmix update means "install the selected
+Nodmix release now."
+
+```bash
+pnpm add -g nodmix@latest
+```
+
+```bash
+bun add -g nodmix@latest
+```
+
+### Advanced npm install topics
+
+<AccordionGroup>
+  <Accordion title="Read-only package tree">
+    Nodmix treats packaged global installs as read-only at runtime, even when the global package directory is writable by the current user. Plugin package installs live in Nodmix-owned npm/git roots under the user config directory, and Gateway startup does not mutate the Nodmix package tree.
+
+    Some Linux npm setups install global packages under root-owned directories such as `/usr/lib/node_modules/nodmix`. Nodmix supports that layout because plugin install/update commands write outside that global package directory.
+
+  </Accordion>
+  <Accordion title="Hardened systemd units">
+    Give Nodmix write access to its config/state roots so explicit plugin installs, plugin updates, and doctor cleanup can persist their changes:
+
+    ```ini
+    ReadWritePaths=/var/lib/nodmix /home/nodmix/.nodmix /tmp
+    ```
+
+  </Accordion>
+  <Accordion title="Disk-space preflight">
+    Before package updates and explicit plugin installs, Nodmix tries a best-effort disk-space check for the target volume. Low space produces a warning with the checked path, but does not block the update because filesystem quotas, snapshots, and network volumes can change after the check. The actual package-manager install and post-install verification remain authoritative.
+  </Accordion>
+</AccordionGroup>
+
+## Auto-updater
+
+The auto-updater is off by default. Enable it in `~/.nodmix/nodmix.json`:
+
+```json5
+{
+  update: {
+    channel: "stable",
+    auto: {
+      enabled: true,
+      stableDelayHours: 6,
+      stableJitterHours: 12,
+      betaCheckIntervalHours: 1,
+    },
+  },
+}
+```
+
+| Channel  | Behavior                                                                                                      |
+| -------- | ------------------------------------------------------------------------------------------------------------- |
+| `stable` | Waits `stableDelayHours`, then applies with deterministic jitter across `stableJitterHours` (spread rollout). |
+| `beta`   | Checks every `betaCheckIntervalHours` (default: hourly) and applies immediately.                              |
+| `dev`    | No automatic apply. Use `nodmix update` manually.                                                           |
+
+The gateway also logs an update hint on startup (disable with `update.checkOnStart: false`).
+For downgrade or incident recovery, set `NODMIX_NO_AUTO_UPDATE=1` in the gateway environment to block automatic applies even when `update.auto.enabled` is configured. Startup update hints can still run unless `update.checkOnStart` is also disabled.
+
+Package-manager updates requested through the live Gateway control-plane handler
+do not replace the package tree inside the running Gateway process. On managed
+service installs, the Gateway starts a detached handoff, exits, and lets the
+normal `nodmix update --yes --json` CLI path stop the service, replace the
+package, refresh service metadata, restart, verify the Gateway version and
+reachability, and recover an installed-but-unloaded macOS LaunchAgent when
+possible. If the Gateway cannot make that handoff safely, `update.run` reports a
+safe shell command instead of running the package manager in-process.
+
+## After updating
+
+<Steps>
+
+### Run doctor
+
+```bash
+nodmix doctor
+```
+
+Migrates config, audits DM policies, and checks gateway health. Details: [Doctor](/gateway/doctor)
+
+### Restart the gateway
+
+```bash
+nodmix gateway restart
+```
+
+### Verify
+
+```bash
+nodmix health
+```
+
+</Steps>
+
+## Rollback
+
+### Pin a version (npm)
+
+```bash
+npm i -g nodmix@<version>
+nodmix doctor
+nodmix gateway restart
+```
+
+<Tip>
+`npm view nodmix version` shows the current published version.
+</Tip>
+
+### Pin a commit (source)
+
+```bash
+git fetch origin
+git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
+pnpm install && pnpm build
+nodmix gateway restart
+```
+
+To return to latest: `git checkout main && git pull`.
+
+## If you are stuck
+
+- Run `nodmix doctor` again and read the output carefully.
+- For `nodmix update --channel dev` on source checkouts, the updater auto-bootstraps `pnpm` when needed. If you see a pnpm/corepack bootstrap error, install `pnpm` manually (or re-enable `corepack`) and rerun the update.
+- Check: [Troubleshooting](/gateway/troubleshooting)
+- Ask in Discord: [https://discord.gg/clawd](https://discord.gg/clawd)
+
+## Related
+
+- [Install overview](/install): all installation methods.
+- [Doctor](/gateway/doctor): health checks after updates.
+- [Migrating](/install/migrating): major version migration guides.