@symerian/symi 3.0.21 → 3.0.22

package/docs/platforms/android.md

@@ -1,151 +0,0 @@
----
-summary: "Android app (node): connection runbook + Canvas/Chat/Camera"
-read_when:
-  - Pairing or reconnecting the Android node
-  - Debugging Android gateway discovery or auth
-  - Verifying chat history parity across clients
-title: "Android App"
----
-
-# Android App (Node)
-
-## 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: [Getting Started](/start/getting-started) + [Pairing](/gateway/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 (default `ws://<host>:18789`) and uses Gateway-owned pairing.
-
-### 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)
-- You can run the CLI (`symi`) on the gateway machine (or via SSH).
-
-### 1) Start the Gateway
-
-```bash
-symi gateway --port 18789 --verbose
-```
-
-Confirm in logs you see something like:
-
-- `listening on ws://0.0.0.0:18789`
-
-For tailnet-only setups (recommended for Vienna ⇄ London), bind the gateway to the tailnet IP:
-
-- Set `gateway.bind: "tailnet"` in `~/.symi/symi.json` on the gateway host.
-- Restart the Gateway / macOS menubar app.
-
-### 2) Verify discovery (optional)
-
-From the gateway machine:
-
-```bash
-dns-sd -B _symi-gw._tcp local.
-```
-
-More debugging notes: [Bonjour](/gateway/bonjour).
-
-#### 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:
-
-1. Set up a DNS-SD zone (example `symi.internal.`) on the gateway host and publish `_symi-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 **Settings**.
-- Under **Discovered Gateways**, select your gateway and hit **Connect**.
-- If mDNS is blocked, use **Advanced → Manual Gateway** (host + port) and **Connect (Manual)**.
-
-After the first successful pairing, Android auto-reconnects on launch:
-
-- Manual endpoint (if enabled), otherwise
-- The last discovered gateway (best-effort).
-
-### 4) Approve pairing (CLI)
-
-On the gateway machine:
-
-```bash
-symi nodes pending
-symi nodes approve <requestId>
-```
-
-Pairing details: [Gateway pairing](/gateway/pairing).
-
-### 5) Verify the node is connected
-
-- Via nodes status:
-
-  ```bash
-  symi nodes status
-  ```
-
-- Via Gateway:
-
-  ```bash
-  symi gateway call node.list --params "{}"
-  ```
-
-### 6) Chat + history
-
-The Android node’s Chat sheet uses the gateway’s **primary session key** (`main`), so history and replies are shared with WebChat and other clients:
-
-- History: `chat.history`
-- 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`).
-
-1. Create `~/.symi/workspace/canvas/index.html` on the gateway host.
-
-2. Navigate the node to it (LAN):
-
-```bash
-symi nodes invoke --node "<Android Node>" --command canvas.navigate --params '{"url":"http://<gateway-hostname>.local:18789/__symi__/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/__symi__/canvas/`.
-
-This server injects a live-reload client into HTML and reloads on file changes.
-The A2UI host lives at `http://<gateway-host>:18789/__symi__/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.

package/docs/platforms/digitalocean.md

@@ -1,265 +0,0 @@
----
-summary: "Symi on DigitalOcean (simple paid VPS option)"
-read_when:
-  - Setting up Symi on DigitalOcean
-  - Looking for cheap VPS hosting for Symi
-title: "DigitalOcean"
----
-
-# Symi on DigitalOcean
-
-## Goal
-
-Run a persistent Symi Gateway on DigitalOcean for **$6/month** (or $4/mo with reserved pricing).
-
-If you want a $0/month option and don’t mind ARM + provider-specific setup, see the [Oracle Cloud guide](/platforms/oracle).
-
-## Cost Comparison (2026)
-
-| Provider     | Plan            | Specs                  | Price/mo    | Notes                                 |
-| ------------ | --------------- | ---------------------- | ----------- | ------------------------------------- |
-| Oracle Cloud | Always Free ARM | up to 4 OCPU, 24GB RAM | $0          | ARM, limited capacity / signup quirks |
-| Hetzner      | CX22            | 2 vCPU, 4GB RAM        | €3.79 (~$4) | Cheapest paid option                  |
-| DigitalOcean | Basic           | 1 vCPU, 1GB RAM        | $6          | Easy UI, good docs                    |
-| Vultr        | Cloud Compute   | 1 vCPU, 1GB RAM        | $6          | Many locations                        |
-| Linode       | Nanode          | 1 vCPU, 1GB RAM        | $5          | Now part of Akamai                    |
-
-**Picking a provider:**
-
-- DigitalOcean: simplest UX + predictable setup (this guide)
-- Hetzner: good price/perf (see [Hetzner guide](/install/hetzner))
-- Oracle Cloud: can be $0/month, but is more finicky and ARM-only (see [Oracle guide](/platforms/oracle))
-
----
-
-## Prerequisites
-
-- DigitalOcean account ([signup with $200 free credit](https://m.do.co/c/signup))
-- SSH key pair (or willingness to use password auth)
-- ~20 minutes
-
-## 1) Create a Droplet
-
-<Warning>
-Use a clean base image (Ubuntu 24.04 LTS). Avoid third-party Marketplace 1-click images unless you have reviewed their startup scripts and firewall defaults.
-</Warning>
-
-1. Log into [DigitalOcean](https://cloud.digitalocean.com/)
-2. Click **Create → Droplets**
-3. Choose:
-   - **Region:** Closest to you (or your users)
-   - **Image:** Ubuntu 24.04 LTS
-   - **Size:** Basic → Regular → **$6/mo** (1 vCPU, 1GB RAM, 25GB SSD)
-   - **Authentication:** SSH key (recommended) or password
-4. Click **Create Droplet**
-5. Note the IP address
-
-## 2) Connect via SSH
-
-```bash
-ssh root@YOUR_DROPLET_IP
-```
-
-## 3) Install Symi
-
-```bash
-# Update system
-apt update && apt upgrade -y
-
-# Install Node.js 22
-curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
-apt install -y nodejs
-
-# Install Symi
-curl -fsSL https://jaysteelmind.github.io/getsymi/install.sh | bash
-
-# Verify
-symi --version
-```
-
-## 4) Run Onboarding
-
-```bash
-symi onboard --install-daemon
-```
-
-The wizard will walk you through:
-
-- Model auth (API keys or OAuth)
-- Gateway token (auto-generated)
-- Daemon installation (systemd)
-
-## 5) Verify the Gateway
-
-```bash
-# Check status
-symi status
-
-# Check service
-systemctl --user status symi-gateway.service
-
-# View logs
-journalctl --user -u symi-gateway.service -f
-```
-
-## 6) Access the Dashboard
-
-The gateway binds to loopback by default. To access the Control UI:
-
-**Option A: SSH Tunnel (recommended)**
-
-```bash
-# From your local machine
-ssh -L 18789:localhost:18789 root@YOUR_DROPLET_IP
-
-# Then open: http://localhost:18789
-```
-
-**Option B: Tailscale Serve (HTTPS, loopback-only)**
-
-```bash
-# On the droplet
-curl -fsSL https://tailscale.com/install.sh | sh
-tailscale up
-
-# Configure Gateway to use Tailscale Serve
-symi config set gateway.tailscale.mode serve
-symi gateway restart
-```
-
-Open: `https://<magicdns>/`
-
-Notes:
-
-- Serve keeps the Gateway loopback-only and authenticates Control UI/WebSocket traffic via Tailscale identity headers (tokenless auth assumes trusted gateway host; HTTP APIs still require token/password).
-- To require token/password instead, set `gateway.auth.allowTailscale: false` or use `gateway.auth.mode: "password"`.
-
-**Option C: Tailnet bind (no Serve)**
-
-```bash
-symi config set gateway.bind tailnet
-symi gateway restart
-```
-
-Open: `http://<tailscale-ip>:18789` (token required).
-
-## 7) Connect Your Channels
-
-### Telegram
-
-```bash
-symi pairing list telegram
-symi pairing approve telegram <CODE>
-```
-
-### WhatsApp
-
-```bash
-symi channels login whatsapp
-# Scan QR code
-```
-
-See [Channels](/channels) for other providers.
-
----
-
-## Optimizations for 1GB RAM
-
-The $6 droplet only has 1GB RAM. To keep things running smoothly:
-
-### Add swap (recommended)
-
-```bash
-fallocate -l 2G /swapfile
-chmod 600 /swapfile
-mkswap /swapfile
-swapon /swapfile
-echo '/swapfile none swap sw 0 0' >> /etc/fstab
-```
-
-### Use a lighter model
-
-If you're hitting OOMs, consider:
-
-- Using API-based models (Claude, GPT) instead of local models
-- Setting `agents.defaults.model.primary` to a smaller model
-
-### Monitor memory
-
-```bash
-free -h
-htop
-```
-
----
-
-## Persistence
-
-All state lives in:
-
-- `~/.symi/` — config, credentials, session data
-- `~/.symi/workspace/` — workspace (SYMICORE.md, memory, etc.)
-
-These survive reboots. Back them up periodically:
-
-```bash
-tar -czvf symi-backup.tar.gz ~/.symi ~/.symi/workspace
-```
-
----
-
-## Oracle Cloud Free Alternative
-
-Oracle Cloud offers **Always Free** ARM instances that are significantly more powerful than any paid option here — for $0/month.
-
-| What you get      | Specs                  |
-| ----------------- | ---------------------- |
-| **4 OCPUs**       | ARM Ampere A1          |
-| **24GB RAM**      | More than enough       |
-| **200GB storage** | Block volume           |
-| **Forever free**  | No credit card charges |
-
-**Caveats:**
-
-- Signup can be finicky (retry if it fails)
-- ARM architecture — most things work, but some binaries need ARM builds
-
-For the full setup guide, see [Oracle Cloud](/platforms/oracle). For signup tips and troubleshooting the enrollment process, see this [community guide](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd).
-
----
-
-## Troubleshooting
-
-### Gateway won't start
-
-```bash
-symi gateway status
-symi doctor --non-interactive
-journalctl -u symi --no-pager -n 50
-```
-
-### Port already in use
-
-```bash
-lsof -i :18789
-kill <PID>
-```
-
-### Out of memory
-
-```bash
-# Check memory
-free -h
-
-# Add more swap
-# Or upgrade to $12/mo droplet (2GB RAM)
-```
-
----
-
-## See Also
-
-- [Hetzner guide](/install/hetzner) — cheaper, more powerful
-- [Docker install](/install/docker) — containerized setup
-- [Tailscale](/gateway/tailscale) — secure remote access
-- [Configuration](/gateway/configuration) — full config reference

