nodmix 2026.5.25

package/docs/cli/flows.md

@@ -0,0 +1,52 @@
+---
+summary: "Redirect: flow commands live under `nodmix tasks flow`"
+read_when:
+  - You encounter `nodmix flows` in older docs or release notes
+  - You want a quick TaskFlow inspection reference
+title: "Flows (redirect)"
+---
+
+# `nodmix tasks flow`
+
+There is no top-level `nodmix flows` command. Durable TaskFlow inspection lives under `nodmix tasks flow`.
+
+## Subcommands
+
+```bash
+nodmix tasks flow list   [--json] [--status <name>]
+nodmix tasks flow show   <lookup> [--json]
+nodmix tasks flow cancel <lookup>
+```
+
+| Subcommand | Description                | Arguments / options                                                                   |
+| ---------- | -------------------------- | ------------------------------------------------------------------------------------- |
+| `list`     | List tracked TaskFlows.    | `--json` machine-readable output; `--status <name>` filter (see status values below). |
+| `show`     | Show one TaskFlow.         | `<lookup>` flow id or owner key; `--json` machine-readable output.                    |
+| `cancel`   | Cancel a running TaskFlow. | `<lookup>` flow id or owner key.                                                      |
+
+`<lookup>` accepts either a flow id (returned by `list` / `show`) or the flow's owner key (the stable identifier the owning subsystem uses to track the flow).
+
+### Status filter values
+
+`--status` on `list` accepts one of:
+
+`queued`, `running`, `waiting`, `blocked`, `succeeded`, `failed`, `cancelled`, `lost`
+
+## Examples
+
+```bash
+nodmix tasks flow list
+nodmix tasks flow list --status running
+nodmix tasks flow list --json
+nodmix tasks flow show flow_abc123
+nodmix tasks flow show flow_abc123 --json
+nodmix tasks flow cancel flow_abc123
+```
+
+For full TaskFlow concepts and authoring see [TaskFlow](/automation/taskflow). For the parent `tasks` command see [tasks CLI reference](/cli/tasks).
+
+## Related
+
+- [CLI reference](/cli)
+- [Automation](/automation)
+- [TaskFlow](/automation/taskflow)

package/docs/cli/gateway.md

