milaidy 1.0.0

package/docs/platforms/hetzner.md

@@ -0,0 +1,330 @@
+---
+summary: "Run Milaidy Gateway 24/7 on a cheap Hetzner VPS (Docker) with durable state and baked-in binaries"
+read_when:
+  - You want Milaidy running 24/7 on a cloud VPS (not your laptop)
+  - You want a production-grade, always-on Gateway on your own VPS
+  - You want full control over persistence, binaries, and restart behavior
+  - You are running Milaidy in Docker on Hetzner or a similar provider
+title: "Hetzner"
+---
+
+# Milaidy on Hetzner (Docker, Production VPS Guide)
+
+## Goal
+
+Run a persistent Milaidy Gateway on a Hetzner VPS using Docker, with durable state, baked-in binaries, and safe restart behavior.
+
+If you want “Milaidy 24/7 for ~$5”, this is the simplest reliable setup.
+Hetzner pricing changes; pick the smallest Debian/Ubuntu VPS and scale up if you hit OOMs.
+
+## What are we doing (simple terms)?
+
+- Rent a small Linux server (Hetzner VPS)
+- Install Docker (isolated app runtime)
+- Start the Milaidy Gateway in Docker
+- Persist `~/.milaidy` + `~/.milaidy/workspace` on the host (survives restarts/rebuilds)
+- Access the Control UI from your laptop via an SSH tunnel
+
+The Gateway can be accessed via:
+
+- SSH port forwarding from your laptop
+- Direct port exposure if you manage firewalling and tokens yourself
+
+This guide assumes Ubuntu or Debian on Hetzner.  
+If you are on another Linux VPS, map packages accordingly.
+For the generic Docker flow, see [Docker](/install/docker).
+
+---
+
+## Quick path (experienced operators)
+
+1. Provision Hetzner VPS
+2. Install Docker
+3. Clone Milaidy repository
+4. Create persistent host directories
+5. Configure `.env` and `docker-compose.yml`
+6. Bake required binaries into the image
+7. `docker compose up -d`
+8. Verify persistence and Gateway access
+
+---
+
+## What you need
+
+- Hetzner VPS with root access
+- SSH access from your laptop
+- Basic comfort with SSH + copy/paste
+- ~20 minutes
+- Docker and Docker Compose
+- Model auth credentials
+- Optional provider credentials
+  - WhatsApp QR
+  - Telegram bot token
+  - Gmail OAuth
+
+---
+
+## 1) Provision the VPS
+
+Create an Ubuntu or Debian VPS in Hetzner.
+
+Connect as root:
+
+```bash
+ssh root@YOUR_VPS_IP
+```
+
+This guide assumes the VPS is stateful.
+Do not treat it as disposable infrastructure.
+
+---
+
+## 2) Install Docker (on the VPS)
+
+```bash
+apt-get update
+apt-get install -y git curl ca-certificates
+curl -fsSL https://get.docker.com | sh
+```
+
+Verify:
+
+```bash
+docker --version
+docker compose version
+```
+
+---
+
+## 3) Clone the Milaidy repository
+
+```bash
+git clone https://github.com/milaidy/milaidy.git
+cd milaidy
+```
+
+This guide assumes you will build a custom image to guarantee binary persistence.
+
+---
+
+## 4) Create persistent host directories
+
+Docker containers are ephemeral.
+All long-lived state must live on the host.
+
+```bash
+mkdir -p /root/.milaidy
+mkdir -p /root/.milaidy/workspace
+
+# Set ownership to the container user (uid 1000):
+chown -R 1000:1000 /root/.milaidy
+chown -R 1000:1000 /root/.milaidy/workspace
+```
+
+---
+
+## 5) Configure environment variables
+
+Create `.env` in the repository root.
+
+```bash
+MILAIDY_IMAGE=milaidy:latest
+MILAIDY_GATEWAY_TOKEN=change-me-now
+MILAIDY_GATEWAY_BIND=lan
+MILAIDY_GATEWAY_PORT=18789
+
+MILAIDY_CONFIG_DIR=/root/.milaidy
+MILAIDY_WORKSPACE_DIR=/root/.milaidy/workspace
+
+GOG_KEYRING_PASSWORD=change-me-now
+XDG_CONFIG_HOME=/home/node/.milaidy
+```
+
+Generate strong secrets:
+
+```bash
+openssl rand -hex 32
+```
+
+**Do not commit this file.**
+
+---
+
+## 6) Docker Compose configuration
+
+Create or update `docker-compose.yml`.
+
+```yaml
+services:
+  milaidy-gateway:
+    image: ${MILAIDY_IMAGE}
+    build: .
+    restart: unless-stopped
+    env_file:
+      - .env
+    environment:
+      - HOME=/home/node
+      - NODE_ENV=production
+      - TERM=xterm-256color
+      - MILAIDY_GATEWAY_BIND=${MILAIDY_GATEWAY_BIND}
+      - MILAIDY_GATEWAY_PORT=${MILAIDY_GATEWAY_PORT}
+      - MILAIDY_GATEWAY_TOKEN=${MILAIDY_GATEWAY_TOKEN}
+      - GOG_KEYRING_PASSWORD=${GOG_KEYRING_PASSWORD}
+      - XDG_CONFIG_HOME=${XDG_CONFIG_HOME}
+      - PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+    volumes:
+      - ${MILAIDY_CONFIG_DIR}:/home/node/.milaidy
+      - ${MILAIDY_WORKSPACE_DIR}:/home/node/.milaidy/workspace
+    ports:
+      # Recommended: keep the Gateway loopback-only on the VPS; access via SSH tunnel.
+      # To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly.
+      - "127.0.0.1:${MILAIDY_GATEWAY_PORT}:18789"
+
+      # Optional: only if you run iOS/Android nodes against this VPS and need Canvas host.
+      # If you expose this publicly, read /gateway/security and firewall accordingly.
+      # - "18793:18793"
+    command:
+      [
+        "node",
+        "dist/index.js",
+        "gateway",
+        "--bind",
+        "${MILAIDY_GATEWAY_BIND}",
+        "--port",
+        "${MILAIDY_GATEWAY_PORT}",
+      ]
+```
+
+---
+
+## 7) Bake required binaries into the image (critical)
+
+Installing binaries inside a running container is a trap.
+Anything installed at runtime will be lost on restart.
+
+All external binaries required by skills must be installed at image build time.
+
+The examples below show three common binaries only:
+
+- `gog` for Gmail access
+- `goplaces` for Google Places
+- `wacli` for WhatsApp
+
+These are examples, not a complete list.
+You may install as many binaries as needed using the same pattern.
+
+If you add new skills later that depend on additional binaries, you must:
+
+1. Update the Dockerfile
+2. Rebuild the image
+3. Restart the containers
+
+**Example Dockerfile**
+
+```dockerfile
+FROM node:22-bookworm
+
+RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*
+
+# Example binary 1: Gmail CLI
+RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
+  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog
+
+# Example binary 2: Google Places CLI
+RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \
+  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces
+
+# Example binary 3: WhatsApp CLI
+RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
+  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli
+
+# Add more binaries below using the same pattern
+
+WORKDIR /app
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
+COPY ui/package.json ./ui/package.json
+COPY scripts ./scripts
+
+RUN corepack enable
+RUN pnpm install --frozen-lockfile
+
+COPY . .
+RUN pnpm build
+RUN pnpm ui:install
+RUN pnpm ui:build
+
+ENV NODE_ENV=production
+
+CMD ["node","dist/index.js"]
+```
+
+---
+
+## 8) Build and launch
+
+```bash
+docker compose build
+docker compose up -d milaidy-gateway
+```
+
+Verify binaries:
+
+```bash
+docker compose exec milaidy-gateway which gog
+docker compose exec milaidy-gateway which goplaces
+docker compose exec milaidy-gateway which wacli
+```
+
+Expected output:
+
+```
+/usr/local/bin/gog
+/usr/local/bin/goplaces
+/usr/local/bin/wacli
+```
+
+---
+
+## 9) Verify Gateway
+
+```bash
+docker compose logs -f milaidy-gateway
+```
+
+Success:
+
+```
+[gateway] listening on ws://0.0.0.0:18789
+```
+
+From your laptop:
+
+```bash
+ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP
+```
+
+Open:
+
+`http://127.0.0.1:18789/`
+
+Paste your gateway token.
+
+---
+
+## What persists where (source of truth)
+
+Milaidy runs in Docker, but Docker is not the source of truth.
+All long-lived state must survive restarts, rebuilds, and reboots.
+
+| Component           | Location                          | Persistence mechanism  | Notes                            |
+| ------------------- | --------------------------------- | ---------------------- | -------------------------------- |
+| Gateway config      | `/home/node/.milaidy/`           | Host volume mount      | Includes `milaidy.json`, tokens |
+| Model auth profiles | `/home/node/.milaidy/`           | Host volume mount      | OAuth tokens, API keys           |
+| Skill configs       | `/home/node/.milaidy/skills/`    | Host volume mount      | Skill-level state                |
+| Agent workspace     | `/home/node/.milaidy/workspace/` | Host volume mount      | Code and agent artifacts         |
+| WhatsApp session    | `/home/node/.milaidy/`           | Host volume mount      | Preserves QR login               |
+| Gmail keyring       | `/home/node/.milaidy/`           | Host volume + password | Requires `GOG_KEYRING_PASSWORD`  |
+| External binaries   | `/usr/local/bin/`                 | Docker image           | Must be baked at build time      |
+| Node runtime        | Container filesystem              | Docker image           | Rebuilt every image build        |
+| OS packages         | Container filesystem              | Docker image           | Do not install at runtime        |
+| Docker container    | Ephemeral                         | Restartable            | Safe to destroy                  |