package/docs/platforms/index.md

@@ -1,53 +0,0 @@
----
-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
-
-Symi 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](/install/fly)
-- Hetzner (Docker): [Hetzner](/install/hetzner)
-- GCP (Compute Engine): [GCP](/install/gcp)
-- 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: `symi gateway status`
-
-## Gateway service install (CLI)
-
-Use one of these (all supported):
-
-- Wizard (recommended): `symi onboard --install-daemon`
-- Direct: `symi gateway install`
-- Configure flow: `symi configure` → select **Gateway service**
-- Repair/migrate: `symi 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.symi.*`)
-- Linux/WSL2: systemd user service (`symi-gateway[-<profile>].service`)

package/docs/platforms/ios.md

@@ -1,108 +0,0 @@
----
-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: `symi.internal.`), **or**
-  - Manual host/port (fallback).
-
-## Quick start (pair + connect)
-
-1. Start the Gateway:
-
-```bash
-symi 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
-symi nodes pending
-symi nodes approve <requestId>
-```
-
-4. Verify connection:
-
-```bash
-symi nodes status
-symi gateway call node.list --params "{}"
-```
-
-## Discovery paths
-
-### Bonjour (LAN)
-
-The Gateway advertises `_symi-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: `symi.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
-symi nodes invoke --node "iOS Node" --command canvas.navigate --params '{"url":"http://<gateway-host>:18789/__symi__/canvas/"}'
-```
-
-Notes:
-
-- The Gateway canvas host serves `/__symi__/canvas/` and `/__symi__/a2ui/`.
-- It is served from the Gateway HTTP server (same port as `gateway.port`, default `18789`).
-- 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
-symi nodes invoke --node "iOS Node" --command canvas.eval --params '{"javaScript":"(() => { const {ctx} = window.__symi; 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
-symi 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).
-- `A2UI_HOST_NOT_CONFIGURED`: the Gateway did not advertise a canvas host URL; check `canvasHost` in [Gateway configuration](/gateway/configuration).
-- Pairing prompt never appears: run `symi 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

@@ -1,94 +0,0 @@
----
-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 @symerian/symi@latest`
-3. `symi 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](/install/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:
-
-```
-symi onboard --install-daemon
-```
-
-Or:
-
-```
-symi gateway install
-```
-
-Or:
-
-```
-symi configure
-```
-
-Select **Gateway service** when prompted.
-
-Repair/migrate:
-
-```
-symi doctor
-```
-
-## System control (systemd user unit)
-
-Symi 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/symi-gateway[-<profile>].service`:
-
-```
-[Unit]
-Description=Symi Gateway (profile: <profile>, v<version>)
-After=network-online.target
-Wants=network-online.target
-
-[Service]
-ExecStart=/usr/local/bin/symi gateway --port 18789
-Restart=always
-RestartSec=5
-
-[Install]
-WantedBy=default.target
-```
-
-Enable it:
-
-```
-systemctl --user enable --now symi-gateway[-<profile>].service
-```