@@ -0,0 +1,567 @@
+---
+summary: "Nodmix Gateway CLI (`nodmix gateway`) — run, query, and discover gateways"
+read_when:
+  - Running the Gateway from the CLI (dev or servers)
+  - Debugging Gateway auth, bind modes, and connectivity
+  - Discovering gateways via Bonjour (local + wide-area DNS-SD)
+title: "Gateway"
+sidebarTitle: "Gateway"
+---
+
+The Gateway is Nodmix's WebSocket server (channels, nodes, sessions, hooks). Subcommands in this page live under `nodmix gateway …`.
+
+<CardGroup cols={3}>
+  <Card title="Bonjour discovery" href="/gateway/bonjour">
+    Local mDNS + wide-area DNS-SD setup.
+  </Card>
+  <Card title="Discovery overview" href="/gateway/discovery">
+    How Nodmix advertises and finds gateways.
+  </Card>
+  <Card title="Configuration" href="/gateway/configuration">
+    Top-level gateway config keys.
+  </Card>
+</CardGroup>
+
+## Run the Gateway
+
+Run a local Gateway process:
+
+```bash
+nodmix gateway
+```
+
+Foreground alias:
+
+```bash
+nodmix gateway run
+```
+
+<AccordionGroup>
+  <Accordion title="Startup behavior">
+    - By default, the Gateway refuses to start unless `gateway.mode=local` is set in `~/.nodmix/nodmix.json`. Use `--allow-unconfigured` for ad-hoc/dev runs.
+    - `nodmix onboard --mode local` and `nodmix setup` are expected to write `gateway.mode=local`. If the file exists but `gateway.mode` is missing, treat that as a broken or clobbered config and repair it instead of assuming local mode implicitly.
+    - If the file exists and `gateway.mode` is missing, the Gateway treats that as suspicious config damage and refuses to "guess local" for you.
+    - Binding beyond loopback without auth is blocked (safety guardrail).
+    - `SIGUSR1` triggers an in-process restart when authorized (`commands.restart` is enabled by default; set `commands.restart: false` to block manual restart, while gateway tool/config apply/update remain allowed).
+    - `SIGINT`/`SIGTERM` handlers stop the gateway process, but they don't restore any custom terminal state. If you wrap the CLI with a TUI or raw-mode input, restore the terminal before exit.
+
+  </Accordion>
+</AccordionGroup>
+
+### Options
+
+<ParamField path="--port <port>" type="number">
+  WebSocket port (default comes from config/env; usually `18789`).
+</ParamField>
+<ParamField path="--bind <loopback|lan|tailnet|auto|custom>" type="string">
+  Listener bind mode.
+</ParamField>
+<ParamField path="--auth <token|password>" type="string">
+  Auth mode override.
+</ParamField>
+<ParamField path="--token <token>" type="string">
+  Token override (also sets `NODMIX_GATEWAY_TOKEN` for the process).
+</ParamField>
+<ParamField path="--password <password>" type="string">
+  Password override.
+</ParamField>
+<ParamField path="--password-file <path>" type="string">
+  Read the gateway password from a file.
+</ParamField>
+<ParamField path="--tailscale <off|serve|funnel>" type="string">
+  Expose the Gateway via Tailscale.
+</ParamField>
+<ParamField path="--tailscale-reset-on-exit" type="boolean">
+  Reset Tailscale serve/funnel config on shutdown.
+</ParamField>
+<ParamField path="--allow-unconfigured" type="boolean">
+  Allow gateway start without `gateway.mode=local` in config. Bypasses the startup guard for ad-hoc/dev bootstrap only; does not write or repair the config file.
+</ParamField>
+<ParamField path="--dev" type="boolean">
+  Create a dev config + workspace if missing (skips BOOTSTRAP.md).
+</ParamField>
+<ParamField path="--reset" type="boolean">
+  Reset dev config + credentials + sessions + workspace (requires `--dev`).
+</ParamField>
+<ParamField path="--force" type="boolean">
+  Kill any existing listener on the selected port before starting.
+</ParamField>
+<ParamField path="--verbose" type="boolean">
+  Verbose logs.
+</ParamField>
+<ParamField path="--cli-backend-logs" type="boolean">
+  Only show CLI backend logs in the console (and enable stdout/stderr).
+</ParamField>
+<ParamField path="--ws-log <auto|full|compact>" type="string" default="auto">
+  Websocket log style.
+</ParamField>
+<ParamField path="--compact" type="boolean">
+  Alias for `--ws-log compact`.
+</ParamField>
+<ParamField path="--raw-stream" type="boolean">
+  Log raw model stream events to jsonl.
+</ParamField>
+<ParamField path="--raw-stream-path <path>" type="string">
+  Raw stream jsonl path.
+</ParamField>
+
+## Restart the Gateway
+
+```bash
+nodmix gateway restart
+nodmix gateway restart --safe
+nodmix gateway restart --safe --skip-deferral
+nodmix gateway restart --force
+```
+
+`nodmix gateway restart --safe` asks the running Gateway to preflight active Nodmix work before restarting. If queued operations, reply delivery, embedded runs, or task runs are active, the Gateway reports the blockers, coalesces duplicate safe restart requests, and restarts once the active work drains. Plain `restart` keeps the existing service-manager behavior for compatibility. Use `--force` only when you explicitly want the immediate override path.
+
+`nodmix gateway restart --safe --skip-deferral` runs the same Nodmix-aware coordinated restart as `--safe`, but bypasses the active-work deferral gate so the Gateway emits the restart immediately even when blockers are reported. Use it as the operator escape hatch when a deferral has been pinned by a stuck task run and `--safe` alone would wait indefinitely. `--skip-deferral` requires `--safe`.
+
+<Warning>
+Inline `--password` can be exposed in local process listings. Prefer `--password-file`, env, or a SecretRef-backed `gateway.auth.password`.
+</Warning>
+
+### Gateway profiling
+
+- Set `NODMIX_GATEWAY_STARTUP_TRACE=1` to log phase timings during Gateway startup, including per-phase `eventLoopMax` delay and plugin lookup-table timings for installed-index, manifest registry, startup planning, and owner-map work.
+- Set `NODMIX_GATEWAY_RESTART_TRACE=1` to log restart-scoped `restart trace:` lines for restart signal handling, active-work drain, shutdown phases, next start, ready timing, and memory metrics.
+- Set `NODMIX_DIAGNOSTICS=timeline` with `NODMIX_DIAGNOSTICS_TIMELINE_PATH=<path>` to write a best-effort JSONL startup diagnostics timeline for external QA harnesses. You can also enable the flag with `diagnostics.flags: ["timeline"]` in config; the path is still env-provided. Add `NODMIX_DIAGNOSTICS_EVENT_LOOP=1` to include event-loop samples.
+- Run `pnpm build` first, then `pnpm test:startup:gateway -- --runs 5 --warmup 1` to benchmark Gateway startup against the built CLI entry. The benchmark records first process output, `/healthz`, `/readyz`, startup trace timings, event-loop delay, and plugin lookup-table timing details.
+- Run `pnpm build` first, then `pnpm test:restart:gateway -- --case skipChannels --runs 1 --restarts 5` to benchmark in-process Gateway restart against the built CLI entry on macOS or Linux. The restart benchmark uses SIGUSR1, enables both startup and restart traces in the child process, and records next `/healthz`, next `/readyz`, downtime, ready timing, CPU, RSS, and restart trace metrics.
+- Treat `/healthz` as liveness and `/readyz` as usable readiness. Trace lines and benchmark output are for owner attribution; do not treat one trace span or one sample as a complete performance conclusion.
+
+## Query a running Gateway
+
+All query commands use WebSocket RPC.
+
+<Tabs>
+  <Tab title="Output modes">
+    - Default: human-readable (colored in TTY).
+    - `--json`: machine-readable JSON (no styling/spinner).
+    - `--no-color` (or `NO_COLOR=1`): disable ANSI while keeping human layout.
+
+  </Tab>
+  <Tab title="Shared options">
+    - `--url <url>`: Gateway WebSocket URL.
+    - `--token <token>`: Gateway token.
+    - `--password <password>`: Gateway password.
+    - `--timeout <ms>`: timeout/budget (varies per command).
+    - `--expect-final`: wait for a "final" response (agent calls).
+
+  </Tab>
+</Tabs>
+
+<Note>
+When you set `--url`, the CLI does not fall back to config or environment credentials. Pass `--token` or `--password` explicitly. Missing explicit credentials is an error.
+</Note>
+
+### `gateway health`
+
+```bash
+nodmix gateway health --url ws://127.0.0.1:18789
+```
+
+The HTTP `/healthz` endpoint is a liveness probe: it returns once the server can answer HTTP. The HTTP `/readyz` endpoint is stricter and stays red while startup plugin sidecars, channels, or configured hooks are still settling. Local or authenticated detailed readiness responses include an `eventLoop` diagnostic block with event-loop delay, event-loop utilization, CPU core ratio, and a `degraded` flag.
+
+### `gateway usage-cost`
+
+Fetch usage-cost summaries from session logs.
+
+```bash
+nodmix gateway usage-cost
+nodmix gateway usage-cost --days 7
+nodmix gateway usage-cost --json
+```
+
+<ParamField path="--days <days>" type="number" default="30">
+  Number of days to include.
+</ParamField>
+
+### `gateway stability`
+
+Fetch the recent diagnostic stability recorder from a running Gateway.
+
+```bash
+nodmix gateway stability
+nodmix gateway stability --type payload.large
+nodmix gateway stability --bundle latest
+nodmix gateway stability --bundle latest --export
+nodmix gateway stability --json
+```
+
+<ParamField path="--limit <limit>" type="number" default="25">
+  Maximum number of recent events to include (max `1000`).
+</ParamField>
+<ParamField path="--type <type>" type="string">
+  Filter by diagnostic event type, such as `payload.large` or `diagnostic.memory.pressure`.
+</ParamField>
+<ParamField path="--since-seq <seq>" type="number">
+  Include only events after a diagnostic sequence number.
+</ParamField>
+<ParamField path="--bundle [path]" type="string">
+  Read a persisted stability bundle instead of calling the running Gateway. Use `--bundle latest` (or just `--bundle`) for the newest bundle under the state directory, or pass a bundle JSON path directly.
+</ParamField>
+<ParamField path="--export" type="boolean">
+  Write a shareable support diagnostics zip instead of printing stability details.
+</ParamField>
+<ParamField path="--output <path>" type="string">
+  Output path for `--export`.
+</ParamField>
+
+<AccordionGroup>
+  <Accordion title="Privacy and bundle behavior">
+    - Records keep operational metadata: event names, counts, byte sizes, memory readings, queue/session state, channel/plugin names, and redacted session summaries. They do not keep chat text, webhook bodies, tool outputs, raw request or response bodies, tokens, cookies, secret values, hostnames, or raw session ids. Set `diagnostics.enabled: false` to disable the recorder entirely.
+    - On fatal Gateway exits, shutdown timeouts, and restart startup failures, Nodmix writes the same diagnostic snapshot to `~/.nodmix/logs/stability/nodmix-stability-*.json` when the recorder has events. Inspect the newest bundle with `nodmix gateway stability --bundle latest`; `--limit`, `--type`, and `--since-seq` also apply to bundle output.
+
+  </Accordion>
+</AccordionGroup>
+
+### `gateway diagnostics export`
+
+Write a local diagnostics zip that is designed to attach to bug reports. For the privacy model and bundle contents, see [Diagnostics Export](/gateway/diagnostics).
+
+```bash
+nodmix gateway diagnostics export
+nodmix gateway diagnostics export --output nodmix-diagnostics.zip
+nodmix gateway diagnostics export --json
+```
+
+<ParamField path="--output <path>" type="string">
+  Output zip path. Defaults to a support export under the state directory.
+</ParamField>
+<ParamField path="--log-lines <count>" type="number" default="5000">
+  Maximum sanitized log lines to include.
+</ParamField>
+<ParamField path="--log-bytes <bytes>" type="number" default="1000000">
+  Maximum log bytes to inspect.
+</ParamField>
+<ParamField path="--url <url>" type="string">
+  Gateway WebSocket URL for the health snapshot.
+</ParamField>
+<ParamField path="--token <token>" type="string">
+  Gateway token for the health snapshot.
+</ParamField>
+<ParamField path="--password <password>" type="string">
+  Gateway password for the health snapshot.
+</ParamField>
+<ParamField path="--timeout <ms>" type="number" default="3000">
+  Status/health snapshot timeout.
+</ParamField>
+<ParamField path="--no-stability-bundle" type="boolean">
+  Skip persisted stability bundle lookup.
+</ParamField>
+<ParamField path="--json" type="boolean">
+  Print the written path, size, and manifest as JSON.
+</ParamField>
+
+The export contains a manifest, a Markdown summary, config shape, sanitized config details, sanitized log summaries, sanitized Gateway status/health snapshots, and the newest stability bundle when one exists.
+
+It is meant to be shared. It keeps operational details that help debugging, such as safe Nodmix log fields, subsystem names, status codes, durations, configured modes, ports, plugin ids, provider ids, non-secret feature settings, and redacted operational log messages. It omits or redacts chat text, webhook bodies, tool outputs, credentials, cookies, account/message identifiers, prompt/instruction text, hostnames, and secret values. When a LogTape-style message looks like user/chat/tool payload text, the export keeps only that a message was omitted plus its byte count.
+
+### `gateway status`
+
+`gateway status` shows the Gateway service (launchd/systemd/schtasks) plus an optional probe of connectivity/auth capability.
+
+```bash
+nodmix gateway status
+nodmix gateway status --json
+nodmix gateway status --require-rpc
+```
+
+<ParamField path="--url <url>" type="string">
+  Add an explicit probe target. Configured remote + localhost are still probed.
+</ParamField>
+<ParamField path="--token <token>" type="string">
+  Token auth for the probe.
+</ParamField>
+<ParamField path="--password <password>" type="string">
+  Password auth for the probe.
+</ParamField>
+<ParamField path="--timeout <ms>" type="number" default="10000">
+  Probe timeout.
+</ParamField>
+<ParamField path="--no-probe" type="boolean">
+  Skip the connectivity probe (service-only view).
+</ParamField>
+<ParamField path="--deep" type="boolean">
+  Scan system-level services too.
+</ParamField>
+<ParamField path="--require-rpc" type="boolean">
+  Upgrade the default connectivity probe to a read probe and exit non-zero when that read probe fails. Cannot be combined with `--no-probe`.
+</ParamField>
+
+<AccordionGroup>
+  <Accordion title="Status semantics">
+    - `gateway status` stays available for diagnostics even when the local CLI config is missing or invalid.
+    - Default `gateway status` proves service state, WebSocket connect, and the auth capability visible at handshake time. It does not prove read/write/admin operations.
+    - Diagnostic probes are non-mutating for first-time device auth: they reuse an existing cached device token when one exists, but they do not create a new CLI device identity or read-only device pairing record just to check status.
+    - `gateway status` resolves configured auth SecretRefs for probe auth when possible.
+    - If a required auth SecretRef is unresolved in this command path, `gateway status --json` reports `rpc.authWarning` when probe connectivity/auth fails; pass `--token`/`--password` explicitly or resolve the secret source first.
+    - If the probe succeeds, unresolved auth-ref warnings are suppressed to avoid false positives.
+    - When probing is enabled, JSON output includes `gateway.version` when the running Gateway reports it; `--require-rpc` can fall back to the `status.runtimeVersion` RPC payload if the follow-up handshake probe cannot provide version metadata.
+    - Use `--require-rpc` in scripts and automation when a listening service is not enough and you need read-scope RPC calls to be healthy too.
+    - `--deep` adds a best-effort scan for extra launchd/systemd/schtasks installs. When multiple gateway-like services are detected, human output prints cleanup hints and warns that most setups should run one gateway per machine.
+    - `--deep` also reports a recent Gateway supervisor restart handoff when the service process exited cleanly for an external supervisor restart.
+    - `--deep` runs config validation in plugin-aware mode (`pluginValidation: "full"`) and surfaces configured plugin manifest warnings (for example missing channel config metadata) so install and update smoke checks catch them. Default `gateway status` keeps the fast read-only path that skips plugin validation.
+    - Human output includes the resolved file log path plus the CLI-vs-service config paths/validity snapshot to help diagnose profile or state-dir drift.
+
+  </Accordion>
+  <Accordion title="Linux systemd auth-drift checks">
+    - On Linux systemd installs, service auth drift checks read both `Environment=` and `EnvironmentFile=` values from the unit (including `%h`, quoted paths, multiple files, and optional `-` files).
+    - Drift checks resolve `gateway.auth.token` SecretRefs using merged runtime env (service command env first, then process env fallback).
+    - If token auth is not effectively active (explicit `gateway.auth.mode` of `password`/`none`/`trusted-proxy`, or mode unset where password can win and no token candidate can win), token-drift checks skip config token resolution.
+
+  </Accordion>
+</AccordionGroup>
+
+### `gateway probe`
+
+`gateway probe` is the "debug everything" command. It always probes:
+
+- your configured remote gateway (if set), and
+- localhost (loopback) **even if remote is configured**.
+
+If you pass `--url`, that explicit target is added ahead of both. Human output labels the targets as:
+
+- `URL (explicit)`
+- `Remote (configured)` or `Remote (configured, inactive)`
+- `Local loopback`
+
+<Note>
+If multiple gateways are reachable, it prints all of them. Multiple gateways are supported when you use isolated profiles/ports (e.g., a rescue bot), but most installs still run a single gateway.
+</Note>
+
+```bash
+nodmix gateway probe
+nodmix gateway probe --json
+```
+
+<AccordionGroup>
+  <Accordion title="Interpretation">
+    - `Reachable: yes` means at least one target accepted a WebSocket connect.
+    - `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` reports what the probe could prove about auth. It is separate from reachability.
+    - `Read probe: ok` means read-scope detail RPC calls (`health`/`status`/`system-presence`/`config.get`) also succeeded.
+    - `Read probe: limited - missing scope: operator.read` means connect succeeded but read-scope RPC is limited. This is reported as **degraded** reachability, not full failure.
+    - `Read probe: failed` after `Connect: ok` means the Gateway accepted the WebSocket connection, but follow-up read diagnostics timed out or failed. This is also **degraded** reachability, not an unreachable Gateway.
+    - Like `gateway status`, probe reuses existing cached device auth but does not create first-time device identity or pairing state.
+    - Exit code is non-zero only when no probed target is reachable.
+
+  </Accordion>
+  <Accordion title="JSON output">
+    Top level:
+
+    - `ok`: at least one target is reachable.
+    - `degraded`: at least one target accepted a connection but did not complete full detail RPC diagnostics.
+    - `capability`: best capability seen across reachable targets (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope`, or `unknown`).
+    - `primaryTargetId`: best target to treat as the active winner in this order: explicit URL, SSH tunnel, configured remote, then local loopback.
+    - `warnings[]`: best-effort warning records with `code`, `message`, and optional `targetIds`.
+    - `network`: local loopback/tailnet URL hints derived from current config and host networking.
+    - `discovery.timeoutMs` and `discovery.count`: the actual discovery budget/result count used for this probe pass.
+
+    Per target (`targets[].connect`):
+
+    - `ok`: reachability after connect + degraded classification.
+    - `rpcOk`: full detail RPC success.
+    - `scopeLimited`: detail RPC failed due to missing operator scope.
+
+    Per target (`targets[].auth`):
+
+    - `role`: auth role reported in `hello-ok` when available.
+    - `scopes`: granted scopes reported in `hello-ok` when available.
+    - `capability`: the surfaced auth capability classification for that target.
+
+  </Accordion>
+  <Accordion title="Common warning codes">
+    - `ssh_tunnel_failed`: SSH tunnel setup failed; the command fell back to direct probes.
+    - `multiple_gateways`: more than one target was reachable; this is unusual unless you intentionally run isolated profiles, such as a rescue bot.
+    - `auth_secretref_unresolved`: a configured auth SecretRef could not be resolved for a failed target.
+    - `probe_scope_limited`: WebSocket connect succeeded, but the read probe was limited by missing `operator.read`.
+
+  </Accordion>
+</AccordionGroup>
+
+#### Remote over SSH (Mac app parity)
+
+The macOS app "Remote over SSH" mode uses a local port-forward so the remote gateway (which may be bound to loopback only) becomes reachable at `ws://127.0.0.1:<port>`.
+
+CLI equivalent:
+
+```bash
+nodmix gateway probe --ssh user@gateway-host
+```
+
+<ParamField path="--ssh <target>" type="string">
+  `user@host` or `user@host:port` (port defaults to `22`).
+</ParamField>
+<ParamField path="--ssh-identity <path>" type="string">
+  Identity file.
+</ParamField>
+<ParamField path="--ssh-auto" type="boolean">
+  Pick the first discovered gateway host as SSH target from the resolved discovery endpoint (`local.` plus the configured wide-area domain, if any). TXT-only hints are ignored.
+</ParamField>
+
+Config (optional, used as defaults):
+
+- `gateway.remote.sshTarget`
+- `gateway.remote.sshIdentity`
+
+### `gateway call <method>`
+
+Low-level RPC helper.
+
+```bash
+nodmix gateway call status
+nodmix gateway call logs.tail --params '{"sinceMs": 60000}'
+```
+
+<ParamField path="--params <json>" type="string" default="{}">
+  JSON object string for params.
+</ParamField>
+<ParamField path="--url <url>" type="string">
+  Gateway WebSocket URL.
+</ParamField>
+<ParamField path="--token <token>" type="string">
+  Gateway token.
+</ParamField>
+<ParamField path="--password <password>" type="string">
+  Gateway password.
+</ParamField>
+<ParamField path="--timeout <ms>" type="number">
+  Timeout budget.
+</ParamField>
+<ParamField path="--expect-final" type="boolean">
+  Mainly for agent-style RPCs that stream intermediate events before a final payload.
+</ParamField>
+<ParamField path="--json" type="boolean">
+  Machine-readable JSON output.
+</ParamField>
+
+<Note>
+`--params` must be valid JSON.
+</Note>
+
+## Manage the Gateway service
+
+```bash
+nodmix gateway install
+nodmix gateway start
+nodmix gateway stop
+nodmix gateway restart
+nodmix gateway uninstall
+```
+
+### Install with a wrapper
+
+Use `--wrapper` when the managed service must start through another executable, for example a
+secrets manager shim or a run-as helper. The wrapper receives the normal Gateway args and is
+responsible for eventually exec'ing `nodmix` or Node with those args.
+
+```bash
+cat > ~/.local/bin/nodmix-doppler <<'EOF'
+#!/usr/bin/env bash
+set -euo pipefail
+exec doppler run --project my-project --config production -- nodmix "$@"
+EOF
+chmod +x ~/.local/bin/nodmix-doppler
+
+nodmix gateway install --wrapper ~/.local/bin/nodmix-doppler --force
+nodmix gateway restart
+```
+
+You can also set the wrapper through the environment. `gateway install` validates that the path is
+an executable file, writes the wrapper into service `ProgramArguments`, and persists
+`NODMIX_WRAPPER` in the service environment for later forced reinstalls, updates, and doctor
+repairs.
+
+```bash
+NODMIX_WRAPPER="$HOME/.local/bin/nodmix-doppler" nodmix gateway install --force
+nodmix doctor
+```
+
+To remove a persisted wrapper, clear `NODMIX_WRAPPER` while reinstalling:
+
+```bash
+NODMIX_WRAPPER= nodmix gateway install --force
+nodmix gateway restart
+```
+
+<AccordionGroup>
+  <Accordion title="Command options">
+    - `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
+    - `gateway install`: `--port`, `--runtime <node|bun>`, `--token`, `--wrapper <path>`, `--force`, `--json`
+    - `gateway restart`: `--safe`, `--skip-deferral`, `--force`, `--wait <duration>`, `--json`
+    - `gateway uninstall|start`: `--json`
+    - `gateway stop`: `--disable`, `--json`
+
+  </Accordion>
+  <Accordion title="Lifecycle behavior">
+    - Use `gateway restart` to restart a managed service. Do not chain `gateway stop` and `gateway start` as a restart substitute.
+    - On macOS, `gateway stop` uses `launchctl bootout` by default, which removes the LaunchAgent from the current boot session without persisting a disable — KeepAlive auto-recovery remains active for future crashes and `gateway start` re-enables cleanly without a manual `launchctl enable`. Pass `--disable` to persistently suppress KeepAlive and RunAtLoad so the gateway does not respawn until the next explicit `gateway start`; use this when a manual stop should survive reboots or system restarts.
+    - `gateway restart --safe` asks the running Gateway to preflight active Nodmix work and defer the restart until reply delivery, embedded runs, and task runs drain. `--safe` cannot be combined with `--force` or `--wait`.
+    - `gateway restart --wait 30s` overrides the configured restart drain budget for that restart. Bare numbers are milliseconds; units such as `s`, `m`, and `h` are accepted. `--wait 0` waits indefinitely.
+    - `gateway restart --safe --skip-deferral` runs the Nodmix-aware safe restart but bypasses the deferral gate so the Gateway emits the restart immediately even when blockers are reported. Operator escape hatch for stuck-task-run deferrals; requires `--safe`.
+    - `gateway restart --force` skips the active-work drain and restarts immediately. Use it when an operator has already inspected the listed task blockers and wants the gateway back now.
+    - Lifecycle commands accept `--json` for scripting.
+
+  </Accordion>
+  <Accordion title="Auth and SecretRefs at install time">
+    - When token auth requires a token and `gateway.auth.token` is SecretRef-managed, `gateway install` validates that the SecretRef is resolvable but does not persist the resolved token into service environment metadata.
+    - If token auth requires a token and the configured token SecretRef is unresolved, install fails closed instead of persisting fallback plaintext.
+    - For password auth on `gateway run`, prefer `NODMIX_GATEWAY_PASSWORD`, `--password-file`, or a SecretRef-backed `gateway.auth.password` over inline `--password`.
+    - In inferred auth mode, shell-only `NODMIX_GATEWAY_PASSWORD` does not relax install token requirements; use durable config (`gateway.auth.password` or config `env`) when installing a managed service.
+    - If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, install is blocked until mode is set explicitly.
+
+  </Accordion>
+</AccordionGroup>
+
+## Discover gateways (Bonjour)
+
+`gateway discover` scans for Gateway beacons (`_nodmix-gw._tcp`).
+
+- Multicast DNS-SD: `local.`
+- Unicast DNS-SD (Wide-Area Bonjour): choose a domain (example: `nodmix.internal.`) and set up split DNS + a DNS server; see [Bonjour](/gateway/bonjour).
+
+Only gateways with Bonjour discovery enabled (default) advertise the beacon.
+
+Wide-area discovery records can include these TXT hints:
+
+- `role` (gateway role hint)
+- `transport` (transport hint, e.g. `gateway`)
+- `gatewayPort` (WebSocket port, usually `18789`)
+- `sshPort` (full discovery mode only; clients default SSH targets to `22` when it is absent)
+- `tailnetDns` (MagicDNS hostname, when available)
+- `gatewayTls` / `gatewayTlsSha256` (TLS enabled + cert fingerprint)
+- `cliPath` (full discovery mode only)
+
+### `gateway discover`
+
+```bash
+nodmix gateway discover
+```
+
+<ParamField path="--timeout <ms>" type="number" default="2000">
+  Per-command timeout (browse/resolve).
+</ParamField>
+<ParamField path="--json" type="boolean">
+  Machine-readable output (also disables styling/spinner).
+</ParamField>
+
+Examples:
+
+```bash
+nodmix gateway discover --timeout 4000
+nodmix gateway discover --json | jq '.beacons[].wsUrl'
+```
+
+<Note>
+- The CLI scans `local.` plus the configured wide-area domain when one is enabled.
+- `wsUrl` in JSON output is derived from the resolved service endpoint, not from TXT-only hints such as `lanHost` or `tailnetDns`.
+- On `local.` mDNS and wide-area DNS-SD, `sshPort` and `cliPath` are only published when `discovery.mdns.mode` is `full`.
+
+</Note>
+
+## Related
+
+- [CLI reference](/cli)
+- [Gateway runbook](/gateway)

package/docs/cli/health.md

@@ -0,0 +1,43 @@
+---
+summary: "CLI reference for `nodmix health` (gateway health snapshot via RPC)"
+read_when:
+  - You want to quickly check the running Gateway's health
+title: "Health"
+---
+
+# `nodmix health`
+
+Fetch health from the running Gateway.
+
+## Options
+
+| Flag             | Default | Description                                                        |
+| ---------------- | ------- | ------------------------------------------------------------------ |
+| `--json`         | `false` | Print machine-readable JSON instead of text.                       |
+| `--timeout <ms>` | `10000` | Connection timeout in milliseconds.                                |
+| `--verbose`      | `false` | Verbose logging. Forces a live probe and expands per-agent output. |
+| `--debug`        | `false` | Alias for `--verbose`.                                             |
+
+Examples:
+
+```bash
+nodmix health
+nodmix health --json
+nodmix health --timeout 2500
+nodmix health --verbose
+nodmix health --debug
+```
+
+Notes:
+
+- Default `nodmix health` asks the running gateway for its health snapshot. When the
+  gateway already has a fresh cached snapshot, it can return that cached payload and
+  refresh in the background.
+- `--verbose` forces a live probe, prints gateway connection details, and expands the
+  human-readable output across all configured accounts and agents.
+- Output includes per-agent session stores when multiple agents are configured.
+
+## Related
+
+- [CLI reference](/cli)
+- [Gateway health](/gateway/health)