package/docs/platforms/index.md

@@ -0,0 +1,53 @@
+---
+summary: "Platform support overview (Gateway + companion apps)"
+read_when:
+  - Looking for OS support or install paths
+  - Deciding where to run the Gateway
+title: "Platforms"
+---
+
+# Platforms
+
+Milaidy core is written in TypeScript. **Node is the recommended runtime**.
+Bun is not recommended for the Gateway (WhatsApp/Telegram bugs).
+
+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 & hosting
+
+- VPS hub: [VPS hosting](/vps)
+- Fly.io: [Fly.io](/platforms/fly)
+- Hetzner (Docker): [Hetzner](/platforms/hetzner)
+- GCP (Compute Engine): [GCP](/platforms/gcp)
+- exe.dev (VM + HTTPS proxy): [exe.dev](/platforms/exe-dev)
+
+## Common links
+
+- Install guide: [Getting Started](/start/getting-started)
+- Gateway runbook: [Gateway](/gateway)
+- Gateway configuration: [Configuration](/gateway/configuration)
+- Service status: `milaidy gateway status`
+
+## Gateway service install (CLI)
+
+Use one of these (all supported):
+
+- Wizard (recommended): `milaidy onboard --install-daemon`
+- Direct: `milaidy gateway install`
+- Configure flow: `milaidy configure` → select **Gateway service**
+- Repair/migrate: `milaidy doctor` (offers to install or fix the service)
+
+The service target depends on OS:
+
+- macOS: LaunchAgent (`bot.molt.gateway` or `bot.molt.<profile>`; legacy `com.milaidy.*`)
+- Linux/WSL2: systemd user service (`milaidy-gateway[-<profile>].service`)

