nodmix 2026.5.25

package/docs/cli/dashboard.md

@@ -0,0 +1,33 @@
+---
+summary: "CLI reference for `nodmix dashboard` (open the Control UI)"
+read_when:
+  - You want to open the Control UI with your current token
+  - You want to print the URL without launching a browser
+title: "Dashboard"
+---
+
+# `nodmix dashboard`
+
+Open the Control UI using your current auth.
+
+```bash
+nodmix dashboard
+nodmix dashboard --no-open
+```
+
+Notes:
+
+- `dashboard` resolves configured `gateway.auth.token` SecretRefs when possible.
+- `dashboard` follows `gateway.tls.enabled`: TLS-enabled gateways print/open
+  `https://` Control UI URLs and connect over `wss://`.
+- If clipboard/browser delivery fails for a token-authenticated dashboard URL,
+  `dashboard` logs a safe manual-auth hint naming `NODMIX_GATEWAY_TOKEN`,
+  `gateway.auth.token`, and fragment key `token` without printing the token
+  value.
+- For SecretRef-managed tokens (resolved or unresolved), `dashboard` prints/copies/opens a non-tokenized URL to avoid exposing external secrets in terminal output, clipboard history, or browser-launch arguments.
+- If `gateway.auth.token` is SecretRef-managed but unresolved in this command path, the command prints a non-tokenized URL and explicit remediation guidance instead of embedding an invalid token placeholder.
+
+## Related
+
+- [CLI reference](/cli)
+- [Dashboard](/web/dashboard)

package/docs/cli/devices.md

