milaidy 1.0.0

package/docs/render.mdx

@@ -0,0 +1,165 @@
+---
+title: Deploy on Render
+---
+
+Deploy Milaidy on Render using Infrastructure as Code. The included `render.yaml` Blueprint defines your entire stack declaratively, service, disk, environment variables, so you can deploy with a single click and version your infrastructure alongside your code.
+
+## Prerequisites
+
+- A [Render account](https://render.com) (free tier available)
+- An API key from your preferred [model provider](/providers)
+
+## Deploy with a Render Blueprint
+
+<a
+  href="https://render.com/deploy?repo=https://github.com/milaidy/milaidy"
+  target="_blank"
+  rel="noreferrer"
+>
+  Deploy to Render
+</a>
+
+Clicking this link will:
+
+1. Create a new Render service from the `render.yaml` Blueprint at the root of this repo.
+2. Prompt you to set `SETUP_PASSWORD`
+3. Build the Docker image and deploy
+
+Once deployed, your service URL follows the pattern `https://<service-name>.onrender.com`.
+
+## Understanding the Blueprint
+
+Render Blueprints are YAML files that define your infrastructure. The `render.yaml` in this
+repository configures everything needed to run Milaidy:
+
+```yaml
+services:
+  - type: web
+    name: milaidy
+    runtime: docker
+    plan: starter
+    healthCheckPath: /health
+    envVars:
+      - key: PORT
+        value: "8080"
+      - key: SETUP_PASSWORD
+        sync: false # prompts during deploy
+      - key: MILAIDY_STATE_DIR
+        value: /data/.milaidy
+      - key: MILAIDY_WORKSPACE_DIR
+        value: /data/workspace
+      - key: MILAIDY_GATEWAY_TOKEN
+        generateValue: true # auto-generates a secure token
+    disk:
+      name: milaidy-data
+      mountPath: /data
+      sizeGB: 1
+```
+
+Key Blueprint features used:
+
+| Feature               | Purpose                                                    |
+| --------------------- | ---------------------------------------------------------- |
+| `runtime: docker`     | Builds from the repo's Dockerfile                          |
+| `healthCheckPath`     | Render monitors `/health` and restarts unhealthy instances |
+| `sync: false`         | Prompts for value during deploy (secrets)                  |
+| `generateValue: true` | Auto-generates a cryptographically secure value            |
+| `disk`                | Persistent storage that survives redeploys                 |
+
+## Choosing a plan
+
+| Plan      | Spin-down         | Disk          | Best for                      |
+| --------- | ----------------- | ------------- | ----------------------------- |
+| Free      | After 15 min idle | Not available | Testing, demos                |
+| Starter   | Never             | 1GB+          | Personal use, small teams     |
+| Standard+ | Never             | 1GB+          | Production, multiple channels |
+
+The Blueprint defaults to `starter`. To use free tier, change `plan: free` in your fork's
+`render.yaml` (but note: no persistent disk means config resets on each deploy).
+
+## After deployment
+
+### Complete the setup wizard
+
+1. Navigate to `https://<your-service>.onrender.com/setup`
+2. Enter your `SETUP_PASSWORD`
+3. Select a model provider and paste your API key
+4. Optionally configure messaging channels (Telegram, Discord, Slack)
+5. Click **Run setup**
+
+### Access the Control UI
+
+The web dashboard is available at `https://<your-service>.onrender.com/milaidy`.
+
+## Render Dashboard features
+
+### Logs
+
+View real-time logs in **Dashboard → your service → Logs**. Filter by:
+
+- Build logs (Docker image creation)
+- Deploy logs (service startup)
+- Runtime logs (application output)
+
+### Shell access
+
+For debugging, open a shell session via **Dashboard → your service → Shell**. The persistent disk is mounted at `/data`.
+
+### Environment variables
+
+Modify variables in **Dashboard → your service → Environment**. Changes trigger an automatic redeploy.
+
+### Auto-deploy
+
+If you use the original Milaidy repository, Render will not auto-deploy your Milaidy. To update it, run a manual Blueprint sync from the dashboard.
+
+## Custom domain
+
+1. Go to **Dashboard → your service → Settings → Custom Domains**
+2. Add your domain
+3. Configure DNS as instructed (CNAME to `*.onrender.com`)
+4. Render provisions a TLS certificate automatically
+
+## Scaling
+
+Render supports horizontal and vertical scaling:
+
+- **Vertical**: Change the plan to get more CPU/RAM
+- **Horizontal**: Increase instance count (Standard plan and above)
+
+For Milaidy, vertical scaling is usually sufficient. Horizontal scaling requires sticky sessions or external state management.
+
+## Backups and migration
+
+Export your configuration and workspace at any time:
+
+```
+https://<your-service>.onrender.com/setup/export
+```
+
+This downloads a portable backup you can restore on any Milaidy host.
+
+## Troubleshooting
+
+### Service won't start
+
+Check the deploy logs in the Render Dashboard. Common issues:
+
+- Missing `SETUP_PASSWORD` — the Blueprint prompts for this, but verify it's set
+- Port mismatch — ensure `PORT=8080` matches the Dockerfile's exposed port
+
+### Slow cold starts (free tier)
+
+Free tier services spin down after 15 minutes of inactivity. The first request after spin-down takes a few seconds while the container starts. Upgrade to Starter plan for always-on.
+
+### Data loss after redeploy
+
+This happens on free tier (no persistent disk). Upgrade to a paid plan, or
+regularly export your config via `/setup/export`.
+
+### Health check failures
+
+Render expects a 200 response from `/health` within 30 seconds. If builds succeed but deploys fail, the service may be taking too long to start. Check:
+
+- Build logs for errors
+- Whether the container runs locally with `docker build && docker run`

package/docs/start/docs-directory.md

@@ -0,0 +1,63 @@
+---
+summary: "Curated links to the most used Milaidy docs."
+read_when:
+  - You want quick access to key docs pages
+title: "Docs directory"
+---
+
+<Note>
+For a complete map of the docs, see [Docs hubs](/start/hubs).
+</Note>
+
+## Start here
+
+- [Docs hubs (all pages linked)](/start/hubs)
+- [Help](/help)
+- [Configuration](/gateway/configuration)
+- [Configuration examples](/gateway/configuration-examples)
+- [Slash commands](/tools/slash-commands)
+- [Multi-agent routing](/concepts/multi-agent)
+- [Updating and rollback](/install/updating)
+- [Pairing (DM and nodes)](/start/pairing)
+- [Nix mode](/install/nix)
+- [Milaidy assistant setup](/start/milaidy)
+- [Skills](/tools/skills)
+- [Skills config](/tools/skills-config)
+- [Workspace templates](/reference/templates/AGENTS)
+- [RPC adapters](/reference/rpc)
+- [Gateway runbook](/gateway)
+- [Nodes (iOS and Android)](/nodes)
+- [Web surfaces (Control UI)](/web)
+- [Discovery and transports](/gateway/discovery)
+- [Remote access](/gateway/remote)
+
+## Providers and UX
+
+- [WebChat](/web/webchat)
+- [Control UI (browser)](/web/control-ui)
+- [Telegram](/channels/telegram)
+- [Discord](/channels/discord)
+- [Mattermost (plugin)](/channels/mattermost)
+- [BlueBubbles (iMessage)](/channels/bluebubbles)
+- [iMessage (legacy)](/channels/imessage)
+- [Groups](/concepts/groups)
+- [WhatsApp group messages](/concepts/group-messages)
+- [Media images](/nodes/images)
+- [Media audio](/nodes/audio)
+
+## Companion apps
+
+- [macOS app](/platforms/macos)
+- [iOS app](/platforms/ios)
+- [Android app](/platforms/android)
+- [Windows (WSL2)](/platforms/windows)
+- [Linux app](/platforms/linux)
+
+## Operations and safety
+
+- [Sessions](/concepts/session)
+- [Cron jobs](/automation/cron-jobs)
+- [Webhooks](/automation/webhook)
+- [Gmail hooks (Pub/Sub)](/automation/gmail-pubsub)
+- [Security](/gateway/security)
+- [Troubleshooting](/gateway/troubleshooting)

package/docs/start/getting-started.md

@@ -0,0 +1,212 @@
+---
+summary: "Beginner guide: from zero to first message (wizard, auth, channels, pairing)"
+read_when:
+  - First time setup from zero
+  - You want the fastest path from install → onboarding → first message
+title: "Getting Started"
+---
+
+# Getting Started
+
+Goal: go from **zero** → **first working chat** (with sane defaults) as quickly as possible.
+
+Fastest chat: open the Control UI (no channel setup needed). Run `milaidy dashboard`
+and chat in the browser, or open `http://127.0.0.1:18789/` on the gateway host.
+Docs: [Dashboard](/web/dashboard) and [Control UI](/web/control-ui).
+
+Recommended path: use the **CLI onboarding wizard** (`milaidy onboard`). It sets up:
+
+- model/auth (OAuth recommended)
+- gateway settings
+- channels (WhatsApp/Telegram/Discord/Mattermost (plugin)/...)
+- pairing defaults (secure DMs)
+- workspace bootstrap + skills
+- optional background service
+
+If you want the deeper reference pages, jump to: [Wizard](/start/wizard), [Setup](/start/setup), [Pairing](/start/pairing), [Security](/gateway/security).
+
+Sandboxing note: `agents.defaults.sandbox.mode: "non-main"` uses `session.mainKey` (default `"main"`),
+so group/channel sessions are sandboxed. If you want the main agent to always
+run on host, set an explicit per-agent override in `agents.list`:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "sandbox": { "mode": "non-main" }
+    },
+    "list": [
+      {
+        "id": "main",
+        "workspace": "~/.milaidy/workspace",
+        "sandbox": { "mode": "off" }
+      }
+    ]
+  }
+}
+```
+
+## 0) Prereqs
+
+- Node `>=22`
+- `pnpm` (optional; recommended if you build from source)
+- **Recommended:** Brave Search API key for web search. Easiest path:
+  `milaidy configure --section web` (stores `tools.web.search.apiKey`).
+  See [Web tools](/tools/web).
+
+macOS: if you plan to build the apps, install Xcode / CLT. For the CLI + gateway only, Node is enough.
+Windows: use **WSL2** (Ubuntu recommended). WSL2 is strongly recommended; native Windows is untested, more problematic, and has poorer tool compatibility. Install WSL2 first, then run the Linux steps inside WSL. See [Windows (WSL2)](/platforms/windows).
+
+## 1) Install the CLI (recommended)
+
+```bash
+curl -fsSL https://milaidy.ai/install.sh | bash
+```
+
+Installer options (install method, non-interactive, from GitHub): [Install](/install).
+
+Windows (PowerShell):
+
+```powershell
+iwr -useb https://milaidy.ai/install.ps1 | iex
+```
+
+Alternative (global install):
+
+```bash
+npm install -g milaidy@latest
+```
+
+```bash
+pnpm add -g milaidy@latest
+```
+
+## 2) Run the onboarding wizard (and install the service)
+
+```bash
+milaidy onboard --install-daemon
+```
+
+What you’ll choose:
+
+- **Local vs Remote** gateway
+- **Auth**: Anthropic API key (recommended), OpenAI Codex OAuth, or other provider API keys. `claude setup-token` is also supported for Anthropic.
+- **Providers**: WhatsApp QR login, Telegram/Discord bot tokens, Mattermost plugin tokens, etc.
+- **Daemon**: background install (launchd/systemd; WSL2 uses systemd)
+  - **Runtime**: Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**.
+- **Gateway token**: the wizard generates one by default (even on loopback) and stores it in `gateway.auth.token`.
+
+Wizard doc: [Wizard](/start/wizard)
+
+### Auth: where it lives (important)
+
+- **Recommended Anthropic path:** set an API key (wizard can store it for service use). `claude setup-token` is also supported if you want to reuse Claude Code credentials.
+
+- OAuth credentials (legacy import): `~/.milaidy/credentials/oauth.json`
+- Auth profiles (OAuth + API keys): `~/.milaidy/agents/<agentId>/agent/auth-profiles.json`
+
+Headless/server tip: do OAuth on a normal machine first, then copy `oauth.json` to the gateway host.
+
+## 3) Start the Gateway
+
+If you installed the service during onboarding, the Gateway should already be running:
+
+```bash
+milaidy gateway status
+```
+
+Manual run (foreground):
+
+```bash
+milaidy gateway --port 18789 --verbose
+```
+
+Dashboard (local loopback): `http://127.0.0.1:18789/`
+If a token is configured, paste it into the Control UI settings (stored as `connect.params.auth.token`).
+
+⚠️ **Bun warning (WhatsApp + Telegram):** Bun has known issues with these
+channels. If you use WhatsApp or Telegram, run the Gateway with **Node**.
+
+## 3.5) Quick verify (2 min)
+
+```bash
+milaidy status
+milaidy health
+milaidy security audit --deep
+```
+
+## 4) Pair + connect your first chat surface
+
+### WhatsApp (QR login)
+
+```bash
+milaidy channels login
+```
+
+Scan via WhatsApp → Settings → Linked Devices.
+
+WhatsApp doc: [WhatsApp](/channels/whatsapp)
+
+### Telegram / Discord / others
+
+The wizard can write tokens/config for you. If you prefer manual config, start with:
+
+- Telegram: [Telegram](/channels/telegram)
+- Discord: [Discord](/channels/discord)
+- Mattermost (plugin): [Mattermost](/channels/mattermost)
+
+**Telegram DM tip:** your first DM returns a pairing code. Approve it (see next step) or the bot won’t respond.
+
+## 5) DM safety (pairing approvals)
+
+Default posture: unknown DMs get a short code and messages are not processed until approved.
+If your first DM gets no reply, approve the pairing:
+
+```bash
+milaidy pairing list whatsapp
+milaidy pairing approve whatsapp <code>
+```
+
+Pairing doc: [Pairing](/start/pairing)
+
+## From source (development)
+
+If you’re hacking on Milaidy itself, run from source:
+
+```bash
+git clone https://github.com/milaidy/milaidy.git
+cd milaidy
+pnpm install
+pnpm ui:build # auto-installs UI deps on first run
+pnpm build
+milaidy onboard --install-daemon
+```
+
+If you don’t have a global install yet, run the onboarding step via `pnpm milaidy ...` from the repo.
+`pnpm build` also bundles UI assets; if you need to build just the UI, use `pnpm ui:build`.
+
+Gateway (from this repo):
+
+```bash
+node milaidy.mjs gateway --port 18789 --verbose
+```
+
+## 6) Verify end-to-end
+
+In a new terminal, send a test message:
+
+```bash
+milaidy message send --target +15555550123 --message "Hello from Milaidy"
+```
+
+If `milaidy health` shows “no auth configured”, go back to the wizard and set OAuth/key auth — the agent won’t be able to respond without it.
+
+Tip: `milaidy status --all` is the best pasteable, read-only debug report.
+Health probes: `milaidy health` (or `milaidy status --deep`) asks the running gateway for a health snapshot.
+
+## Next steps (optional, but great)
+
+- macOS menu bar app + voice wake: [macOS app](/platforms/macos)
+- iOS/Android nodes (Canvas/camera/voice): [Nodes](/nodes)
+- Remote access (SSH tunnel / Tailscale Serve): [Remote access](/gateway/remote) and [Tailscale](/gateway/tailscale)
+- Always-on / VPN setups: [Remote access](/gateway/remote), [exe.dev](/platforms/exe-dev), [Hetzner](/platforms/hetzner), [macOS remote](/platforms/mac/remote)

