milaidy 1.0.0

package/docs/tools/subagents.md

@@ -0,0 +1,151 @@
+---
+summary: "Sub-agents: spawning isolated agent runs that announce results back to the requester chat"
+read_when:
+  - You want background/parallel work via the agent
+  - You are changing sessions_spawn or sub-agent tool policy
+title: "Sub-Agents"
+---
+
+# Sub-agents
+
+Sub-agents are background agent runs spawned from an existing agent run. They run in their own session (`agent:<agentId>:subagent:<uuid>`) and, when finished, **announce** their result back to the requester chat channel.
+
+## Slash command
+
+Use `/subagents` to inspect or control sub-agent runs for the **current session**:
+
+- `/subagents list`
+- `/subagents stop <id|#|all>`
+- `/subagents log <id|#> [limit] [tools]`
+- `/subagents info <id|#>`
+- `/subagents send <id|#> <message>`
+
+`/subagents info` shows run metadata (status, timestamps, session id, transcript path, cleanup).
+
+Primary goals:
+
+- Parallelize “research / long task / slow tool” work without blocking the main run.
+- Keep sub-agents isolated by default (session separation + optional sandboxing).
+- Keep the tool surface hard to misuse: sub-agents do **not** get session tools by default.
+- Avoid nested fan-out: sub-agents cannot spawn sub-agents.
+
+Cost note: each sub-agent has its **own** context and token usage. For heavy or repetitive
+tasks, set a cheaper model for sub-agents and keep your main agent on a higher-quality model.
+You can configure this via `agents.defaults.subagents.model` or per-agent overrides.
+
+## Tool
+
+Use `sessions_spawn`:
+
+- Starts a sub-agent run (`deliver: false`, global lane: `subagent`)
+- Then runs an announce step and posts the announce reply to the requester chat channel
+- Default model: inherits the caller unless you set `agents.defaults.subagents.model` (or per-agent `agents.list[].subagents.model`); an explicit `sessions_spawn.model` still wins.
+- Default thinking: inherits the caller unless you set `agents.defaults.subagents.thinking` (or per-agent `agents.list[].subagents.thinking`); an explicit `sessions_spawn.thinking` still wins.
+
+Tool params:
+
+- `task` (required)
+- `label?` (optional)
+- `agentId?` (optional; spawn under another agent id if allowed)
+- `model?` (optional; overrides the sub-agent model; invalid values are skipped and the sub-agent runs on the default model with a warning in the tool result)
+- `thinking?` (optional; overrides thinking level for the sub-agent run)
+- `runTimeoutSeconds?` (default `0`; when set, the sub-agent run is aborted after N seconds)
+- `cleanup?` (`delete|keep`, default `keep`)
+
+Allowlist:
+
+- `agents.list[].subagents.allowAgents`: list of agent ids that can be targeted via `agentId` (`["*"]` to allow any). Default: only the requester agent.
+
+Discovery:
+
+- Use `agents_list` to see which agent ids are currently allowed for `sessions_spawn`.
+
+Auto-archive:
+
+- Sub-agent sessions are automatically archived after `agents.defaults.subagents.archiveAfterMinutes` (default: 60).
+- Archive uses `sessions.delete` and renames the transcript to `*.deleted.<timestamp>` (same folder).
+- `cleanup: "delete"` archives immediately after announce (still keeps the transcript via rename).
+- Auto-archive is best-effort; pending timers are lost if the gateway restarts.
+- `runTimeoutSeconds` does **not** auto-archive; it only stops the run. The session remains until auto-archive.
+
+## Authentication
+
+Sub-agent auth is resolved by **agent id**, not by session type:
+
+- The sub-agent session key is `agent:<agentId>:subagent:<uuid>`.
+- The auth store is loaded from that agent’s `agentDir`.
+- The main agent’s auth profiles are merged in as a **fallback**; agent profiles override main profiles on conflicts.
+
+Note: the merge is additive, so main profiles are always available as fallbacks. Fully isolated auth per agent is not supported yet.
+
+## Announce
+
+Sub-agents report back via an announce step:
+
+- The announce step runs inside the sub-agent session (not the requester session).
+- If the sub-agent replies exactly `ANNOUNCE_SKIP`, nothing is posted.
+- Otherwise the announce reply is posted to the requester chat channel via a follow-up `agent` call (`deliver=true`).
+- Announce replies preserve thread/topic routing when available (Slack threads, Telegram topics, Matrix threads).
+- Announce messages are normalized to a stable template:
+  - `Status:` derived from the run outcome (`success`, `error`, `timeout`, or `unknown`).
+  - `Result:` the summary content from the announce step (or `(not available)` if missing).
+  - `Notes:` error details and other useful context.
+- `Status` is not inferred from model output; it comes from runtime outcome signals.
+
+Announce payloads include a stats line at the end (even when wrapped):
+
+- Runtime (e.g., `runtime 5m12s`)
+- Token usage (input/output/total)
+- Estimated cost when model pricing is configured (`models.providers.*.models[].cost`)
+- `sessionKey`, `sessionId`, and transcript path (so the main agent can fetch history via `sessions_history` or inspect the file on disk)
+
+## Tool Policy (sub-agent tools)
+
+By default, sub-agents get **all tools except session tools**:
+
+- `sessions_list`
+- `sessions_history`
+- `sessions_send`
+- `sessions_spawn`
+
+Override via config:
+
+```json5
+{
+  agents: {
+    defaults: {
+      subagents: {
+        maxConcurrent: 1,
+      },
+    },
+  },
+  tools: {
+    subagents: {
+      tools: {
+        // deny wins
+        deny: ["gateway", "cron"],
+        // if allow is set, it becomes allow-only (deny still wins)
+        // allow: ["read", "exec", "process"]
+      },
+    },
+  },
+}
+```
+
+## Concurrency
+
+Sub-agents use a dedicated in-process queue lane:
+
+- Lane name: `subagent`
+- Concurrency: `agents.defaults.subagents.maxConcurrent` (default `8`)
+
+## Stopping
+
+- Sending `/stop` in the requester chat aborts the requester session and stops any active sub-agent runs spawned from it.
+
+## Limitations
+
+- Sub-agent announce is **best-effort**. If the gateway restarts, pending “announce back” work is lost.
+- Sub-agents still share the same gateway process resources; treat `maxConcurrent` as a safety valve.
+- `sessions_spawn` is always non-blocking: it returns `{ status: "accepted", runId, childSessionKey }` immediately.
+- Sub-agent context only injects `AGENTS.md` + `TOOLS.md` (no `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, or `BOOTSTRAP.md`).

package/docs/tools/thinking.md

@@ -0,0 +1,73 @@
+---
+summary: "Directive syntax for /think + /verbose and how they affect model reasoning"
+read_when:
+  - Adjusting thinking or verbose directive parsing or defaults
+title: "Thinking Levels"
+---
+
+# Thinking Levels (/think directives)
+
+## What it does
+
+- Inline directive in any inbound body: `/t <level>`, `/think:<level>`, or `/thinking <level>`.
+- Levels (aliases): `off | minimal | low | medium | high | xhigh` (GPT-5.2 + Codex models only)
+  - minimal → “think”
+  - low → “think hard”
+  - medium → “think harder”
+  - high → “ultrathink” (max budget)
+  - xhigh → “ultrathink+” (GPT-5.2 + Codex models only)
+  - `highest`, `max` map to `high`.
+- Provider notes:
+  - Z.AI (`zai/*`) only supports binary thinking (`on`/`off`). Any non-`off` level is treated as `on` (mapped to `low`).
+
+## Resolution order
+
+1. Inline directive on the message (applies only to that message).
+2. Session override (set by sending a directive-only message).
+3. Global default (`agents.defaults.thinkingDefault` in config).
+4. Fallback: low for reasoning-capable models; off otherwise.
+
+## Setting a session default
+
+- Send a message that is **only** the directive (whitespace allowed), e.g. `/think:medium` or `/t high`.
+- That sticks for the current session (per-sender by default); cleared by `/think:off` or session idle reset.
+- Confirmation reply is sent (`Thinking level set to high.` / `Thinking disabled.`). If the level is invalid (e.g. `/thinking big`), the command is rejected with a hint and the session state is left unchanged.
+- Send `/think` (or `/think:`) with no argument to see the current thinking level.
+
+## Application by agent
+
+- **Embedded Pi**: the resolved level is passed to the in-process Pi agent runtime.
+
+## Verbose directives (/verbose or /v)
+
+- Levels: `on` (minimal) | `full` | `off` (default).
+- Directive-only message toggles session verbose and replies `Verbose logging enabled.` / `Verbose logging disabled.`; invalid levels return a hint without changing state.
+- `/verbose off` stores an explicit session override; clear it via the Sessions UI by choosing `inherit`.
+- Inline directive affects only that message; session/global defaults apply otherwise.
+- Send `/verbose` (or `/verbose:`) with no argument to see the current verbose level.
+- When verbose is on, agents that emit structured tool results (Pi, other JSON agents) send each tool call back as its own metadata-only message, prefixed with `<emoji> <tool-name>: <arg>` when available (path/command). These tool summaries are sent as soon as each tool starts (separate bubbles), not as streaming deltas.
+- When verbose is `full`, tool outputs are also forwarded after completion (separate bubble, truncated to a safe length). If you toggle `/verbose on|full|off` while a run is in-flight, subsequent tool bubbles honor the new setting.
+
+## Reasoning visibility (/reasoning)
+
+- Levels: `on|off|stream`.
+- Directive-only message toggles whether thinking blocks are shown in replies.
+- When enabled, reasoning is sent as a **separate message** prefixed with `Reasoning:`.
+- `stream` (Telegram only): streams reasoning into the Telegram draft bubble while the reply is generating, then sends the final answer without reasoning.
+- Alias: `/reason`.
+- Send `/reasoning` (or `/reasoning:`) with no argument to see the current reasoning level.
+
+## Related
+
+- Elevated mode docs live in [Elevated mode](/tools/elevated).
+
+## Heartbeats
+
+- Heartbeat probe body is the configured heartbeat prompt (default: `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.`). Inline directives in a heartbeat message apply as usual (but avoid changing session defaults from heartbeats).
+- Heartbeat delivery defaults to the final payload only. To also send the separate `Reasoning:` message (when available), set `agents.defaults.heartbeat.includeReasoning: true` or per-agent `agents.list[].heartbeat.includeReasoning: true`.
+
+## Web chat UI
+
+- The web chat thinking selector mirrors the session's stored level from the inbound session store/config when the page loads.
+- Picking another level applies only to the next message (`thinkingOnce`); after sending, the selector snaps back to the stored session level.
+- To change the session default, send a `/think:<level>` directive (as before); the selector will reflect it after the next reload.

package/docs/tools/web.md

@@ -0,0 +1,261 @@
+---
+summary: "Web search + fetch tools (Brave Search API, Perplexity direct/OpenRouter)"
+read_when:
+  - You want to enable web_search or web_fetch
+  - You need Brave Search API key setup
+  - You want to use Perplexity Sonar for web search
+title: "Web Tools"
+---
+
+# Web tools
+
+Milaidy ships two lightweight web tools:
+
+- `web_search` — Search the web via Brave Search API (default) or Perplexity Sonar (direct or via OpenRouter).
+- `web_fetch` — HTTP fetch + readable extraction (HTML → markdown/text).
+
+These are **not** browser automation. For JS-heavy sites or logins, use the
+[Browser tool](/tools/browser).
+
+## How it works
+
+- `web_search` calls your configured provider and returns results.
+  - **Brave** (default): returns structured results (title, URL, snippet).
+  - **Perplexity**: returns AI-synthesized answers with citations from real-time web search.
+- Results are cached by query for 15 minutes (configurable).
+- `web_fetch` does a plain HTTP GET and extracts readable content
+  (HTML → markdown/text). It does **not** execute JavaScript.
+- `web_fetch` is enabled by default (unless explicitly disabled).
+
+## Choosing a search provider
+
+| Provider            | Pros                                         | Cons                                     | API Key                                      |
+| ------------------- | -------------------------------------------- | ---------------------------------------- | -------------------------------------------- |
+| **Brave** (default) | Fast, structured results, free tier          | Traditional search results               | `BRAVE_API_KEY`                              |
+| **Perplexity**      | AI-synthesized answers, citations, real-time | Requires Perplexity or OpenRouter access | `OPENROUTER_API_KEY` or `PERPLEXITY_API_KEY` |
+
+See [Brave Search setup](/brave-search) and [Perplexity Sonar](/perplexity) for provider-specific details.
+
+Set the provider in config:
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        provider: "brave", // or "perplexity"
+      },
+    },
+  },
+}
+```
+
+Example: switch to Perplexity Sonar (direct API):
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        provider: "perplexity",
+        perplexity: {
+          apiKey: "pplx-...",
+          baseUrl: "https://api.perplexity.ai",
+          model: "perplexity/sonar-pro",
+        },
+      },
+    },
+  },
+}
+```
+
+## Getting a Brave API key
+
+1. Create a Brave Search API account at https://brave.com/search/api/
+2. In the dashboard, choose the **Data for Search** plan (not “Data for AI”) and generate an API key.
+3. Run `milaidy configure --section web` to store the key in config (recommended), or set `BRAVE_API_KEY` in your environment.
+
+Brave provides a free tier plus paid plans; check the Brave API portal for the
+current limits and pricing.
+
+### Where to set the key (recommended)
+
+**Recommended:** run `milaidy configure --section web`. It stores the key in
+`~/.milaidy/milaidy.json` under `tools.web.search.apiKey`.
+
+**Environment alternative:** set `BRAVE_API_KEY` in the Gateway process
+environment. For a gateway install, put it in `~/.milaidy/.env` (or your
+service environment). See [Env vars](/help/faq#how-does-milaidy-load-environment-variables).
+
+## Using Perplexity (direct or via OpenRouter)
+
+Perplexity Sonar models have built-in web search capabilities and return AI-synthesized
+answers with citations. You can use them via OpenRouter (no credit card required - supports
+crypto/prepaid).
+
+### Getting an OpenRouter API key
+
+1. Create an account at https://openrouter.ai/
+2. Add credits (supports crypto, prepaid, or credit card)
+3. Generate an API key in your account settings
+
+### Setting up Perplexity search
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        enabled: true,
+        provider: "perplexity",
+        perplexity: {
+          // API key (optional if OPENROUTER_API_KEY or PERPLEXITY_API_KEY is set)
+          apiKey: "sk-or-v1-...",
+          // Base URL (key-aware default if omitted)
+          baseUrl: "https://openrouter.ai/api/v1",
+          // Model (defaults to perplexity/sonar-pro)
+          model: "perplexity/sonar-pro",
+        },
+      },
+    },
+  },
+}
+```
+
+**Environment alternative:** set `OPENROUTER_API_KEY` or `PERPLEXITY_API_KEY` in the Gateway
+environment. For a gateway install, put it in `~/.milaidy/.env`.
+
+If no base URL is set, Milaidy chooses a default based on the API key source:
+
+- `PERPLEXITY_API_KEY` or `pplx-...` → `https://api.perplexity.ai`
+- `OPENROUTER_API_KEY` or `sk-or-...` → `https://openrouter.ai/api/v1`
+- Unknown key formats → OpenRouter (safe fallback)
+
+### Available Perplexity models
+
+| Model                            | Description                          | Best for          |
+| -------------------------------- | ------------------------------------ | ----------------- |
+| `perplexity/sonar`               | Fast Q&A with web search             | Quick lookups     |
+| `perplexity/sonar-pro` (default) | Multi-step reasoning with web search | Complex questions |
+| `perplexity/sonar-reasoning-pro` | Chain-of-thought analysis            | Deep research     |
+
+## web_search
+
+Search the web using your configured provider.
+
+### Requirements
+
+- `tools.web.search.enabled` must not be `false` (default: enabled)
+- API key for your chosen provider:
+  - **Brave**: `BRAVE_API_KEY` or `tools.web.search.apiKey`
+  - **Perplexity**: `OPENROUTER_API_KEY`, `PERPLEXITY_API_KEY`, or `tools.web.search.perplexity.apiKey`
+
+### Config
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        enabled: true,
+        apiKey: "BRAVE_API_KEY_HERE", // optional if BRAVE_API_KEY is set
+        maxResults: 5,
+        timeoutSeconds: 30,
+        cacheTtlMinutes: 15,
+      },
+    },
+  },
+}
+```
+
+### Tool parameters
+
+- `query` (required)
+- `count` (1–10; default from config)
+- `country` (optional): 2-letter country code for region-specific results (e.g., "DE", "US", "ALL"). If omitted, Brave chooses its default region.
+- `search_lang` (optional): ISO language code for search results (e.g., "de", "en", "fr")
+- `ui_lang` (optional): ISO language code for UI elements
+- `freshness` (optional, Brave only): filter by discovery time (`pd`, `pw`, `pm`, `py`, or `YYYY-MM-DDtoYYYY-MM-DD`)
+
+**Examples:**
+
+```javascript
+// German-specific search
+await web_search({
+  query: "TV online schauen",
+  count: 10,
+  country: "DE",
+  search_lang: "de",
+});
+
+// French search with French UI
+await web_search({
+  query: "actualités",
+  country: "FR",
+  search_lang: "fr",
+  ui_lang: "fr",
+});
+
+// Recent results (past week)
+await web_search({
+  query: "TMBG interview",
+  freshness: "pw",
+});
+```
+
+## web_fetch
+
+Fetch a URL and extract readable content.
+
+### Requirements
+
+- `tools.web.fetch.enabled` must not be `false` (default: enabled)
+- Optional Firecrawl fallback: set `tools.web.fetch.firecrawl.apiKey` or `FIRECRAWL_API_KEY`.
+
+### Config
+
+```json5
+{
+  tools: {
+    web: {
+      fetch: {
+        enabled: true,
+        maxChars: 50000,
+        maxCharsCap: 50000,
+        timeoutSeconds: 30,
+        cacheTtlMinutes: 15,
+        maxRedirects: 3,
+        userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 14_7_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
+        readability: true,
+        firecrawl: {
+          enabled: true,
+          apiKey: "FIRECRAWL_API_KEY_HERE", // optional if FIRECRAWL_API_KEY is set
+          baseUrl: "https://api.firecrawl.dev",
+          onlyMainContent: true,
+          maxAgeMs: 86400000, // ms (1 day)
+          timeoutSeconds: 60,
+        },
+      },
+    },
+  },
+}
+```
+
+### Tool parameters
+
+- `url` (required, http/https only)
+- `extractMode` (`markdown` | `text`)
+- `maxChars` (truncate long pages)
+
+Notes:
+
+- `web_fetch` uses Readability (main-content extraction) first, then Firecrawl (if configured). If both fail, the tool returns an error.
+- Firecrawl requests use bot-circumvention mode and cache results by default.
+- `web_fetch` sends a Chrome-like User-Agent and `Accept-Language` by default; override `userAgent` if needed.
+- `web_fetch` blocks private/internal hostnames and re-checks redirects (limit with `maxRedirects`).
+- `maxChars` is clamped to `tools.web.fetch.maxCharsCap`.
+- `web_fetch` is best-effort extraction; some sites will need the browser tool.
+- See [Firecrawl](/tools/firecrawl) for key setup and service details.
+- Responses are cached (default 15 minutes) to reduce repeated fetches.
+- If you use tool profiles/allowlists, add `web_search`/`web_fetch` or `group:web`.
+- If the Brave key is missing, `web_search` returns a short setup hint with a docs link.

package/docs/tui.md

@@ -0,0 +1,159 @@
+---
+summary: "Terminal UI (TUI): connect to the Gateway from any machine"
+read_when:
+  - You want a beginner-friendly walkthrough of the TUI
+  - You need the complete list of TUI features, commands, and shortcuts
+title: "TUI"
+---
+
+# TUI (Terminal UI)
+
+## Quick start
+
+1. Start the Gateway.
+
+```bash
+milaidy gateway
+```
+
+2. Open the TUI.
+
+```bash
+milaidy tui
+```
+
+3. Type a message and press Enter.
+
+Remote Gateway:
+
+```bash
+milaidy tui --url ws://<host>:<port> --token <gateway-token>
+```
+
+Use `--password` if your Gateway uses password auth.
+
+## What you see
+
+- Header: connection URL, current agent, current session.
+- Chat log: user messages, assistant replies, system notices, tool cards.
+- Status line: connection/run state (connecting, running, streaming, idle, error).
+- Footer: connection state + agent + session + model + think/verbose/reasoning + token counts + deliver.
+- Input: text editor with autocomplete.
+
+## Mental model: agents + sessions
+
+- Agents are unique slugs (e.g. `main`, `research`). The Gateway exposes the list.
+- Sessions belong to the current agent.
+- Session keys are stored as `agent:<agentId>:<sessionKey>`.
+  - If you type `/session main`, the TUI expands it to `agent:<currentAgent>:main`.
+  - If you type `/session agent:other:main`, you switch to that agent session explicitly.
+- Session scope:
+  - `per-sender` (default): each agent has many sessions.
+  - `global`: the TUI always uses the `global` session (the picker may be empty).
+- The current agent + session are always visible in the footer.
+
+## Sending + delivery
+
+- Messages are sent to the Gateway; delivery to providers is off by default.
+- Turn delivery on:
+  - `/deliver on`
+  - or the Settings panel
+  - or start with `milaidy tui --deliver`
+
+## Pickers + overlays
+
+- Model picker: list available models and set the session override.
+- Agent picker: choose a different agent.
+- Session picker: shows only sessions for the current agent.
+- Settings: toggle deliver, tool output expansion, and thinking visibility.
+
+## Keyboard shortcuts
+
+- Enter: send message
+- Esc: abort active run
+- Ctrl+C: clear input (press twice to exit)
+- Ctrl+D: exit
+- Ctrl+L: model picker
+- Ctrl+G: agent picker
+- Ctrl+P: session picker
+- Ctrl+O: toggle tool output expansion
+- Ctrl+T: toggle thinking visibility (reloads history)
+
+## Slash commands
+
+Core:
+
+- `/help`
+- `/status`
+- `/agent <id>` (or `/agents`)
+- `/session <key>` (or `/sessions`)
+- `/model <provider/model>` (or `/models`)
+
+Session controls:
+
+- `/think <off|minimal|low|medium|high>`
+- `/verbose <on|full|off>`
+- `/reasoning <on|off|stream>`
+- `/usage <off|tokens|full>`
+- `/elevated <on|off|ask|full>` (alias: `/elev`)
+- `/activation <mention|always>`
+- `/deliver <on|off>`
+
+Session lifecycle:
+
+- `/new` or `/reset` (reset the session)
+- `/abort` (abort the active run)
+- `/settings`
+- `/exit`
+
+Other Gateway slash commands (for example, `/context`) are forwarded to the Gateway and shown as system output. See [Slash commands](/tools/slash-commands).
+
+## Local shell commands
+
+- Prefix a line with `!` to run a local shell command on the TUI host.
+- The TUI prompts once per session to allow local execution; declining keeps `!` disabled for the session.
+- Commands run in a fresh, non-interactive shell in the TUI working directory (no persistent `cd`/env).
+- A lone `!` is sent as a normal message; leading spaces do not trigger local exec.
+
+## Tool output
+
+- Tool calls show as cards with args + results.
+- Ctrl+O toggles between collapsed/expanded views.
+- While tools run, partial updates stream into the same card.
+
+## History + streaming
+
+- On connect, the TUI loads the latest history (default 200 messages).
+- Streaming responses update in place until finalized.
+- The TUI also listens to agent tool events for richer tool cards.
+
+## Connection details
+
+- The TUI registers with the Gateway as `mode: "tui"`.
+- Reconnects show a system message; event gaps are surfaced in the log.
+
+## Options
+
+- `--url <url>`: Gateway WebSocket URL (defaults to config or `ws://127.0.0.1:<port>`)
+- `--token <token>`: Gateway token (if required)
+- `--password <password>`: Gateway password (if required)
+- `--session <key>`: Session key (default: `main`, or `global` when scope is global)
+- `--deliver`: Deliver assistant replies to the provider (default off)
+- `--thinking <level>`: Override thinking level for sends
+- `--timeout-ms <ms>`: Agent timeout in ms (defaults to `agents.defaults.timeoutSeconds`)
+
+## Troubleshooting
+
+No output after sending a message:
+
+- Run `/status` in the TUI to confirm the Gateway is connected and idle/busy.
+- Check the Gateway logs: `milaidy logs --follow`.
+- Confirm the agent can run: `milaidy status` and `milaidy models status`.
+- If you expect messages in a chat channel, enable delivery (`/deliver on` or `--deliver`).
+- `--history-limit <n>`: History entries to load (default 200)
+
+## Troubleshooting
+
+- `disconnected`: ensure the Gateway is running and your `--url/--token/--password` are correct.
+- No agents in picker: check `milaidy agents list` and your routing config.
+- Empty session picker: you might be in global scope or have no sessions yet.

package/docs/vps.md

@@ -0,0 +1,43 @@
+---
+summary: "VPS hosting hub for Milaidy (Oracle/Fly/Hetzner/GCP/exe.dev)"
+read_when:
+  - You want to run the Gateway in the cloud
+  - You need a quick map of VPS/hosting guides
+title: "VPS Hosting"
+---
+
+# VPS hosting
+
+This hub links to the supported VPS/hosting guides and explains how cloud
+deployments work at a high level.
+
+## Pick a provider
+
+- **Railway** (one‑click + browser setup): [Railway](/railway)
+- **Northflank** (one‑click + browser setup): [Northflank](/northflank)
+- **Oracle Cloud (Always Free)**: [Oracle](/platforms/oracle) — $0/month (Always Free, ARM; capacity/signup can be finicky)
+- **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)
+- **AWS (EC2/Lightsail/free tier)**: works well too. Video guide:
+  https://x.com/techfrenAJ/status/2014934471095812547
+
+## How cloud setups work
+
+- The **Gateway runs on the VPS** and owns state + workspace.
+- You connect from your laptop/phone via the **Control UI** or **Tailscale/SSH**.
+- Treat the VPS as the source of truth and **back up** the state + workspace.
+- Secure default: keep the Gateway on loopback and access it via SSH tunnel or Tailscale Serve.
+  If you bind to `lan`/`tailnet`, require `gateway.auth.token` or `gateway.auth.password`.
+
+Remote access: [Gateway remote](/gateway/remote)  
+Platforms hub: [Platforms](/platforms)
+
+## Using nodes with a VPS
+
+You can keep the Gateway in the cloud and pair **nodes** on your local devices
+(Mac/iOS/Android/headless). Nodes provide local screen/camera/canvas and `system.run`
+capabilities while the Gateway stays in the cloud.
+
+Docs: [Nodes](/nodes), [Nodes CLI](/cli/nodes)