nodmix 2026.5.25

package/docs/plan/ui-channels.md

@@ -0,0 +1,284 @@
+---
+summary: Decouple semantic message presentation from channel native UI renderers.
+title: Channel presentation refactor plan
+read_when:
+  - Refactoring channel message UI, interactive payloads, or native channel renderers
+  - Changing message tool capabilities, delivery hints, or cross-context markers
+  - Debugging Discord Carbon import fanout or channel plugin runtime laziness
+---
+
+## Status
+
+Implemented for the shared agent, CLI, plugin capability, and outbound delivery surfaces:
+
+- `ReplyPayload.presentation` carries semantic message UI.
+- `ReplyPayload.delivery.pin` carries sent-message pin requests.
+- Shared message actions expose `presentation`, `delivery`, and `pin` instead of provider-native `components`, `blocks`, `buttons`, or `card`.
+- Core renders or auto-degrades presentation through plugin-declared outbound capabilities.
+- Discord, Slack, Telegram, Mattermost, MS Teams, and Feishu renderers consume the generic contract.
+- Discord channel control-plane code no longer imports Carbon-backed UI containers.
+
+Canonical docs now live in [Message Presentation](/plugins/message-presentation).
+Keep this plan as historical implementation context; update the canonical guide
+for contract, renderer, or fallback behavior changes.
+
+## Problem
+
+Channel UI is currently split across several incompatible surfaces:
+
+- Core owns a Discord-shaped cross-context renderer hook through `buildCrossContextComponents`.
+- Discord `channel.ts` can import native Carbon UI through `DiscordUiContainer`, which pulls runtime UI dependencies into the channel plugin control plane.
+- The agent and CLI expose native payload escape hatches such as Discord `components`, Slack `blocks`, Telegram or Mattermost `buttons`, and Teams or Feishu `card`.
+- `ReplyPayload.channelData` carries both transport hints and native UI envelopes.
+- The generic `interactive` model exists, but it is narrower than the richer layouts already used by Discord, Slack, Teams, Feishu, LINE, Telegram, and Mattermost.
+
+This makes core aware of native UI shapes, weakens plugin runtime laziness, and gives agents too many provider-specific ways to express the same message intent.
+
+## Goals
+
+- Core decides the best semantic presentation for a message from declared capabilities.
+- Extensions declare capabilities and render semantic presentation into native transport payloads.
+- Web Control UI remains separate from chat native UI.
+- Native channel payloads are not exposed through the shared agent or CLI message surface.
+- Unsupported presentation features auto-degrade to the best text representation.
+- Delivery behavior such as pinning a sent message is generic delivery metadata, not presentation.
+
+## Non goals
+
+- No backwards compatibility shim for `buildCrossContextComponents`.
+- No public native escape hatches for `components`, `blocks`, `buttons`, or `card`.
+- No core imports of channel-native UI libraries.
+- No provider-specific SDK seams for bundled channels.
+
+## Target model
+
+Add a core-owned `presentation` field to `ReplyPayload`.
+
+```ts
+type MessagePresentationTone = "neutral" | "info" | "success" | "warning" | "danger";
+
+type MessagePresentation = {
+  tone?: MessagePresentationTone;
+  title?: string;
+  blocks: MessagePresentationBlock[];
+};
+
+type MessagePresentationBlock =
+  | { type: "text"; text: string }
+  | { type: "context"; text: string }
+  | { type: "divider" }
+  | { type: "buttons"; buttons: MessagePresentationButton[] }
+  | { type: "select"; placeholder?: string; options: MessagePresentationOption[] };
+
+type MessagePresentationButton = {
+  label: string;
+  value?: string;
+  url?: string;
+  style?: "primary" | "secondary" | "success" | "danger";
+};
+
+type MessagePresentationOption = {
+  label: string;
+  value: string;
+};
+```
+
+`interactive` becomes a subset of `presentation` during migration:
+
+- `interactive` text block maps to `presentation.blocks[].type = "text"`.
+- `interactive` buttons block maps to `presentation.blocks[].type = "buttons"`.
+- `interactive` select block maps to `presentation.blocks[].type = "select"`.
+
+The external agent and CLI schemas now use `presentation`; `interactive` remains an internal legacy parser/rendering helper for existing reply producers.
+The public producer-facing API treats `interactive` as deprecated. Runtime
+support remains so existing approval helpers and older plugins continue to
+work while new code emits `presentation`.
+
+## Delivery metadata
+
+Add a core-owned `delivery` field for send behavior that is not UI.
+
+```ts
+type ReplyPayloadDelivery = {
+  pin?:
+    | boolean
+    | {
+        enabled: boolean;
+        notify?: boolean;
+        required?: boolean;
+      };
+};
+```
+
+Semantics:
+
+- `delivery.pin = true` means pin the first successfully delivered message.
+- `notify` defaults to `false`.
+- `required` defaults to `false`; unsupported channels or failed pinning auto-degrade by continuing delivery.
+- Manual `pin`, `unpin`, and `list-pins` message actions remain for existing messages.
+
+Current Telegram ACP topic binding should move from `channelData.telegram.pin = true` to `delivery.pin = true`.
+
+## Runtime capability contract
+
+Add presentation and delivery render hooks to the runtime outbound adapter, not the control-plane channel plugin.
+
+```ts
+type ChannelPresentationCapabilities = {
+  supported: boolean;
+  buttons?: boolean;
+  selects?: boolean;
+  context?: boolean;
+  divider?: boolean;
+  tones?: MessagePresentationTone[];
+  limits?: {
+    actions?: {
+      maxActions?: number;
+      maxActionsPerRow?: number;
+      maxRows?: number;
+      maxLabelLength?: number;
+      maxValueBytes?: number;
+      supportsStyles?: boolean;
+      supportsDisabled?: boolean;
+      supportsLayoutHints?: boolean;
+    };
+    selects?: {
+      maxOptions?: number;
+      maxLabelLength?: number;
+      maxValueBytes?: number;
+    };
+    text?: {
+      maxLength?: number;
+      encoding?: "characters" | "utf8-bytes" | "utf16-units";
+      markdownDialect?: "plain" | "markdown" | "html" | "slack-mrkdwn" | "discord-markdown";
+      supportsEdit?: boolean;
+    };
+  };
+};
+
+type ChannelDeliveryCapabilities = {
+  pinSentMessage?: boolean;
+};
+
+type ChannelOutboundAdapter = {
+  presentationCapabilities?: ChannelPresentationCapabilities;
+
+  renderPresentation?: (params: {
+    payload: ReplyPayload;
+    presentation: MessagePresentation;
+    ctx: ChannelOutboundSendContext;
+  }) => ReplyPayload | null;
+
+  deliveryCapabilities?: ChannelDeliveryCapabilities;
+
+  pinDeliveredMessage?: (params: {
+    cfg: NodmixConfig;
+    accountId?: string | null;
+    to: string;
+    threadId?: string | number | null;
+    messageId: string;
+    notify: boolean;
+  }) => Promise<void>;
+};
+```
+
+Core behavior:
+
+- Resolve target channel and runtime adapter.
+- Ask for presentation capabilities.
+- Degrade unsupported blocks and apply generic capability limits before
+  rendering.
+- Call `renderPresentation`.
+- If no renderer exists, convert presentation to text fallback.
+- After successful send, call `pinDeliveredMessage` when `delivery.pin` is requested and supported.
+
+## Channel mapping
+
+Discord:
+
+- Render `presentation` to components v2 and Carbon containers in runtime-only modules.
+- Keep accent color helpers in light modules.
+- Remove `DiscordUiContainer` imports from channel plugin control-plane code.
+
+Slack:
+
+- Render `presentation` to Block Kit.
+- Remove agent and CLI `blocks` input.
+
+Telegram:
+
+- Render text, context, and dividers as text.
+- Render actions and select as inline keyboards when configured and allowed for the target surface.
+- Use text fallback when inline buttons are disabled.
+- Move ACP topic pinning to `delivery.pin`.
+
+Mattermost:
+
+- Render actions as interactive buttons where configured.
+- Render other blocks as text fallback.
+
+MS Teams:
+
+- Render `presentation` to Adaptive Cards.
+- Keep manual pin/unpin/list-pins actions.
+- Optionally implement `pinDeliveredMessage` if Graph support is reliable for the target conversation.
+
+Feishu:
+
+- Render `presentation` to interactive cards.
+- Keep manual pin/unpin/list-pins actions.
+- Optionally implement `pinDeliveredMessage` for sent-message pinning if API behavior is reliable.
+
+LINE:
+
+- Render `presentation` to Flex or template messages where possible.
+- Fall back to text for unsupported blocks.
+- Remove LINE UI payloads from `channelData`.
+
+Plain or limited channels:
+
+- Convert presentation to text with conservative formatting.
+
+## Refactor steps
+
+1. Reapply the Discord release fix that splits `ui-colors.ts` from Carbon-backed UI and removes `DiscordUiContainer` from `extensions/discord/src/channel.ts`.
+2. Add `presentation` and `delivery` to `ReplyPayload`, outbound payload normalization, delivery summaries, and hook payloads.
+3. Add `MessagePresentation` schema and parser helpers in a narrow SDK/runtime subpath.
+4. Replace message capabilities `buttons`, `cards`, `components`, and `blocks` with semantic presentation capabilities.
+5. Add runtime outbound adapter hooks for presentation render and delivery pinning.
+6. Replace cross-context component construction with `buildCrossContextPresentation`.
+7. Delete `src/infra/outbound/channel-adapters.ts` and remove `buildCrossContextComponents` from channel plugin types.
+8. Change `maybeApplyCrossContextMarker` to attach `presentation` instead of native params.
+9. Update plugin-dispatch send paths to consume only semantic presentation and delivery metadata.
+10. Remove agent and CLI native payload params: `components`, `blocks`, `buttons`, and `card`.
+11. Remove SDK helpers that create native message-tool schemas, replacing them with presentation schema helpers.
+12. Remove UI/native envelopes from `channelData`; keep only transport metadata until each remaining field is reviewed.
+13. Migrate Discord, Slack, Telegram, Mattermost, MS Teams, Feishu, and LINE renderers.
+14. Update docs for message CLI, channel pages, plugin SDK, and capability cookbook.
+15. Run import fanout profiling for Discord and affected channel entrypoints.
+
+Steps 1-11 and 13-14 are implemented in this refactor for the shared agent, CLI, plugin capability, and outbound adapter contracts. Step 12 remains a deeper internal cleanup pass for provider-private `channelData` transport envelopes. Step 15 remains follow-up validation if we want quantified import-fanout numbers beyond the type/test gate.
+
+## Tests
+
+Add or update:
+
+- Presentation normalization tests.
+- Presentation auto-degrade tests for unsupported blocks.
+- Cross-context marker tests for plugin dispatch and core delivery paths.
+- Channel render matrix tests for Discord, Slack, Telegram, Mattermost, MS Teams, Feishu, LINE, and text fallback.
+- Message tool schema tests proving native fields are gone.
+- CLI tests proving native flags are gone.
+- Discord entrypoint import-laziness regression covering Carbon.
+- Delivery pin tests covering Telegram and generic fallback.
+
+## Open questions
+
+- Should `delivery.pin` be implemented for Discord, Slack, MS Teams, and Feishu in the first pass, or only Telegram first?
+- Should `delivery` eventually absorb existing fields such as `replyToId`, `replyToCurrent`, `silent`, and `audioAsVoice`, or stay focused on post-send behaviors?
+- Should presentation support images or file references directly, or should media remain separate from UI layout for now?
+
+## Related
+
+- [Channels overview](/channels)
+- [Message presentation](/plugins/message-presentation)