package/docs/start/milaidy.md

@@ -0,0 +1,247 @@
+---
+summary: "End-to-end guide for running Milaidy as a personal assistant with safety cautions"
+read_when:
+  - Onboarding a new assistant instance
+  - Reviewing safety/permission implications
+title: "Personal Assistant Setup"
+---
+
+# Building a personal assistant with Milaidy
+
+Milaidy is a WhatsApp + Telegram + Discord + iMessage gateway for **ElizaOS** agents. Plugins add Mattermost, Slack, Signal, and more. This guide is the "personal assistant" setup: one dedicated WhatsApp number that behaves like your always-on agent.
+
+## ⚠️ Safety first
+
+You’re putting an agent in a position to:
+
+- run commands on your machine (depending on your tool setup)
+- read/write files in your workspace
+- send messages back out via WhatsApp/Telegram/Discord/Mattermost (plugin)
+
+Start conservative:
+
+- Always set `channels.whatsapp.allowFrom` (never run open-to-the-world on your personal Mac).
+- Use a dedicated WhatsApp number for the assistant.
+- Heartbeats now default to every 30 minutes. Disable until you trust the setup by setting `agents.defaults.heartbeat.every: "0m"`.
+
+## Prerequisites
+
+- Node **22+**
+- Milaidy available on PATH (recommended: global install)
+- A second phone number (SIM/eSIM/prepaid) for the assistant
+
+```bash
+npm install -g milaidy@latest
+# or: pnpm add -g milaidy@latest
+```
+
+From source (development):
+
+```bash
+git clone https://github.com/milaidy/milaidy.git
+cd milaidy
+pnpm install
+pnpm ui:build # auto-installs UI deps on first run
+pnpm build
+pnpm link --global
+```
+
+## The two-phone setup (recommended)
+
+You want this:
+
+```
+Your Phone (personal)          Second Phone (assistant)
+┌─────────────────┐           ┌─────────────────┐
+│  Your WhatsApp  │  ──────▶  │  Assistant WA   │
+│  +1-555-YOU     │  message  │  +1-555-ASSIST  │
+└─────────────────┘           └────────┬────────┘
+                                       │ linked via QR
+                                       ▼
+                              ┌─────────────────┐
+                              │  Your Mac       │
+                              │  (milaidy)      │
+                              │  ElizaOS agent  │
+                              └─────────────────┘
+```
+
+If you link your personal WhatsApp to Milaidy, every message to you becomes “agent input”. That’s rarely what you want.
+
+## 5-minute quick start
+
+1. Pair WhatsApp Web (shows QR; scan with the assistant phone):
+
+```bash
+milaidy channels login
+```
+
+2. Start the Gateway (leave it running):
+
+```bash
+milaidy gateway --port 18789
+```
+
+3. Put a minimal config in `~/.milaidy/milaidy.json`:
+
+```json5
+{
+  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
+}
+```
+
+Now message the assistant number from your allowlisted phone.
+
+When onboarding finishes, we auto-open the dashboard with your gateway token and print the tokenized link. To reopen later: `milaidy dashboard`.
+
+## Give the agent a workspace (AGENTS)
+
+Milaidy reads operating instructions and “memory” from its workspace directory.
+
+By default, Milaidy uses `~/.milaidy/workspace` as the agent workspace, and will create it (plus starter `AGENTS.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `MEMORY.md`) automatically on setup/first agent run. `BOOTSTRAP.md` is only created when the workspace is brand new (it should not come back after you delete it).
+
+Tip: treat this folder like Milaidy’s “memory” and make it a git repo (ideally private) so your `AGENTS.md` + memory files are backed up. If git is installed, brand-new workspaces are auto-initialized.
+
+```bash
+milaidy setup
+```
+
+Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace)
+Memory workflow: [Memory](/concepts/memory)
+
+Optional: choose a different workspace with `agents.defaults.workspace` (supports `~`).
+
+```json5
+{
+  agents: {
+    defaults: {
+      workspace: "~/.milaidy/workspace",
+    },
+  },
+}
+```
+
+If you already ship your own workspace files from a repo, you can disable bootstrap file creation entirely:
+
+```json5
+{
+  agents: {
+    defaults: {
+      skipBootstrap: true,
+    },
+  },
+}
+```
+
+## The config that turns it into “an assistant”
+
+Milaidy defaults to a good assistant setup, but you’ll usually want to tune:
+
+- persona/instructions in the Eliza character file (`character.json`)
+- thinking defaults (if desired)
+- heartbeats (once you trust it)
+
+Example:
+
+```json5
+{
+  logging: { level: "info" },
+  agents: {
+    defaults: {
+      model: { primary: "anthropic/claude-opus-4-5" },
+      workspace: "~/.milaidy/workspace",
+      thinkingDefault: "high",
+      timeoutSeconds: 1800,
+      // Start with 0; enable later.
+      heartbeat: { every: "0m" },
+      groupChat: {
+        mentionPatterns: ["@milaidy", "milaidy"],
+      },
+    },
+  },
+  channels: {
+    whatsapp: {
+      allowFrom: ["+15555550123"],
+      groups: {
+        "*": { requireMention: true },
+      },
+    },
+  },
+  session: {
+    scope: "per-sender",
+    resetTriggers: ["/new", "/reset"],
+    reset: {
+      mode: "daily",
+      atHour: 4,
+      idleMinutes: 10080,
+    },
+  },
+}
+```
+
+## Sessions and memory
+
+- Session files: `~/.milaidy/agents/<agentId>/sessions/{{SessionId}}.jsonl`
+- Session metadata (token usage, last route, etc): `~/.milaidy/agents/<agentId>/sessions/sessions.json` (legacy: `~/.milaidy/sessions/sessions.json`)
+- `/new` or `/reset` starts a fresh session for that chat (configurable via `resetTriggers`). If sent alone, the agent replies with a short hello to confirm the reset.
+- `/compact [instructions]` compacts the session context and reports the remaining context budget.
+
+## Heartbeats (proactive mode)
+
+By default, Milaidy runs a heartbeat every 30 minutes with the prompt:
+`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`
+Set `agents.defaults.heartbeat.every: "0m"` to disable.
+
+- If `HEARTBEAT.md` exists but is effectively empty (only blank lines and markdown headers like `# Heading`), Milaidy skips the heartbeat run to save API calls.
+- If the file is missing, the heartbeat still runs and the model decides what to do.
+- If the agent replies with `HEARTBEAT_OK` (optionally with short padding; see `agents.defaults.heartbeat.ackMaxChars`), Milaidy suppresses outbound delivery for that heartbeat.
+- Heartbeats run full agent turns — shorter intervals burn more tokens.
+
+```json5
+{
+  agents: {
+    defaults: {
+      heartbeat: { every: "30m" },
+    },
+  },
+}
+```
+
+## Media in and out
+
+Inbound attachments (images/audio/docs) can be surfaced to your command via templates:
+
+- `{{MediaPath}}` (local temp file path)
+- `{{MediaUrl}}` (pseudo-URL)
+- `{{Transcript}}` (if audio transcription is enabled)
+
+Outbound attachments from the agent: include `MEDIA:<path-or-url>` on its own line (no spaces). Example:
+
+```
+Here’s the screenshot.
+MEDIA:https://example.com/screenshot.png
+```
+
+Milaidy extracts these and sends them as media alongside the text.
+
+## Operations checklist
+
+```bash
+milaidy status          # local status (creds, sessions, queued events)
+milaidy status --all    # full diagnosis (read-only, pasteable)
+milaidy status --deep   # adds gateway health probes (Telegram + Discord)
+milaidy health --json   # gateway health snapshot (WS)
+```
+
+Logs live under `/tmp/milaidy/` (default: `milaidy-YYYY-MM-DD.log`).
+
+## Next steps
+
+- WebChat: [WebChat](/web/webchat)
+- Gateway ops: [Gateway runbook](/gateway)
+- Cron + wakeups: [Cron jobs](/automation/cron-jobs)
+- macOS menu bar companion: [Milaidy macOS app](/platforms/macos)
+- iOS node app: [iOS app](/platforms/ios)
+- Android node app: [Android app](/platforms/android)
+- Windows status: [Windows (WSL2)](/platforms/windows)
+- Linux status: [Linux app](/platforms/linux)
+- Security: [Security](/gateway/security)