package/docs/platforms/ios.md

@@ -0,0 +1,106 @@
+---
+summary: "iOS node app: connect to the Gateway, pairing, canvas, and troubleshooting"
+read_when:
+  - Pairing or reconnecting the iOS node
+  - Running the iOS app from source
+  - Debugging gateway discovery or canvas commands
+title: "iOS App"
+---
+
+# iOS App (Node)
+
+Availability: internal preview. The iOS app is not publicly distributed yet.
+
+## What it does
+
+- Connects to a Gateway over WebSocket (LAN or tailnet).
+- Exposes node capabilities: Canvas, Screen snapshot, Camera capture, Location, Talk mode, Voice wake.
+- Receives `node.invoke` commands and reports node status events.
+
+## Requirements
+
+- Gateway running on another device (macOS, Linux, or Windows via WSL2).
+- Network path:
+  - Same LAN via Bonjour, **or**
+  - Tailnet via unicast DNS-SD (example domain: `milaidy.internal.`), **or**
+  - Manual host/port (fallback).
+
+## Quick start (pair + connect)
+
+1. Start the Gateway:
+
+```bash
+milaidy gateway --port 18789
+```
+
+2. In the iOS app, open Settings and pick a discovered gateway (or enable Manual Host and enter host/port).
+
+3. Approve the pairing request on the gateway host:
+
+```bash
+milaidy nodes pending
+milaidy nodes approve <requestId>
+```
+
+4. Verify connection:
+
+```bash
+milaidy nodes status
+milaidy gateway call node.list --params "{}"
+```
+
+## Discovery paths
+
+### Bonjour (LAN)
+
+The Gateway advertises `_milaidy-gw._tcp` on `local.`. The iOS app lists these automatically.
+
+### Tailnet (cross-network)
+
+If mDNS is blocked, use a unicast DNS-SD zone (choose a domain; example: `milaidy.internal.`) and Tailscale split DNS.
+See [Bonjour](/gateway/bonjour) for the CoreDNS example.
+
+### Manual host/port
+
+In Settings, enable **Manual Host** and enter the gateway host + port (default `18789`).
+
+## Canvas + A2UI
+
+The iOS node renders a WKWebView canvas. Use `node.invoke` to drive it:
+
+```bash
+milaidy nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-host>:18793/__milaidy__/canvas/"}'
+```
+
+Notes:
+
+- The Gateway canvas host serves `/__milaidy__/canvas/` and `/__milaidy__/a2ui/`.
+- The iOS node auto-navigates to A2UI on connect when a canvas host URL is advertised.
+- Return to the built-in scaffold with `canvas.navigate` and `{"url":""}`.
+
+### Canvas eval / snapshot
+
+```bash
+milaidy nodes invoke --node "iOS Node" --command canvas.eval --params '{"javaScript":"(() => { const {ctx} = window.__milaidy; ctx.clearRect(0,0,innerWidth,innerHeight); ctx.lineWidth=6; ctx.strokeStyle=\"#ff2d55\"; ctx.beginPath(); ctx.moveTo(40,40); ctx.lineTo(innerWidth-40, innerHeight-40); ctx.stroke(); return \"ok\"; })()"}'
+```
+
+```bash
+milaidy nodes invoke --node "iOS Node" --command canvas.snapshot --params '{"maxWidth":900,"format":"jpeg"}'
+```
+
+## Voice wake + talk mode
+
+- Voice wake and talk mode are available in Settings.
+- iOS may suspend background audio; treat voice features as best-effort when the app is not active.
+
+## Common errors
+
+- `NODE_BACKGROUND_UNAVAILABLE`: bring the iOS app to the foreground (canvas/camera/screen commands require it).
+- Pairing prompt never appears: run `milaidy nodes pending` and approve manually.
+- Reconnect fails after reinstall: the Keychain pairing token was cleared; re-pair the node.
+
+## Related docs
+
+- [Pairing](/gateway/pairing)
+- [Discovery](/gateway/discovery)
+- [Bonjour](/gateway/bonjour)