@@ -0,0 +1,204 @@
+---
+summary: "CLI reference for `nodmix devices` (device pairing + token rotation/revocation)"
+read_when:
+  - You are approving device pairing requests
+  - You need to rotate or revoke device tokens
+title: "Devices"
+---
+
+# `nodmix devices`
+
+Manage device pairing requests and device-scoped tokens.
+
+## Commands
+
+### `nodmix devices list`
+
+List pending pairing requests and paired devices.
+
+```
+nodmix devices list
+nodmix devices list --json
+```
+
+Pending request output shows the requested access next to the device's current
+approved access when the device is already paired. This makes scope/role
+upgrades explicit instead of looking like the pairing was lost.
+
+### `nodmix devices remove <deviceId>`
+
+Remove one paired device entry.
+
+When you are authenticated with a paired device token, non-admin callers can
+remove only **their own** device entry. Removing some other device requires
+`operator.admin`.
+
+```
+nodmix devices remove <deviceId>
+nodmix devices remove <deviceId> --json
+```
+
+### `nodmix devices clear --yes [--pending]`
+
+Clear paired devices in bulk.
+
+```
+nodmix devices clear --yes
+nodmix devices clear --yes --pending
+nodmix devices clear --yes --pending --json
+```
+
+### `nodmix devices approve [requestId] [--latest]`
+
+Approve a pending device pairing request by exact `requestId`. If `requestId`
+is omitted or `--latest` is passed, Nodmix only prints the selected pending
+request and exits; rerun approval with the exact request ID after verifying
+the details.
+
+<Note>
+If a device retries pairing with changed auth details (role, scopes, or public key), Nodmix supersedes the previous pending entry and issues a new `requestId`. Run `nodmix devices list` right before approval to use the current ID.
+</Note>
+
+If the device is already paired and asks for broader scopes or a broader role,
+Nodmix keeps the existing approval in place and creates a new pending upgrade
+request. Review the `Requested` vs `Approved` columns in `nodmix devices list`
+or use `nodmix devices approve --latest` to preview the exact upgrade before
+approving it.
+
+If the Gateway is explicitly configured with
+`gateway.nodes.pairing.autoApproveCidrs`, first-time `role: node` requests from
+matching client IPs can be approved before they appear in this list. That policy
+is disabled by default and never applies to operator/browser clients or upgrade
+requests.
+
+```
+nodmix devices approve
+nodmix devices approve <requestId>
+nodmix devices approve --latest
+```
+
+### `nodmix devices reject <requestId>`
+
+Reject a pending device pairing request.
+
+```
+nodmix devices reject <requestId>
+```
+
+### `nodmix devices rotate --device <id> --role <role> [--scope <scope...>]`
+
+Rotate a device token for a specific role (optionally updating scopes).
+The target role must already exist in that device's approved pairing contract;
+rotation cannot mint a new unapproved role.
+If you omit `--scope`, later reconnects with the stored rotated token reuse that
+token's cached approved scopes. If you pass explicit `--scope` values, those
+become the stored scope set for future cached-token reconnects.
+Non-admin paired-device callers can rotate only their **own** device token.
+The target token scope set must stay within the caller session's own operator
+scopes; rotation cannot mint or preserve a broader operator token than the
+caller already has.
+
+```
+nodmix devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
+```
+
+Returns rotation metadata as JSON. If the caller is rotating its own token while
+authenticated with that device token, the response also includes the replacement
+token so the client can persist it before reconnecting. Shared/admin rotations
+do not echo the bearer token.
+
+### `nodmix devices revoke --device <id> --role <role>`
+
+Revoke a device token for a specific role.
+
+Non-admin paired-device callers can revoke only their **own** device token.
+Revoking some other device's token requires `operator.admin`.
+The target token scope set must also fit within the caller session's own
+operator scopes; pairing-only callers cannot revoke admin/write operator tokens.
+
+```
+nodmix devices revoke --device <deviceId> --role node
+```
+
+Returns the revoke result as JSON.
+
+## Common options
+
+- `--url <url>`: Gateway WebSocket URL (defaults to `gateway.remote.url` when configured).
+- `--token <token>`: Gateway token (if required).
+- `--password <password>`: Gateway password (password auth).
+- `--timeout <ms>`: RPC timeout.
+- `--json`: JSON output (recommended for scripting).
+
+<Warning>
+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.
+</Warning>
+
+## Notes
+
+- Token rotation returns a new token (sensitive). Treat it like a secret.
+- These commands require `operator.pairing` (or `operator.admin`) scope. Some
+  approvals also require the caller to hold the operator scopes that the target
+  device would mint or inherit; see [Operator scopes](/gateway/operator-scopes).
+- `gateway.nodes.pairing.autoApproveCidrs` is an opt-in Gateway policy for
+  fresh node device pairing only; it does not change CLI approval authority.
+- Token rotation and revocation stay inside the approved pairing role set and
+  approved scope baseline for that device. A stray cached token entry does not
+  grant a token-management target.
+- For paired-device token sessions, cross-device management is admin-only:
+  `remove`, `rotate`, and `revoke` are self-only unless the caller has
+  `operator.admin`.
+- Token mutation is also caller-scope contained: a pairing-only session cannot
+  rotate or revoke a token that currently carries `operator.admin` or
+  `operator.write`.
+- `devices clear` is intentionally gated by `--yes`.
+- If pairing scope is unavailable on local loopback (and no explicit `--url` is passed), list/approve can use a local pairing fallback.
+- `devices approve` requires an explicit request ID before minting tokens; omitting `requestId` or passing `--latest` only previews the newest pending request.
+
+## Token drift recovery checklist
+
+Use this when Control UI or other clients keep failing with `AUTH_TOKEN_MISMATCH`, `AUTH_DEVICE_TOKEN_MISMATCH`, or `AUTH_SCOPE_MISMATCH`.
+
+1. Confirm current gateway token source:
+
+```bash
+nodmix config get gateway.auth.token
+```
+
+2. List paired devices and identify the affected device id:
+
+```bash
+nodmix devices list
+```
+
+3. Rotate operator token for the affected device:
+
+```bash
+nodmix devices rotate --device <deviceId> --role operator
+```
+
+4. If rotation is not enough, remove stale pairing and approve again:
+
+```bash
+nodmix devices remove <deviceId>
+nodmix devices list
+nodmix devices approve <requestId>
+```
+
+5. Retry client connection with the current shared token/password.
+
+Notes:
+
+- Normal reconnect auth precedence is explicit shared token/password first, then explicit `deviceToken`, then stored device token, then bootstrap token.
+- Trusted `AUTH_TOKEN_MISMATCH` recovery can temporarily send both the shared token and the stored device token together for the one bounded retry.
+- `AUTH_SCOPE_MISMATCH` means the device token was recognized but does not carry the requested scope set; fix the pairing/scope approval contract before changing shared gateway auth.
+
+Related:
+
+- [Dashboard auth troubleshooting](/web/dashboard#if-you-see-unauthorized-1008)
+- [Gateway troubleshooting](/gateway/troubleshooting#dashboard-control-ui-connectivity)
+
+## Related
+
+- [CLI reference](/cli)
+- [Nodes](/nodes)

package/docs/cli/directory.md

@@ -0,0 +1,68 @@
+---
+summary: "CLI reference for `nodmix directory` (self, peers, groups)"
+read_when:
+  - You want to look up contacts/groups/self ids for a channel
+  - You are developing a channel directory adapter
+title: "Directory"
+---
+
+# `nodmix directory`
+
+Directory lookups for channels that support it (contacts/peers, groups, and "me").
+
+## Common flags
+
+- `--channel <name>`: channel id/alias (required when multiple channels are configured; auto when only one is configured)
+- `--account <id>`: account id (default: channel default)
+- `--json`: output JSON
+
+## Notes
+
+- `directory` is meant to help you find IDs you can paste into other commands (especially `nodmix message send --target ...`).
+- For many channels, results are config-backed (allowlists / configured groups) rather than a live provider directory.
+- Installed channel plugins can still omit directory support; in that case the command reports the unsupported directory operation instead of reinstalling the plugin.
+- Default output is `id` (and sometimes `name`) separated by a tab; use `--json` for scripting.
+
+## Using results with `message send`
+
+```bash
+nodmix directory peers list --channel slack --query "U0"
+nodmix message send --channel slack --target user:U012ABCDEF --message "hello"
+```
+
+## ID formats (by channel)
+
+- WhatsApp: `+15551234567` (DM), `1234567890-1234567890@g.us` (group), `120363123456789@newsletter` (Channel/Newsletter outbound target)
+- Telegram: `@username` or numeric chat id; groups are numeric ids
+- Slack: `user:U…` and `channel:C…`
+- Discord: `user:<id>` and `channel:<id>`
+- Matrix (plugin): `user:@user:server`, `room:!roomId:server`, or `#alias:server`
+- Microsoft Teams (plugin): `user:<id>` and `conversation:<id>`
+- Zalo (plugin): user id (Bot API)
+- Zalo Personal / `zalouser` (plugin): thread id (DM/group) from `zca` (`me`, `friend list`, `group list`)
+
+## Self ("me")
+
+```bash
+nodmix directory self --channel zalouser
+```
+
+## Peers (contacts/users)
+
+```bash
+nodmix directory peers list --channel zalouser
+nodmix directory peers list --channel zalouser --query "name"
+nodmix directory peers list --channel zalouser --limit 50
+```
+
+## Groups
+
+```bash
+nodmix directory groups list --channel zalouser
+nodmix directory groups list --channel zalouser --query "work"
+nodmix directory groups members --channel zalouser --group-id <id>
+```
+
+## Related
+
+- [CLI reference](/cli)

package/docs/cli/dns.md

@@ -0,0 +1,53 @@
+---
+summary: "CLI reference for `nodmix dns` (wide-area discovery helpers)"
+read_when:
+  - You want wide-area discovery (DNS-SD) via Tailscale + CoreDNS
+  - You're setting up split DNS for a custom discovery domain (example: nodmix.internal)
+title: "DNS"
+---
+
+# `nodmix dns`
+
+DNS helpers for wide-area discovery (Tailscale + CoreDNS). Currently focused on macOS + Homebrew CoreDNS.
+
+Related:
+
+- Gateway discovery: [Discovery](/gateway/discovery)
+- Wide-area discovery config: [Configuration](/gateway/configuration)
+
+## Setup
+
+```bash
+nodmix dns setup
+nodmix dns setup --domain nodmix.internal
+nodmix dns setup --apply
+```
+
+## `dns setup`
+
+Plan or apply CoreDNS setup for unicast DNS-SD discovery.
+
+Options:
+
+- `--domain <domain>`: wide-area discovery domain (for example `nodmix.internal`)
+- `--apply`: install or update CoreDNS config and restart the service (requires sudo; macOS only)
+
+What it shows:
+
+- resolved discovery domain
+- zone file path
+- current tailnet IPs
+- recommended `nodmix.json` discovery config
+- the Tailscale Split DNS nameserver/domain values to set
+
+Notes:
+
+- Without `--apply`, the command is a planning helper only and prints the recommended setup.
+- If `--domain` is omitted, Nodmix uses `discovery.wideArea.domain` from config.
+- `--apply` currently supports macOS only and expects Homebrew CoreDNS.
+- `--apply` bootstraps the zone file if needed, ensures the CoreDNS import stanza exists, and restarts the `coredns` brew service.
+
+## Related
+
+- [CLI reference](/cli)
+- [Discovery](/gateway/discovery)

package/docs/cli/docs.md

@@ -0,0 +1,73 @@
+---
+summary: "CLI reference for `nodmix docs` (search the live docs index)"
+read_when:
+  - You want to search the live Nodmix docs from the terminal
+  - You need to know which helper binaries the docs CLI shells out to
+title: "Docs"
+---
+
+# `nodmix docs`
+
+Search the live Nodmix docs index from the terminal. The command shells out to the public Mintlify-hosted docs MCP search endpoint at `https://docs.nodmix.ai/mcp.search_open_claw` and renders the results in your terminal.
+
+## Usage
+
+```bash
+nodmix docs                       # print docs entrypoint and example search
+nodmix docs <query...>            # search the live docs index
+```
+
+Arguments:
+
+| Argument     | Description                                                                        |
+| ------------ | ---------------------------------------------------------------------------------- |
+| `[query...]` | Free-form search query. Multi-word queries are joined with spaces and sent as one. |
+
+## Examples
+
+```bash
+nodmix docs browser existing-session
+nodmix docs sandbox allowHostControl
+nodmix docs gateway token secretref
+```
+
+With no query, `nodmix docs` prints the docs entrypoint URL plus a sample search command instead of running a search.
+
+## How it works
+
+`nodmix docs` invokes the `mcporter` CLI to call the docs search MCP tool, then parses the `Title: / Link: / Content:` blocks from the tool output into a list of results.
+
+To resolve `mcporter`, Nodmix checks in order:
+
+1. `mcporter` on `PATH` (used directly if present).
+2. `pnpm dlx mcporter ...` if `pnpm` is installed.
+3. `npx -y mcporter ...` if `npx` is installed.
+
+If none are available, the command fails with a hint to install `pnpm` (`npm install -g pnpm`).
+
+The search call uses a fixed 30 second timeout. Result snippets are truncated to ~220 characters per entry.
+
+## Output
+
+In a rich (TTY) terminal, results render as a heading followed by a bullet list. Each bullet shows the page title, the linked docs URL, and a short snippet on the next line. Empty results print "No results.".
+
+In non-rich output (piped, `--no-color`, scripts), the same data renders as Markdown:
+
+```markdown
+# Docs search: <query>
+
+- [Title](https://docs.nodmix.ai/...) - snippet
+- [Title](https://docs.nodmix.ai/...) - snippet
+```
+
+## Exit codes
+
+| Code | Meaning                                             |
+| ---- | --------------------------------------------------- |
+| `0`  | Search succeeded (including zero-result responses). |
+| `1`  | The MCP tool call failed; stderr is printed inline. |
+
+## Related
+
+- [CLI reference](/cli)
+- [Live docs](https://docs.nodmix.ai)

package/docs/cli/doctor.md

@@ -0,0 +1,237 @@
+---
+summary: "CLI reference for `nodmix doctor` (health checks + guided repairs)"
+read_when:
+  - You have connectivity/auth issues and want guided fixes
+  - You updated and want a sanity check
+title: "Doctor"
+---
+
+# `nodmix doctor`
+
+Health checks + quick fixes for the gateway and channels.
+
+Related:
+
+- Troubleshooting: [Troubleshooting](/gateway/troubleshooting)
+- Security audit: [Security](/gateway/security)
+
+## Why Use It
+
+`nodmix doctor` is the Nodmix health surface. Use it when the gateway,
+channels, plugins, skills, model routing, local state, or config migrations are
+not behaving as expected and you want one command that can explain what is
+wrong.
+
+Doctor has three postures:
+
+| Posture | Command                  | Behavior                                                                        |
+| ------- | ------------------------ | ------------------------------------------------------------------------------- |
+| Inspect | `nodmix doctor`        | Human-oriented checks and guided prompts.                                       |
+| Repair  | `nodmix doctor --fix`  | Applies supported repairs, using prompts unless non-interactive repair is safe. |
+| Lint    | `nodmix doctor --lint` | Read-only structured findings for CI, preflight, and review gates.              |
+
+Prefer `--lint` when automation needs a stable result. Prefer `--fix` when a
+human operator intentionally wants doctor to edit config or state.
+
+## Examples
+
+```bash
+nodmix doctor
+nodmix doctor --lint
+nodmix doctor --lint --json
+nodmix doctor --lint --severity-min warning
+nodmix doctor --deep
+nodmix doctor --fix
+nodmix doctor --fix --non-interactive
+nodmix doctor --generate-gateway-token
+```
+
+For channel-specific permissions, use the channel probes instead of `doctor`:
+
+```bash
+nodmix channels capabilities --channel discord --target channel:<channel-id>
+nodmix channels status --probe
+```
+
+The targeted Discord capabilities probe reports the bot's effective channel permissions; the status probe audits configured Discord channels and voice auto-join targets.
+
+## Options
+
+- `--no-workspace-suggestions`: disable workspace memory/search suggestions
+- `--yes`: accept defaults without prompting
+- `--repair`: apply recommended non-service repairs without prompting; gateway service installs and rewrites still require interactive confirmation or explicit gateway commands
+- `--fix`: alias for `--repair`
+- `--force`: apply aggressive repairs, including overwriting custom service config when needed
+- `--non-interactive`: run without prompts; safe migrations and non-service repairs only
+- `--generate-gateway-token`: generate and configure a gateway token
+- `--deep`: scan system services for extra gateway installs and report recent Gateway supervisor restart handoffs
+- `--lint`: run modernized health checks in read-only mode and emit diagnostic findings
+- `--json`: with `--lint`, emit JSON findings instead of human output
+- `--severity-min <level>`: with `--lint`, drop findings below `info`, `warning`, or `error`
+- `--skip <id>`: with `--lint`, skip a check id; repeat to skip more than one
+- `--only <id>`: with `--lint`, run only a check id; repeat to run a small selected set
+
+## Lint mode
+
+`nodmix doctor --lint` is the read-only automation posture for doctor checks.
+It uses the structured health-check path, does not prompt, and does not repair
+or rewrite config/state. Use it in CI, preflight scripts, and review workflows
+when you want machine-readable findings instead of guided repair prompts.
+Lint-output options such as `--json`, `--severity-min`, `--only`, and `--skip`
+are only accepted with `--lint`.
+
+```bash
+nodmix doctor --lint
+nodmix doctor --lint --severity-min warning
+nodmix doctor --lint --json
+nodmix doctor --lint --only core/doctor/gateway-config --json
+```
+
+Human output is compact:
+
+```text
+doctor --lint: ran 6 check(s), 1 finding(s)
+  [warning] core/doctor/gateway-config gateway.mode - gateway.mode is unset; gateway start will be blocked.
+    fix: Run `nodmix configure` and set Gateway mode (local/remote), or `nodmix config set gateway.mode local`.
+```
+
+JSON output is the scripting surface for lint runs:
+
+```json
+{
+  "ok": false,
+  "checksRun": 5,
+  "checksSkipped": 0,
+  "findings": [
+    {
+      "checkId": "core/doctor/gateway-config",
+      "severity": "warning",
+      "message": "gateway.mode is unset; gateway start will be blocked.",
+      "path": "gateway.mode",
+      "fixHint": "Run `nodmix configure` and set Gateway mode (local/remote), or `nodmix config set gateway.mode local`."
+    }
+  ]
+}
+```
+
+Exit behavior:
+
+- `0`: no findings at or above the selected severity threshold
+- `1`: at least one finding meets the selected threshold
+- `2`: command/runtime failure before lint findings can be produced
+
+`--severity-min` controls both visible findings and the exit threshold. For
+example, `nodmix doctor --lint --severity-min error` can print no findings and
+exit `0` even when lower-severity `info` or `warning` findings exist.
+
+## Structured Health Checks
+
+Modern doctor checks use a small structured contract:
+
+```ts
+detect(ctx, scope?) -> HealthFinding[]
+repair?(ctx, findings) -> HealthRepairResult
+```
+
+`detect()` powers `doctor --lint`. `repair()` is optional and is only considered
+by `doctor --fix` / `doctor --repair`. Checks that have not migrated to this
+shape continue to use the legacy doctor contribution flow.
+
+The split is intentional: `detect()` owns diagnosis, while `repair()` owns
+reporting what it changed or would change. Repair contexts can carry
+`dryRun`/`diff` requests, and repair results can return structured `diffs` for
+config/file edits plus `effects` for service, process, package, state, or other
+side effects. That lets converted checks grow toward `doctor --fix --dry-run`
+and diff reporting without moving mutation planning into `detect()`.
+
+`repair()` reports whether it attempted the requested repair with `status:
+"repaired" | "skipped" | "failed"`. Omitted status means `repaired`, so simple
+repair checks only need to return changes. When repair returns `skipped` or
+`failed`, doctor reports the reason and does not run validation for that check.
+
+After a successful structured repair, doctor re-runs `detect()` with the
+repaired findings as scope. Checks can use selected findings, paths, or `ocPath`
+values for focused validation. If the finding is still present, doctor reports a
+repair warning instead of treating the change as silently complete.
+
+A finding includes:
+
+| Field             | Purpose                                                |
+| ----------------- | ------------------------------------------------------ |
+| `checkId`         | Stable id for skip/only filters and CI allowlists.     |
+| `severity`        | `info`, `warning`, or `error`.                         |
+| `message`         | Human-readable problem statement.                      |
+| `path`            | Config, file, or logical path when available.          |
+| `line` / `column` | Source location when available.                        |
+| `ocPath`          | Precise `oc://` address when a check can point to one. |
+| `fixHint`         | Suggested operator action or repair summary.           |
+
+This release registers the modernized core doctor checks on the structured
+health path. The `nodmix/plugin-sdk/health` subpath exposes the same
+contract for bundled follow-up consumers, but plugin-backed checks only run
+after their owning package registers them in the active command path.
+
+## Check Selection
+
+Use `--only` and `--skip` when a workflow wants a focused gate:
+
+```bash
+nodmix doctor --lint --only core/doctor/gateway-config --json
+nodmix doctor --lint --skip core/doctor/skills-readiness
+```
+
+`--only` and `--skip` accept full check ids and may be repeated. If an `--only`
+id is not registered, no check runs for that id; use the command's `checksRun`
+and `checksSkipped` fields to verify a focused gate is selecting the checks you
+expect.
+
+Notes:
+
+- In Nix mode (`NODMIX_NIX_MODE=1`), read-only doctor checks still work, but `doctor --fix`, `doctor --repair`, `doctor --yes`, and `doctor --generate-gateway-token` are disabled because `nodmix.json` is immutable. Edit the Nix source for this install instead; for nix-nodmix, use the agent-first [Quick Start](https://github.com/nodmix/nix-nodmix#quick-start).
+- Interactive prompts (like keychain/OAuth fixes) only run when stdin is a TTY and `--non-interactive` is **not** set. Headless runs (cron, Telegram, no terminal) will skip prompts.
+- Performance: non-interactive `doctor` runs skip eager plugin loading so headless health checks stay fast. Interactive doctor sessions still load the plugin surfaces needed by the legacy health and repair flow.
+- `--lint` is stricter than `--non-interactive`: it is always read-only, never prompts, and never applies safe migrations. Run `doctor --fix` or `doctor --repair` when you want doctor to make changes.
+- `--fix` (alias for `--repair`) writes a backup to `~/.nodmix/nodmix.json.bak` and drops unknown config keys, listing each removal.
+- Modernized health checks can expose a `repair()` path for `doctor --fix`; checks that do not expose one continue through the existing doctor repair flow.
+- `doctor --fix --non-interactive` reports missing or stale gateway service definitions but does not install or rewrite them outside update repair mode. Run `nodmix gateway install` for a missing service, or `nodmix gateway install --force` when you intentionally want to replace the launcher.
+- State integrity checks now detect orphan transcript files in the sessions directory. Archiving them as `.deleted.<timestamp>` requires an interactive confirmation; `--fix`, `--yes`, and headless runs leave them in place.
+- Doctor also scans `~/.nodmix/cron/jobs.json` (or `cron.store`) for legacy cron job shapes and can rewrite them in place before the scheduler has to auto-normalize them at runtime.
+- Doctor reports cron jobs with explicit `payload.model` overrides, including provider namespace counts and mismatches against `agents.defaults.model`, so scheduled jobs that do not inherit the default model are visible during auth or billing investigations.
+- On Linux, doctor warns when the user's crontab still runs legacy `~/.nodmix/bin/ensure-whatsapp.sh`; that script is no longer maintained and can log false WhatsApp gateway outages when cron lacks the systemd user-bus environment.
+- When WhatsApp is enabled, doctor checks for a degraded Gateway event loop with local `nodmix-tui` clients still running. `doctor --fix` stops only verified local TUI clients so WhatsApp replies are not queued behind stale TUI refresh loops.
+- Doctor rewrites legacy `openai-codex/*` model refs to canonical `openai/*` refs across primary models, fallbacks, heartbeat/subagent/compaction overrides, hooks, channel model overrides, and stale session route pins. `--fix` moves Codex intent onto provider/model-scoped `agentRuntime.id: "codex"` entries, preserves session auth-profile pins such as `openai-codex:...`, removes stale whole-agent/session runtime pins, and keeps repaired OpenAI agent refs on Codex auth routing instead of direct OpenAI API-key auth.
+- Doctor cleans legacy plugin dependency staging state created by older Nodmix versions and relinks the host `nodmix` package for managed npm plugins that declare it as a peer dependency. It also repairs missing downloadable plugins that are referenced by config, such as `plugins.entries`, configured channels, configured provider/search settings, or configured agent runtimes. During package updates, doctor skips package-manager plugin repair until the package swap is complete; rerun `nodmix doctor --fix` afterward if a configured plugin still needs recovery. If the download fails, doctor reports the install error and preserves the configured plugin entry for the next repair attempt.
+- Doctor repairs stale plugin config by removing missing plugin ids from `plugins.allow`/`plugins.deny`/`plugins.entries`, plus matching dangling channel config, heartbeat targets, and channel model overrides when plugin discovery is healthy.
+- Doctor quarantines invalid plugin config by disabling the affected `plugins.entries.<id>` entry and removing its invalid `config` payload. Gateway startup already skips only that bad plugin so other plugins and channels can keep running.
+- Set `NODMIX_SERVICE_REPAIR_POLICY=external` when another supervisor owns the gateway lifecycle. Doctor still reports gateway/service health and applies non-service repairs, but skips service install/start/restart/bootstrap and legacy service cleanup.
+- On Linux, doctor ignores inactive extra gateway-like systemd units and does not rewrite command/entrypoint metadata for a running systemd gateway service during repair. Stop the service first or use `nodmix gateway install --force` when you intentionally want to replace the active launcher.
+- Doctor auto-migrates legacy flat Talk config (`talk.voiceId`, `talk.modelId`, and friends) into `talk.provider` + `talk.providers.<provider>`.
+- Repeat `doctor --fix` runs no longer report/apply Talk normalization when the only difference is object key order.
+- Doctor includes a memory-search readiness check and can recommend `nodmix configure --section model` when embedding credentials are missing.
+- Doctor warns when no command owner is configured. The command owner is the human operator account allowed to run owner-only commands and approve dangerous actions. DM pairing only lets someone talk to the bot; if you approved a sender before first-owner bootstrap existed, set `commands.ownerAllowFrom` explicitly.
+- Doctor warns when Codex-mode agents are configured and personal Codex CLI assets exist in the operator's Codex home. Local Codex app-server launches use isolated per-agent homes, so use `nodmix migrate codex --dry-run` to inventory assets that should be promoted deliberately.
+- Doctor removes retired `plugins.entries.codex.config.codexDynamicToolsProfile`; Codex app-server always keeps Codex-native workspace tools native.
+- Doctor warns when skills allowed for the default agent are unavailable in the current runtime environment because bins, env vars, config, or OS requirements are missing. `doctor --fix` can disable those unavailable skills with `skills.entries.<skill>.enabled=false`; install/configure the missing requirement instead when you want to keep the skill active.
+- If sandbox mode is enabled but Docker is unavailable, doctor reports a high-signal warning with remediation (`install Docker` or `nodmix config set agents.defaults.sandbox.mode off`).
+- If legacy sandbox registry files (`~/.nodmix/sandbox/containers.json` or `~/.nodmix/sandbox/browsers.json`) are present, doctor reports them; `nodmix doctor --fix` migrates valid entries into sharded registry directories and quarantines invalid legacy files.
+- If `gateway.auth.token`/`gateway.auth.password` are SecretRef-managed and unavailable in the current command path, doctor reports a read-only warning and does not write plaintext fallback credentials.
+- If channel SecretRef inspection fails in a fix path, doctor continues and reports a warning instead of exiting early.
+- After state-directory migrations, doctor warns when enabled default Telegram or Discord accounts depend on env fallback and `TELEGRAM_BOT_TOKEN` or `DISCORD_BOT_TOKEN` is unavailable to the doctor process.
+- Telegram `allowFrom` username auto-resolution (`doctor --fix`) requires a resolvable Telegram token in the current command path. If token inspection is unavailable, doctor reports a warning and skips auto-resolution for that pass.
+
+## macOS: `launchctl` env overrides
+
+If you previously ran `launchctl setenv NODMIX_GATEWAY_TOKEN ...` (or `...PASSWORD`), that value overrides your config file and can cause persistent "unauthorized" errors.
+
+```bash
+launchctl getenv NODMIX_GATEWAY_TOKEN
+launchctl getenv NODMIX_GATEWAY_PASSWORD
+
+launchctl unsetenv NODMIX_GATEWAY_TOKEN
+launchctl unsetenv NODMIX_GATEWAY_PASSWORD
+```
+
+## Related
+
+- [CLI reference](/cli)
+- [Gateway doctor](/gateway/doctor)