nodmix 2026.5.25

package/docs/cli/crestodian.md

@@ -0,0 +1,332 @@
+---
+summary: "CLI reference and security model for Crestodian, the configless-safe setup and repair helper"
+read_when:
+  - You run nodmix with no command and want to understand Crestodian
+  - You need a configless-safe way to inspect or repair Nodmix
+  - You are designing or enabling message-channel rescue mode
+title: "Crestodian"
+---
+
+# `nodmix crestodian`
+
+Crestodian is Nodmix's local setup, repair, and configuration helper. It is
+designed to stay reachable when the normal agent path is broken.
+
+Running `nodmix` with no command starts Crestodian in an interactive terminal.
+Running `nodmix crestodian` starts the same helper explicitly.
+
+## What Crestodian shows
+
+On startup, interactive Crestodian opens the same TUI shell used by
+`nodmix tui`, with a Crestodian chat backend. The chat log starts with a short
+greeting:
+
+- when to start Crestodian
+- the model or deterministic planner path Crestodian is actually using
+- config validity and the default agent
+- Gateway reachability from the first startup probe
+- the next debug action Crestodian can take
+
+It does not dump secrets or load plugin CLI commands just to start. The TUI
+still provides the normal header, chat log, status line, footer, autocomplete,
+and editor controls.
+
+Use `status` for the detailed inventory with config path, docs/source paths,
+local CLI probes, API-key presence, agents, model, and Gateway details.
+
+Crestodian uses the same Nodmix reference discovery as regular agents. In a Git checkout,
+it points itself at local `docs/` and the local source tree. In an npm package install, it
+uses the bundled package docs and links to
+[https://github.com/nodmix/nodmix](https://github.com/nodmix/nodmix), with explicit
+guidance to review source whenever the docs are not enough.
+
+## Examples
+
+```bash
+nodmix
+nodmix crestodian
+nodmix crestodian --json
+nodmix crestodian --message "models"
+nodmix crestodian --message "validate config"
+nodmix crestodian --message "setup workspace ~/Projects/work model openai/gpt-5.5" --yes
+nodmix crestodian --message "set default model openai/gpt-5.5" --yes
+nodmix onboard --modern
+```
+
+Inside the Crestodian TUI:
+
+```text
+status
+health
+doctor
+doctor fix
+validate config
+setup
+setup workspace ~/Projects/work model openai/gpt-5.5
+config set gateway.port 19001
+config set-ref gateway.auth.token env NODMIX_GATEWAY_TOKEN
+gateway status
+restart gateway
+agents
+create agent work workspace ~/Projects/work
+models
+set default model openai/gpt-5.5
+plugins list
+plugins search slack
+plugin install clawhub:nodmix-codex-app-server
+plugin uninstall nodmix-codex-app-server
+talk to work agent
+talk to agent for ~/Projects/work
+audit
+quit
+```
+
+## Safe startup
+
+Crestodian's startup path is deliberately small. It can run when:
+
+- `nodmix.json` is missing
+- `nodmix.json` is invalid
+- the Gateway is down
+- plugin command registration is unavailable
+- no agent has been configured yet
+
+`nodmix --help` and `nodmix --version` still use the normal fast paths.
+Noninteractive `nodmix` exits with a short message instead of printing root
+help, because the no-command product is Crestodian.
+
+## Operations and approval
+
+Crestodian uses typed operations instead of editing config ad hoc.
+
+Read-only operations can run immediately:
+
+- show overview
+- list agents
+- list installed plugins
+- search ClawHub plugins
+- show model/backend status
+- run status or health checks
+- check Gateway reachability
+- run doctor without interactive fixes
+- validate config
+- show the audit-log path
+
+Persistent operations require conversational approval in interactive mode unless
+you pass `--yes` for a direct command:
+
+- write config
+- run `config set`
+- set supported SecretRef values through `config set-ref`
+- run setup/onboarding bootstrap
+- change the default model
+- start, stop, or restart the Gateway
+- create agents
+- install plugins from ClawHub or npm
+- uninstall plugins
+- run doctor repairs that rewrite config or state
+
+Applied writes are recorded in:
+
+```text
+~/.nodmix/audit/crestodian.jsonl
+```
+
+Discovery is not audited. Only applied operations and writes are logged.
+
+`nodmix onboard --modern` starts Crestodian as the modern onboarding preview.
+Plain `nodmix onboard` still runs classic onboarding.
+
+## Setup bootstrap
+
+`setup` is the chat-first onboarding bootstrap. It writes only through typed
+config operations and asks for approval first.
+
+```text
+setup
+setup workspace ~/Projects/work
+setup workspace ~/Projects/work model openai/gpt-5.5
+```
+
+When no model is configured, setup selects the first usable backend in this
+order and tells you what it chose:
+
+- existing explicit model, if already configured
+- `OPENAI_API_KEY` -> `openai/gpt-5.5`
+- `ANTHROPIC_API_KEY` -> `anthropic/claude-opus-4-7`
+- Claude Code CLI -> `claude-cli/claude-opus-4-7`
+- Codex -> `openai/gpt-5.5` through the Codex app-server harness
+
+If none are available, setup still writes the default workspace and leaves the
+model unset. Install or log into Codex/Claude Code, or expose
+`OPENAI_API_KEY`/`ANTHROPIC_API_KEY`, then run setup again.
+
+## Model-Assisted Planner
+
+Crestodian always starts in deterministic mode. For fuzzy commands that the
+deterministic parser does not understand, local Crestodian can make one bounded
+planner turn through Nodmix's normal runtime paths. It first uses the
+configured Nodmix model. If no configured model is usable yet, it can fall
+back to local runtimes already present on the machine:
+
+- Claude Code CLI: `claude-cli/claude-opus-4-7`
+- Codex app-server harness: `openai/gpt-5.5`
+
+The model-assisted planner cannot mutate config directly. It must translate the
+request into one of Crestodian's typed commands, then the normal approval and
+audit rules apply. Crestodian prints the model it used and the interpreted
+command before it runs anything. Configless fallback planner turns are
+temporary, tool-disabled where the runtime supports it, and use a temporary
+workspace/session.
+
+Message-channel rescue mode does not use the model-assisted planner. Remote
+rescue stays deterministic so a broken or compromised normal agent path cannot
+be used as a config editor.
+
+## Switching to an agent
+
+Use a natural-language selector to leave Crestodian and open the normal TUI:
+
+```text
+talk to agent
+talk to work agent
+switch to main agent
+```
+
+`nodmix tui`, `nodmix chat`, and `nodmix terminal` still open the normal
+agent TUI directly. They do not start Crestodian.
+
+After switching into the normal TUI, use `/crestodian` to return to Crestodian.
+You can include a follow-up request:
+
+```text
+/crestodian
+/crestodian restart gateway
+```
+
+Agent switches inside the TUI leave a breadcrumb that `/crestodian` is available.
+
+## Message rescue mode
+
+Message rescue mode is the message-channel entrypoint for Crestodian. It is for
+the case where your normal agent is dead, but a trusted channel such as WhatsApp
+still receives commands.
+
+Supported text command:
+
+- `/crestodian <request>`
+
+Operator flow:
+
+```text
+You, in a trusted owner DM: /crestodian status
+Nodmix: Crestodian rescue mode. Gateway reachable: no. Config valid: no.
+You: /crestodian restart gateway
+Nodmix: Plan: restart the Gateway. Reply /crestodian yes to apply.
+You: /crestodian yes
+Nodmix: Applied. Audit entry written.
+```
+
+Agent creation can also be queued from the local prompt or rescue mode:
+
+```text
+create agent work workspace ~/Projects/work model openai/gpt-5.5
+/crestodian create agent work workspace ~/Projects/work
+```
+
+Remote rescue mode is an admin surface. It must be treated like remote config
+repair, not like normal chat.
+
+Security contract for remote rescue:
+
+- Disabled when sandboxing is active. If an agent/session is sandboxed,
+  Crestodian must refuse remote rescue and explain that local CLI repair is
+  required.
+- Default effective state is `auto`: allow remote rescue only in trusted YOLO
+  operation, where the runtime already has unsandboxed local authority.
+- Require an explicit owner identity. Rescue must not accept wildcard sender
+  rules, open group policy, unauthenticated webhooks, or anonymous channels.
+- Owner DMs only by default. Group/channel rescue requires explicit opt-in.
+- Plugin search and list are read-only. Plugin install is local-only by default
+  because it downloads executable code. Plugin uninstall can be allowed as an
+  approved repair operation when rescue policy permits persistent writes.
+- Remote rescue cannot open the local TUI or switch into an interactive agent
+  session. Use local `nodmix` for agent handoff.
+- Persistent writes still require approval, even in rescue mode.
+- Audit every applied rescue operation. Message-channel rescue records channel,
+  account, sender, and source-address metadata. Config-mutating operations also
+  record config hashes before and after.
+- Never echo secrets. SecretRef inspection should report availability, not
+  values.
+- If the Gateway is alive, prefer Gateway typed operations. If the Gateway is
+  dead, use only the minimal local repair surface that does not depend on the
+  normal agent loop.
+
+Config shape:
+
+```jsonc
+{
+  "crestodian": {
+    "rescue": {
+      "enabled": "auto",
+      "ownerDmOnly": true,
+    },
+  },
+}
+```
+
+`enabled` should accept:
+
+- `"auto"`: default. Allow only when the effective runtime is YOLO and
+  sandboxing is off.
+- `false`: never allow message-channel rescue.
+- `true`: explicitly allow rescue when the owner/channel checks pass. This
+  still must not bypass the sandboxing denial.
+
+The default `"auto"` YOLO posture is:
+
+- sandbox mode resolves to `off`
+- `tools.exec.security` resolves to `full`
+- `tools.exec.ask` resolves to `off`
+
+Remote rescue is covered by the Docker lane:
+
+```bash
+pnpm test:docker:crestodian-rescue
+```
+
+Configless local planner fallback is covered by:
+
+```bash
+pnpm test:docker:crestodian-planner
+```
+
+An opt-in live channel command-surface smoke checks `/crestodian status` plus a
+persistent approval roundtrip through the rescue handler:
+
+```bash
+pnpm test:live:crestodian-rescue-channel
+```
+
+Fresh configless setup through Crestodian is covered by:
+
+```bash
+pnpm test:docker:crestodian-first-run
+```
+
+That lane starts with an empty state dir, routes bare `nodmix` to Crestodian,
+sets the default model, creates an additional agent, configures Discord through
+a plugin enablement plus token SecretRef, validates config, and checks the audit
+log. QA Lab also has a repo-backed scenario for the same Ring 0 flow:
+
+```bash
+pnpm nodmix qa suite --scenario crestodian-ring-zero-setup
+```
+
+## Related
+
+- [CLI reference](/cli)
+- [Doctor](/cli/doctor)
+- [TUI](/cli/tui)
+- [Sandbox](/cli/sandbox)
+- [Security](/cli/security)

package/docs/cli/cron.md

@@ -0,0 +1,281 @@
+---
+summary: "CLI reference for `nodmix cron` (schedule and run background jobs)"
+read_when:
+  - You want scheduled jobs and wakeups
+  - You are debugging cron execution and logs
+title: "Cron"
+---
+
+# `nodmix cron`
+
+Manage cron jobs for the Gateway scheduler.
+
+<Tip>
+Run `nodmix cron --help` for the full command surface. See [Cron jobs](/automation/cron-jobs) for the conceptual guide.
+</Tip>
+
+## Sessions
+
+`--session` accepts `main`, `isolated`, `current`, or `session:<id>`.
+
+<AccordionGroup>
+  <Accordion title="Session keys">
+    - `main` binds to the agent's main session.
+    - `isolated` creates a fresh transcript and session id for each run.
+    - `current` binds to the active session at creation time.
+    - `session:<id>` pins to an explicit persistent session key.
+
+  </Accordion>
+  <Accordion title="Isolated session semantics">
+    Isolated runs reset ambient conversation context. Channel and group routing, send/queue policy, elevation, origin, and ACP runtime binding are reset for the new run. Safe preferences and explicit user-selected model or auth overrides can carry across runs.
+  </Accordion>
+</AccordionGroup>
+
+## Delivery
+
+`nodmix cron list` and `nodmix cron show <job-id>` preview the resolved delivery route. For `channel: "last"`, the preview shows whether the route resolved from the main or current session, or will fail closed.
+
+Provider-prefixed targets can disambiguate unresolved announce channels. For example, `to: "telegram:123"` selects Telegram when `delivery.channel` is omitted or `last`. Only prefixes advertised by the loaded plugin are provider selectors. If `delivery.channel` is explicit, the prefix must match that channel; `channel: "whatsapp"` with `to: "telegram:123"` is rejected. Service prefixes such as `imessage:` and `sms:` remain channel-owned target syntax.
+
+<Note>
+Isolated `cron add` jobs default to `--announce` delivery. Use `--no-deliver` to keep output internal. `--deliver` remains as a deprecated alias for `--announce`.
+</Note>
+
+### Delivery ownership
+
+Isolated cron chat delivery is shared between the agent and the runner:
+
+- The agent can send directly using the `message` tool when a chat route is available.
+- `announce` fallback-delivers the final reply only when the agent did not send directly to the resolved target.
+- `webhook` posts the finished payload to a URL.
+- `none` disables runner fallback delivery.
+
+`--announce` is runner fallback delivery for the final reply. `--no-deliver` disables that fallback but does not remove the agent's `message` tool when a chat route is available.
+
+Reminders created from an active chat preserve the live chat delivery target for fallback announce delivery. Internal session keys may be lowercase; do not use them as a source of truth for case-sensitive provider IDs such as Matrix room IDs.
+
+### Failure delivery
+
+Failure notifications resolve in this order:
+
+1. `delivery.failureDestination` on the job.
+2. Global `cron.failureDestination`.
+3. The job's primary announce target (when no explicit failure destination is set).
+
+<Note>
+Main-session jobs may only use `delivery.failureDestination` when primary delivery mode is `webhook`. Isolated jobs accept it in all modes.
+</Note>
+
+Note: isolated cron runs treat run-level agent failures as job errors even when
+no reply payload is produced, so model/provider failures still increment error
+counters and trigger failure notifications.
+
+If an isolated run times out before the first model request, `nodmix cron show`
+and `nodmix cron runs` include a phase-specific error such as
+`setup timed out before runner start` or
+`stalled before first model call (last phase: context-engine)`.
+For CLI-backed providers, the pre-model watchdog stays active until the external
+CLI turn starts, so session lookup, hook, auth, prompt, and CLI setup stalls are
+reported as pre-model cron failures.
+
+## Scheduling
+
+### One-shot jobs
+
+`--at <datetime>` schedules a one-shot run. Offset-less datetimes are treated as UTC unless you also pass `--tz <iana>`, which interprets the wall-clock time in the given timezone.
+
+<Note>
+One-shot jobs delete after success by default. Use `--keep-after-run` to preserve them.
+</Note>
+
+### Recurring jobs
+
+Recurring jobs use exponential retry backoff after consecutive errors: 30s, 1m, 5m, 15m, 60m. The schedule returns to normal after the next successful run.
+
+Skipped runs are tracked separately from execution errors. They do not affect retry backoff, but `nodmix cron edit <job-id> --failure-alert-include-skipped` can opt failure alerts into repeated skipped-run notifications.
+
+For isolated jobs that target a local configured model provider, cron runs a lightweight provider preflight before starting the agent turn. Loopback, private-network, and `.local` `api: "ollama"` providers are probed at `/api/tags`; local OpenAI-compatible providers such as vLLM, SGLang, and LM Studio are probed at `/models`. If the endpoint is unreachable, the run is recorded as `skipped` and retried on a later schedule; matching dead endpoints are cached for 5 minutes to avoid many jobs hammering the same local server.
+
+Note: cron job definitions live in `jobs.json`, while pending runtime state lives in `jobs-state.json`. If `jobs.json` is edited externally, the Gateway reloads changed schedules and clears stale pending slots; formatting-only rewrites do not clear the pending slot.
+
+### Manual runs
+
+`nodmix cron run <job-id>` force-runs by default and returns as soon as the manual run is queued. Successful responses include `{ ok: true, enqueued: true, runId }`. Use the returned `runId` to inspect the later result:
+
+```bash
+nodmix cron run <job-id>
+nodmix cron runs --id <job-id> --run-id <run-id>
+```
+
+Add `--wait` when a script should block until that exact queued run records a terminal status:
+
+```bash
+nodmix cron run <job-id> --wait --wait-timeout 10m --poll-interval 2s
+```
+
+With `--wait`, the CLI still calls `cron.run` first, then polls `cron.runs` for the returned `runId`. The command exits `0` only when the run finishes with status `ok`. It exits non-zero when the run finishes with `error` or `skipped`, when the Gateway response does not include a `runId`, or when `--wait-timeout` expires. `--poll-interval` must be greater than zero.
+
+<Note>
+Use `--due` when you want the manual command to run only if the job is currently due. If `--due --wait` does not enqueue a run, the command returns the normal non-run response instead of polling.
+</Note>
+
+## Models
+
+`cron add|edit --model <ref>` selects an allowed model for the job.
+
+<Warning>
+If the model is not allowed or cannot be resolved, cron fails the run with an explicit validation error instead of falling back to the job's agent or default model selection.
+</Warning>
+
+Cron `--model` is a **job primary**, not a chat-session `/model` override. That means:
+
+- Configured model fallbacks still apply when the selected job model fails.
+- Per-job payload `fallbacks` replaces the configured fallback list when present.
+- An empty per-job fallback list (`fallbacks: []` in the job payload/API) makes the cron run strict.
+- When a job has `--model` but no fallback list is configured, Nodmix passes an explicit empty fallback override so the agent primary is not appended as a hidden retry target.
+
+`nodmix doctor` reports jobs that already have `payload.model` set, including provider namespace counts and mismatches against `agents.defaults.model`. Use that check when auth, provider, or billing behavior looks different between live chat and scheduled jobs.
+
+### Isolated cron model precedence
+
+Isolated cron resolves the active model in this order:
+
+1. Gmail-hook override.
+2. Per-job `--model`.
+3. Stored cron-session model override (when the user selected one).
+4. Agent or default model selection.
+
+### Fast mode
+
+Isolated cron fast mode follows the resolved live model selection. Model config `params.fastMode` applies by default, but a stored session `fastMode` override still wins over config.
+
+### Live model switch retries
+
+If an isolated run throws `LiveSessionModelSwitchError`, cron persists the switched provider and model (and switched auth profile override when present) for the active run before retrying. The outer retry loop is bounded to two switch retries after the initial attempt, then aborts instead of looping forever.
+
+## Run output and denials
+
+### Stale acknowledgement suppression
+
+Isolated cron turns suppress stale acknowledgement-only replies. If the first result is just an interim status update and no descendant subagent run is responsible for the eventual answer, cron re-prompts once for the real result before delivery.
+
+### Silent token suppression
+
+If an isolated cron run returns only the silent token (`NO_REPLY` or `no_reply`), cron suppresses both direct outbound delivery and the fallback queued summary path, so nothing is posted back to chat.
+
+### Structured denials
+
+Isolated cron runs use structured execution-denial metadata from the embedded run as the authoritative denial signal. They also honor node-host `UNAVAILABLE` wrappers when the nested structured error message starts with `SYSTEM_RUN_DENIED` or `INVALID_REQUEST`.
+
+Cron does not classify final-output prose or approval-looking refusal phrases as denials unless the embedded run also provides structured denial metadata, so ordinary assistant text is not treated as a blocked command.
+
+`cron list` and run history surface the denial reason instead of reporting a blocked command as `ok`.
+
+## Retention
+
+Retention and pruning are controlled in config:
+
+- `cron.sessionRetention` (default `24h`) prunes completed isolated run sessions.
+- `cron.runLog.maxBytes` and `cron.runLog.keepLines` prune `~/.nodmix/cron/runs/<jobId>.jsonl`.
+
+## Migrating older jobs
+
+<Note>
+If you have cron jobs from before the current delivery and store format, run `nodmix doctor --fix`. Doctor normalizes legacy cron fields (`jobId`, `schedule.cron`, top-level delivery fields including legacy `threadId`, payload `provider` delivery aliases) and migrates simple `notify: true` webhook fallback jobs to explicit webhook delivery when `cron.webhook` is configured.
+</Note>
+
+## Common edits
+
+Update delivery settings without changing the message:
+
+```bash
+nodmix cron edit <job-id> --announce --channel telegram --to "123456789"
+```
+
+Disable delivery for an isolated job:
+
+```bash
+nodmix cron edit <job-id> --no-deliver
+```
+
+Enable lightweight bootstrap context for an isolated job:
+
+```bash
+nodmix cron edit <job-id> --light-context
+```
+
+Announce to a specific channel:
+
+```bash
+nodmix cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
+```
+
+Announce to a Telegram forum topic:
+
+```bash
+nodmix cron edit <job-id> --announce --channel telegram --to "-1001234567890" --thread-id 42
+```
+
+Create an isolated job with lightweight bootstrap context:
+
+```bash
+nodmix cron add \
+  --name "Lightweight morning brief" \
+  --cron "0 7 * * *" \
+  --session isolated \
+  --message "Summarize overnight updates." \
+  --light-context \
+  --no-deliver
+```
+
+`--light-context` applies to isolated agent-turn jobs only. For cron runs, lightweight mode keeps bootstrap context empty instead of injecting the full workspace bootstrap set.
+
+## Common admin commands
+
+Manual run and inspection:
+
+```bash
+nodmix cron list
+nodmix cron list --agent ops
+nodmix cron get <job-id>
+nodmix cron show <job-id>
+nodmix cron run <job-id>
+nodmix cron run <job-id> --due
+nodmix cron run <job-id> --wait --wait-timeout 10m
+nodmix cron run <job-id> --wait --wait-timeout 10m --poll-interval 2s
+nodmix cron runs --id <job-id> --limit 50
+nodmix cron runs --id <job-id> --run-id <run-id>
+```
+
+`nodmix cron list` shows all matching jobs by default. Pass `--agent <id>` to show only jobs whose effective normalized agent id matches; jobs without a stored agent id count as the configured default agent.
+
+`nodmix cron get <job-id>` returns the stored job JSON directly. Use `cron show <job-id>` when you want the human-readable view with delivery-route preview.
+
+`cron list --json` and `cron show <job-id> --json` include a top-level `status` field on each job, computed from `enabled`, `state.runningAtMs`, and `state.lastRunStatus`. Values: `disabled`, `running`, `ok`, `error`, `skipped`, or `idle`. This mirrors the human-readable status column so external tooling can read job state without re-deriving it.
+
+`cron runs` entries include delivery diagnostics with the intended cron target, the resolved target, message-tool sends, fallback use, and delivered state.
+
+Agent and session retargeting:
+
+```bash
+nodmix cron edit <job-id> --agent ops
+nodmix cron edit <job-id> --clear-agent
+nodmix cron edit <job-id> --session current
+nodmix cron edit <job-id> --session "session:daily-brief"
+```
+
+`nodmix cron add` warns when `--agent` is omitted on agent-turn jobs and falls back to the default agent (`main`). Pass `--agent <id>` at create time to pin a specific agent.
+
+Delivery tweaks:
+
+```bash
+nodmix cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
+nodmix cron edit <job-id> --best-effort-deliver
+nodmix cron edit <job-id> --no-best-effort-deliver
+nodmix cron edit <job-id> --no-deliver
+```
+
+## Related
+
+- [CLI reference](/cli)
+- [Scheduled tasks](/automation/cron-jobs)

package/docs/cli/daemon.md

@@ -0,0 +1,67 @@
+---
+summary: "CLI reference for `nodmix daemon` (legacy alias for gateway service management)"
+read_when:
+  - You still use `nodmix daemon ...` in scripts
+  - You need service lifecycle commands (install/start/stop/restart/status)
+title: "Daemon"
+---
+
+# `nodmix daemon`
+
+Legacy alias for Gateway service management commands.
+
+`nodmix daemon ...` maps to the same service control surface as `nodmix gateway ...` service commands.
+
+## Usage
+
+```bash
+nodmix daemon status
+nodmix daemon install
+nodmix daemon start
+nodmix daemon stop
+nodmix daemon restart
+nodmix daemon uninstall
+```
+
+## Subcommands
+
+- `status`: show service install state and probe Gateway health
+- `install`: install service (`launchd`/`systemd`/`schtasks`)
+- `uninstall`: remove service
+- `start`: start service
+- `stop`: stop service
+- `restart`: restart service
+
+## Common options
+
+- `status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
+- `install`: `--port`, `--runtime <node|bun>`, `--token`, `--force`, `--json`
+- `restart`: `--safe`, `--skip-deferral`, `--force`, `--wait <duration>`, `--json`
+- lifecycle (`uninstall|start|stop`): `--json`
+
+Notes:
+
+- `status` resolves configured auth SecretRefs for probe auth when possible.
+- If a required auth SecretRef is unresolved in this command path, `daemon 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.
+- `status --deep` adds a best-effort system-level service scan. When it finds other gateway-like services, human output prints cleanup hints and warns that one gateway per machine is still the normal recommendation.
+- `status --deep` also runs config validation in plugin-aware mode and surfaces configured plugin manifest warnings (for example missing channel config metadata) so install and update smoke checks catch them. Default `status` keeps the fast read-only path that skips plugin validation.
+- On Linux systemd installs, `status` token-drift checks include both `Environment=` and `EnvironmentFile=` unit sources.
+- 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.
+- When token auth requires a token and `gateway.auth.token` is SecretRef-managed, `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.
+- 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.
+- On macOS, `install` keeps LaunchAgent plists owner-only and loads managed service environment values through an owner-only file and wrapper instead of serializing API keys or auth-profile env refs into `EnvironmentVariables`.
+- If you intentionally run multiple gateways on one host, isolate ports, config/state, and workspaces; see [/gateway#multiple-gateways-same-host](/gateway#multiple-gateways-same-host).
+- `restart --safe` asks the running Gateway to preflight active work and schedule one coalesced restart after active work drains. Plain `restart` keeps the existing service-manager behavior; `--force` remains the immediate override path.
+- `restart --safe --skip-deferral` runs the Nodmix-aware safe restart but bypasses the active-work deferral gate so the Gateway emits the restart immediately even when blockers are reported. Operator escape hatch when a stuck task run pins the safe restart; requires `--safe`.
+
+## Prefer
+
+Use [`nodmix gateway`](/cli/gateway) for current docs and examples.
+
+## Related
+
+- [CLI reference](/cli)
+- [Gateway runbook](/gateway)