package/docs/platforms/android.md

@@ -0,0 +1,285 @@
+---
+summary: "Android app (node): connection runbook + Connect/Chat/Voice/Canvas command surface"
+read_when:
+  - Pairing or reconnecting the Android node
+  - Debugging Android gateway discovery or auth
+  - Verifying chat history parity across clients
+title: "Android app"
+---
+
+<Note>
+The official Android app is available on [Google Play](https://play.google.com/store/apps/details?id=ai.nodmix.app&hl=en_IN). It is a companion node and requires a running Nodmix Gateway. The source code is also available in the [Nodmix repository](https://github.com/nodmix/nodmix) under `apps/android`; see [apps/android/README.md](https://github.com/nodmix/nodmix/blob/main/apps/android/README.md) for build instructions.
+</Note>
+
+## Support snapshot
+
+- Role: companion node app (Android does not host the Gateway).
+- Gateway required: yes (run it on macOS, Linux, or Windows via WSL2).
+- Install: [Google Play](https://play.google.com/store/apps/details?id=ai.nodmix.app&hl=en_IN) for the app, [Getting Started](/start/getting-started) for the Gateway, then [Pairing](/channels/pairing).
+- Gateway: [Runbook](/gateway) + [Configuration](/gateway/configuration).
+  - Protocols: [Gateway protocol](/gateway/protocol) (nodes + control plane).
+
+## System control
+
+System control (launchd/systemd) lives on the Gateway host. See [Gateway](/gateway).
+
+## Connection runbook
+
+Android node app ⇄ (mDNS/NSD + WebSocket) ⇄ **Gateway**
+
+Android connects directly to the Gateway WebSocket and uses device pairing (`role: node`).
+
+For Tailscale or public hosts, Android requires a secure endpoint:
+
+- Preferred: Tailscale Serve / Funnel with `https://<magicdns>` / `wss://<magicdns>`
+- Also supported: any other `wss://` Gateway URL with a real TLS endpoint
+- Cleartext `ws://` remains supported on private LAN addresses / `.local` hosts, plus `localhost`, `127.0.0.1`, and the Android emulator bridge (`10.0.2.2`)
+
+### Prerequisites
+
+- You can run the Gateway on the "master" machine.
+- Android device/emulator can reach the gateway WebSocket:
+  - Same LAN with mDNS/NSD, **or**
+  - Same Tailscale tailnet using Wide-Area Bonjour / unicast DNS-SD (see below), **or**
+  - Manual gateway host/port (fallback)
+- Tailnet/public mobile pairing does **not** use raw tailnet IP `ws://` endpoints. Use Tailscale Serve or another `wss://` URL instead.
+- You can run the CLI (`nodmix`) on the gateway machine (or via SSH).
+
+### 1) Start the Gateway
+
+```bash
+nodmix gateway --port 18789 --verbose
+```
+
+Confirm in logs you see something like:
+
+- `listening on ws://0.0.0.0:18789`
+
+For remote Android access over Tailscale, prefer Serve/Funnel instead of a raw tailnet bind:
+
+```bash
+nodmix gateway --tailscale serve
+```
+
+This gives Android a secure `wss://` / `https://` endpoint. A plain `gateway.bind: "tailnet"` setup is not enough for first-time remote Android pairing unless you also terminate TLS separately.
+
+### 2) Verify discovery (optional)
+
+From the gateway machine:
+
+```bash
+dns-sd -B _nodmix-gw._tcp local.
+```
+
+More debugging notes: [Bonjour](/gateway/bonjour).
+
+If you also configured a wide-area discovery domain, compare against:
+
+```bash
+nodmix gateway discover --json
+```
+
+That shows `local.` plus the configured wide-area domain in one pass and uses the resolved
+service endpoint instead of TXT-only hints.
+
+#### Tailnet (Vienna ⇄ London) discovery via unicast DNS-SD
+
+Android NSD/mDNS discovery won't cross networks. If your Android node and the gateway are on different networks but connected via Tailscale, use Wide-Area Bonjour / unicast DNS-SD instead.
+
+Discovery alone is not sufficient for tailnet/public Android pairing. The discovered route still needs a secure endpoint (`wss://` or Tailscale Serve):
+
+1. Set up a DNS-SD zone (example `nodmix.internal.`) on the gateway host and publish `_nodmix-gw._tcp` records.
+2. Configure Tailscale split DNS for your chosen domain pointing at that DNS server.
+
+Details and example CoreDNS config: [Bonjour](/gateway/bonjour).
+
+### 3) Connect from Android
+
+In the Android app:
+
+- The app keeps its gateway connection alive via a **foreground service** (persistent notification).
+- Open the **Connect** tab.
+- Use **Setup Code** or **Manual** mode.
+- If discovery is blocked, use manual host/port in **Advanced controls**. For private LAN hosts, `ws://` still works. For Tailscale/public hosts, turn on TLS and use a `wss://` / Tailscale Serve endpoint.
+
+After the first successful pairing, Android auto-reconnects on launch:
+
+- Manual endpoint (if enabled), otherwise
+- The last discovered gateway (best-effort).
+
+### Presence alive beacons
+
+After the authenticated node session connects, and when the app moves to the background while the
+foreground service is still connected, Android calls `node.event` with
+`event: "node.presence.alive"`. The gateway records this as `lastSeenAtMs`/`lastSeenReason` on the
+paired node/device metadata only after the authenticated node device identity is known.
+
+The app counts the beacon as successfully recorded only when the gateway response includes
+`handled: true`. Older gateways may acknowledge `node.event` with `{ "ok": true }`; that response is
+compatible but does not count as a durable last-seen update.
+
+### 4) Approve pairing (CLI)
+
+On the gateway machine:
+
+```bash
+nodmix devices list
+nodmix devices approve <requestId>
+nodmix devices reject <requestId>
+```
+
+Pairing details: [Pairing](/channels/pairing).
+
+Optional: if the Android node always connects from a tightly controlled subnet,
+you can opt in to first-time node auto-approval with explicit CIDRs or exact IPs:
+
+```json5
+{
+  gateway: {
+    nodes: {
+      pairing: {
+        autoApproveCidrs: ["192.168.1.0/24"],
+      },
+    },
+  },
+}
+```
+
+This is disabled by default. It applies only to fresh `role: node` pairing with
+no requested scopes. Operator/browser pairing and any role, scope, metadata, or
+public-key change still require manual approval.
+
+### 5) Verify the node is connected
+
+- Via nodes status:
+
+  ```bash
+  nodmix nodes status
+  ```
+
+- Via Gateway:
+
+  ```bash
+  nodmix gateway call node.list --params "{}"
+  ```
+
+### 6) Chat + history
+
+The Android Chat tab supports session selection (default `main`, plus other existing sessions):
+
+- History: `chat.history` (display-normalized; inline directive tags are
+  stripped from visible text, plain-text tool-call XML payloads (including
+  `<tool_call>...</tool_call>`, `<function_call>...</function_call>`,
+  `<tool_calls>...</tool_calls>`, `<function_calls>...</function_calls>`, and
+  truncated tool-call blocks) and leaked ASCII/full-width model control tokens
+  are stripped, pure silent-token assistant rows such as exact `NO_REPLY` /
+  `no_reply` are omitted, and oversized rows can be replaced with placeholders)
+- Send: `chat.send`
+- Push updates (best-effort): `chat.subscribe` → `event:"chat"`
+
+### 7) Canvas + camera
+
+#### Gateway Canvas Host (recommended for web content)
+
+If you want the node to show real HTML/CSS/JS that the agent can edit on disk, point the node at the Gateway canvas host.
+
+<Note>
+Nodes load canvas from the Gateway HTTP server (same port as `gateway.port`, default `18789`).
+</Note>
+
+1. Create `~/.nodmix/workspace/canvas/index.html` on the gateway host.
+
+2. Navigate the node to it (LAN):
+
+```bash
+nodmix nodes invoke --node "<Android Node>" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18789/__nodmix__/canvas/"}'
+```
+
+Tailnet (optional): if both devices are on Tailscale, use a MagicDNS name or tailnet IP instead of `.local`, e.g. `http://<gateway-magicdns>:18789/__nodmix__/canvas/`.
+
+This server injects a live-reload client into HTML and reloads on file changes.
+The A2UI host lives at `http://<gateway-host>:18789/__nodmix__/a2ui/`.
+
+Canvas commands (foreground only):
+
+- `canvas.eval`, `canvas.snapshot`, `canvas.navigate` (use `{"url":""}` or `{"url":"/"}` to return to the default scaffold). `canvas.snapshot` returns `{ format, base64 }` (default `format="jpeg"`).
+- A2UI: `canvas.a2ui.push`, `canvas.a2ui.reset` (`canvas.a2ui.pushJSONL` legacy alias)
+
+Camera commands (foreground only; permission-gated):
+
+- `camera.snap` (jpg)
+- `camera.clip` (mp4)
+
+See [Camera node](/nodes/camera) for parameters and CLI helpers.
+
+### 8) Voice + expanded Android command surface
+
+- Voice tab: Android has two explicit capture modes. **Mic** is a manual Voice-tab session that sends each pause as a chat turn and stops when the app leaves the foreground or the user leaves the Voice tab. **Talk** is continuous Talk Mode and keeps listening until toggled off or the node disconnects.
+- Talk Mode promotes the existing foreground service from `dataSync` to `dataSync|microphone` before capture starts, then demotes it when Talk Mode stops. Android 14+ requires the `FOREGROUND_SERVICE_MICROPHONE` declaration, the `RECORD_AUDIO` runtime grant, and the microphone service type at runtime.
+- By default, Android Talk uses native speech recognition, Gateway chat, and `talk.speak` through the configured gateway Talk provider. Local system TTS is used only when `talk.speak` is unavailable.
+- Android Talk uses realtime Gateway relay only when `talk.realtime.mode` is `realtime` and `talk.realtime.transport` is `gateway-relay`.
+- Voice wake remains disabled in the Android UX/runtime.
+- Additional Android command families (availability depends on device + permissions):
+  - `device.status`, `device.info`, `device.permissions`, `device.health`
+  - `notifications.list`, `notifications.actions` (see [Notification forwarding](#notification-forwarding) below)
+  - `photos.latest`
+  - `contacts.search`, `contacts.add`
+  - `calendar.events`, `calendar.add`
+  - `callLog.search`
+  - `sms.search`
+  - `motion.activity`, `motion.pedometer`
+
+## Assistant entrypoints
+
+Android supports launching Nodmix from the system assistant trigger (Google
+Assistant). When configured, holding the home button or saying "Hey Google, ask
+Nodmix..." opens the app and hands the prompt into the chat composer.
+
+This uses Android **App Actions** metadata declared in the app manifest. No
+extra configuration is needed on the gateway side -- the assistant intent is
+handled entirely by the Android app and forwarded as a normal chat message.
+
+<Note>
+App Actions availability depends on the device, Google Play Services version,
+and whether the user has set Nodmix as the default assistant app.
+</Note>
+
+## Notification forwarding
+
+Android can forward device notifications to the gateway as events. Several controls let you scope which notifications are forwarded and when.
+
+| Key                              | Type           | Description                                                                                       |
+| -------------------------------- | -------------- | ------------------------------------------------------------------------------------------------- |
+| `notifications.allowPackages`    | string[]       | Only forward notifications from these package names. If set, all other packages are ignored.      |
+| `notifications.denyPackages`     | string[]       | Never forward notifications from these package names. Applied after `allowPackages`.              |
+| `notifications.quietHours.start` | string (HH:mm) | Start of quiet hours window (local device time). Notifications are suppressed during this window. |
+| `notifications.quietHours.end`   | string (HH:mm) | End of quiet hours window.                                                                        |
+| `notifications.rateLimit`        | number         | Maximum forwarded notifications per package per minute. Excess notifications are dropped.         |
+
+The notification picker also uses safer behavior for forwarded notification events, preventing accidental forwarding of sensitive system notifications.
+
+Example configuration:
+
+```json5
+{
+  notifications: {
+    allowPackages: ["com.slack", "com.whatsapp"],
+    denyPackages: ["com.android.systemui"],
+    quietHours: {
+      start: "22:00",
+      end: "07:00",
+    },
+    rateLimit: 5,
+  },
+}
+```
+
+<Note>
+Notification forwarding requires the Android Notification Listener permission. The app prompts for this during setup.
+</Note>
+
+## Related
+
+- [iOS app](/platforms/ios)
+- [Nodes](/nodes)
+- [Android node troubleshooting](/nodes/troubleshooting)

package/docs/platforms/digitalocean.md

@@ -0,0 +1,12 @@
+---
+summary: "Redirect to /install/digitalocean"
+title: "DigitalOcean (platform)"
+redirect: /install/digitalocean
+---
+
+This page has moved to [DigitalOcean](/install/digitalocean).
+
+## Related
+
+- [Install overview](/install)
+- [VPS hosting](/vps)

package/docs/platforms/index.md

@@ -0,0 +1,60 @@
+---
+summary: "Platform support overview (Gateway + companion apps)"
+read_when:
+  - Looking for OS support or install paths
+  - Deciding where to run the Gateway
+title: "Platforms"
+---
+
+Nodmix core is written in TypeScript. **Node is the recommended runtime**.
+Bun is not recommended for the Gateway — known issues with WhatsApp and
+Telegram channels; see [Bun (experimental)](/install/bun) for details.
+
+Companion apps exist for macOS (menu bar app) and mobile nodes (iOS/Android). Windows and
+Linux companion apps are planned, but the Gateway is fully supported today.
+Native companion apps for Windows are also planned; the Gateway is recommended via WSL2.
+
+## Choose your OS
+
+- macOS: [macOS](/platforms/macos)
+- iOS: [iOS](/platforms/ios)
+- Android: [Android](/platforms/android)
+- Windows: [Windows](/platforms/windows)
+- Linux: [Linux](/platforms/linux)
+
+## VPS and hosting
+
+- VPS hub: [VPS hosting](/vps)
+- Fly.io: [Fly.io](/install/fly)
+- Hetzner (Docker): [Hetzner](/install/hetzner)
+- GCP (Compute Engine): [GCP](/install/gcp)
+- Azure (Linux VM): [Azure](/install/azure)
+- exe.dev (VM + HTTPS proxy): [exe.dev](/install/exe-dev)
+
+## Common links
+
+- Install guide: [Getting Started](/start/getting-started)
+- Gateway runbook: [Gateway](/gateway)
+- Gateway configuration: [Configuration](/gateway/configuration)
+- Service status: `nodmix gateway status`
+
+## Gateway service install (CLI)
+
+Use one of these (all supported):
+
+- Wizard (recommended): `nodmix onboard --install-daemon`
+- Direct: `nodmix gateway install`
+- Configure flow: `nodmix configure` → select **Gateway service**
+- Repair/migrate: `nodmix doctor` (offers to install or fix the service)
+
+The service target depends on OS:
+
+- macOS: LaunchAgent (`ai.nodmix.gateway` or `ai.nodmix.<profile>`; legacy `com.nodmix.*`)
+- Linux/WSL2: systemd user service (`nodmix-gateway[-<profile>].service`)
+- Native Windows: Scheduled Task (`Nodmix Gateway` or `Nodmix Gateway (<profile>)`), with a per-user Startup-folder login item fallback if task creation is denied
+
+## Related
+
+- [Install overview](/install)
+- [macOS app](/platforms/macos)
+- [iOS app](/platforms/ios)