package/docs/platforms/linux.md

@@ -0,0 +1,94 @@
+---
+summary: "Linux support + companion app status"
+read_when:
+  - Looking for Linux companion app status
+  - Planning platform coverage or contributions
+title: "Linux App"
+---
+
+# Linux App
+
+The Gateway is fully supported on Linux. **Node is the recommended runtime**.
+Bun is not recommended for the Gateway (WhatsApp/Telegram bugs).
+
+Native Linux companion apps are planned. Contributions are welcome if you want to help build one.
+
+## Beginner quick path (VPS)
+
+1. Install Node 22+
+2. `npm i -g milaidy@latest`
+3. `milaidy onboard --install-daemon`
+4. From your laptop: `ssh -N -L 18789:127.0.0.1:18789 <user>@<host>`
+5. Open `http://127.0.0.1:18789/` and paste your token
+
+Step-by-step VPS guide: [exe.dev](/platforms/exe-dev)
+
+## Install
+
+- [Getting Started](/start/getting-started)
+- [Install & updates](/install/updating)
+- Optional flows: [Bun (experimental)](/install/bun), [Nix](/install/nix), [Docker](/install/docker)
+
+## Gateway
+
+- [Gateway runbook](/gateway)
+- [Configuration](/gateway/configuration)
+
+## Gateway service install (CLI)
+
+Use one of these:
+
+```
+milaidy onboard --install-daemon
+```
+
+Or:
+
+```
+milaidy gateway install
+```
+
+Or:
+
+```
+milaidy configure
+```
+
+Select **Gateway service** when prompted.
+
+Repair/migrate:
+
+```
+milaidy doctor
+```
+
+## System control (systemd user unit)
+
+Milaidy installs a systemd **user** service by default. Use a **system**
+service for shared or always-on servers. The full unit example and guidance
+live in the [Gateway runbook](/gateway).
+
+Minimal setup:
+
+Create `~/.config/systemd/user/milaidy-gateway[-<profile>].service`:
+
+```
+[Unit]
+Description=Milaidy Gateway (profile: <profile>, v<version>)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+ExecStart=/usr/local/bin/milaidy gateway --port 18789
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+```
+
+Enable it:
+
+```
+systemctl --user enable --now milaidy-gateway[-<profile>].service
+```

package/docs/platforms/mac/bundled-gateway.md

@@ -0,0 +1,73 @@
+---
+summary: "Gateway runtime on macOS (external launchd service)"
+read_when:
+  - Packaging Milaidy.app
+  - Debugging the macOS gateway launchd service
+  - Installing the gateway CLI for macOS
+title: "Gateway on macOS"
+---
+
+# Gateway on macOS (external launchd)
+
+Milaidy.app no longer bundles Node/Bun or the Gateway runtime. The macOS app
+expects an **external** `milaidy` CLI install, does not spawn the Gateway as a
+child process, and manages a per‑user launchd service to keep the Gateway
+running (or attaches to an existing local Gateway if one is already running).
+
+## Install the CLI (required for local mode)
+
+You need Node 22+ on the Mac, then install `milaidy` globally:
+
+```bash
+npm install -g milaidy@<version>
+```
+
+The macOS app’s **Install CLI** button runs the same flow via npm/pnpm (bun not recommended for Gateway runtime).
+
+## Launchd (Gateway as LaunchAgent)
+
+Label:
+
+- `bot.molt.gateway` (or `bot.molt.<profile>`; legacy `com.milaidy.*` may remain)
+
+Plist location (per‑user):
+
+- `~/Library/LaunchAgents/bot.molt.gateway.plist`
+  (or `~/Library/LaunchAgents/bot.molt.<profile>.plist`)
+
+Manager:
+
+- The macOS app owns LaunchAgent install/update in Local mode.
+- The CLI can also install it: `milaidy gateway install`.
+
+Behavior:
+
+- “Milaidy Active” enables/disables the LaunchAgent.
+- App quit does **not** stop the gateway (launchd keeps it alive).
+- If a Gateway is already running on the configured port, the app attaches to
+  it instead of starting a new one.
+
+Logging:
+
+- launchd stdout/err: `/tmp/milaidy/milaidy-gateway.log`
+
+## Version compatibility
+
+The macOS app checks the gateway version against its own version. If they’re
+incompatible, update the global CLI to match the app version.
+
+## Smoke check
+
+```bash
+milaidy --version
+
+MILAIDY_SKIP_CHANNELS=1 \
+MILAIDY_SKIP_CANVAS_HOST=1 \
+milaidy gateway --port 18999 --bind loopback
+```
+
+Then:
+
+```bash
+milaidy gateway call health --url ws://127.0.0.1:18999 --timeout 3000
+```