@symerian/symi 3.0.20 → 3.0.22

package/docs/platforms/raspberry-pi.md

@@ -1,358 +0,0 @@
----
-summary: "Symi on Raspberry Pi (budget self-hosted setup)"
-read_when:
-  - Setting up Symi on a Raspberry Pi
-  - Running Symi on ARM devices
-  - Building a cheap always-on personal AI
-title: "Raspberry Pi"
----
-
-# Symi on Raspberry Pi
-
-## Goal
-
-Run a persistent, always-on Symi Gateway on a Raspberry Pi for **~$35-80** one-time cost (no monthly fees).
-
-Perfect for:
-
-- 24/7 personal AI assistant
-- Home automation hub
-- Low-power, always-available Telegram/WhatsApp bot
-
-## Hardware Requirements
-
-| Pi Model        | RAM     | Works?   | Notes                              |
-| --------------- | ------- | -------- | ---------------------------------- |
-| **Pi 5**        | 4GB/8GB | ✅ Best  | Fastest, recommended               |
-| **Pi 4**        | 4GB     | ✅ Good  | Sweet spot for most users          |
-| **Pi 4**        | 2GB     | ✅ OK    | Works, add swap                    |
-| **Pi 4**        | 1GB     | ⚠️ Tight | Possible with swap, minimal config |
-| **Pi 3B+**      | 1GB     | ⚠️ Slow  | Works but sluggish                 |
-| **Pi Zero 2 W** | 512MB   | ❌       | Not recommended                    |
-
-**Minimum specs:** 1GB RAM, 1 core, 500MB disk  
-**Recommended:** 2GB+ RAM, 64-bit OS, 16GB+ SD card (or USB SSD)
-
-## What You'll Need
-
-- Raspberry Pi 4 or 5 (2GB+ recommended)
-- MicroSD card (16GB+) or USB SSD (better performance)
-- Power supply (official Pi PSU recommended)
-- Network connection (Ethernet or WiFi)
-- ~30 minutes
-
-## 1) Flash the OS
-
-Use **Raspberry Pi OS Lite (64-bit)** — no desktop needed for a headless server.
-
-1. Download [Raspberry Pi Imager](https://www.raspberrypi.com/software/)
-2. Choose OS: **Raspberry Pi OS Lite (64-bit)**
-3. Click the gear icon (⚙️) to pre-configure:
-   - Set hostname: `gateway-host`
-   - Enable SSH
-   - Set username/password
-   - Configure WiFi (if not using Ethernet)
-4. Flash to your SD card / USB drive
-5. Insert and boot the Pi
-
-## 2) Connect via SSH
-
-```bash
-ssh user@gateway-host
-# or use the IP address
-ssh user@192.168.x.x
-```
-
-## 3) System Setup
-
-```bash
-# Update system
-sudo apt update && sudo apt upgrade -y
-
-# Install essential packages
-sudo apt install -y git curl build-essential
-
-# Set timezone (important for cron/reminders)
-sudo timedatectl set-timezone America/Chicago  # Change to your timezone
-```
-
-## 4) Install Node.js 22 (ARM64)
-
-```bash
-# Install Node.js via NodeSource
-curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
-sudo apt install -y nodejs
-
-# Verify
-node --version  # Should show v22.x.x
-npm --version
-```
-
-## 5) Add Swap (Important for 2GB or less)
-
-Swap prevents out-of-memory crashes:
-
-```bash
-# Create 2GB swap file
-sudo fallocate -l 2G /swapfile
-sudo chmod 600 /swapfile
-sudo mkswap /swapfile
-sudo swapon /swapfile
-
-# Make permanent
-echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
-
-# Optimize for low RAM (reduce swappiness)
-echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
-sudo sysctl -p
-```
-
-## 6) Install Symi
-
-### Option A: Standard Install (Recommended)
-
-```bash
-curl -fsSL https://jaysteelmind.github.io/getsymi/install.sh | bash
-```
-
-### Option B: Hackable Install (For tinkering)
-
-```bash
-git clone https://github.com/symi/symi.git
-cd symi
-npm install
-npm run build
-npm link
-```
-
-The hackable install gives you direct access to logs and code — useful for debugging ARM-specific issues.
-
-## 7) Run Onboarding
-
-```bash
-symi onboard --install-daemon
-```
-
-Follow the wizard:
-
-1. **Gateway mode:** Local
-2. **Auth:** API keys recommended (OAuth can be finicky on headless Pi)
-3. **Channels:** Telegram is easiest to start with
-4. **Daemon:** Yes (systemd)
-
-## 8) Verify Installation
-
-```bash
-# Check status
-symi status
-
-# Check service
-sudo systemctl status symi
-
-# View logs
-journalctl -u symi -f
-```
-
-## 9) Access the Dashboard
-
-Since the Pi is headless, use an SSH tunnel:
-
-```bash
-# From your laptop/desktop
-ssh -L 18789:localhost:18789 user@gateway-host
-
-# Then open in browser
-open http://localhost:18789
-```
-
-Or use Tailscale for always-on access:
-
-```bash
-# On the Pi
-curl -fsSL https://tailscale.com/install.sh | sh
-sudo tailscale up
-
-# Update config
-symi config set gateway.bind tailnet
-sudo systemctl restart symi
-```
-
----
-
-## Performance Optimizations
-
-### Use a USB SSD (Huge Improvement)
-
-SD cards are slow and wear out. A USB SSD dramatically improves performance:
-
-```bash
-# Check if booting from USB
-lsblk
-```
-
-See [Pi USB boot guide](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#usb-mass-storage-boot) for setup.
-
-### Reduce Memory Usage
-
-```bash
-# Disable GPU memory allocation (headless)
-echo 'gpu_mem=16' | sudo tee -a /boot/config.txt
-
-# Disable Bluetooth if not needed
-sudo systemctl disable bluetooth
-```
-
-### Monitor Resources
-
-```bash
-# Check memory
-free -h
-
-# Check CPU temperature
-vcgencmd measure_temp
-
-# Live monitoring
-htop
-```
-
----
-
-## ARM-Specific Notes
-
-### Binary Compatibility
-
-Most Symi features work on ARM64, but some external binaries may need ARM builds:
-
-| Tool               | ARM64 Status | Notes                               |
-| ------------------ | ------------ | ----------------------------------- |
-| Node.js            | ✅           | Works great                         |
-| WhatsApp (Baileys) | ✅           | Pure JS, no issues                  |
-| Telegram           | ✅           | Pure JS, no issues                  |
-| gog (Gmail CLI)    | ⚠️           | Check for ARM release               |
-| Chromium (browser) | ✅           | `sudo apt install chromium-browser` |
-
-If a skill fails, check if its binary has an ARM build. Many Go/Rust tools do; some don't.
-
-### 32-bit vs 64-bit
-
-**Always use 64-bit OS.** Node.js and many modern tools require it. Check with:
-
-```bash
-uname -m
-# Should show: aarch64 (64-bit) not armv7l (32-bit)
-```
-
----
-
-## Recommended Model Setup
-
-Since the Pi is just the Gateway (models run in the cloud), use API-based models:
-
-```json
-{
-  "agents": {
-    "defaults": {
-      "model": {
-        "primary": "anthropic/claude-sonnet-4-20250514",
-        "fallbacks": ["openai/gpt-4o-mini"]
-      }
-    }
-  }
-}
-```
-
-**Don't try to run local LLMs on a Pi** — even small models are too slow. Let Claude/GPT do the heavy lifting.
-
----
-
-## Auto-Start on Boot
-
-The onboarding wizard sets this up, but to verify:
-
-```bash
-# Check service is enabled
-sudo systemctl is-enabled symi
-
-# Enable if not
-sudo systemctl enable symi
-
-# Start on boot
-sudo systemctl start symi
-```
-
----
-
-## Troubleshooting
-
-### Out of Memory (OOM)
-
-```bash
-# Check memory
-free -h
-
-# Add more swap (see Step 5)
-# Or reduce services running on the Pi
-```
-
-### Slow Performance
-
-- Use USB SSD instead of SD card
-- Disable unused services: `sudo systemctl disable cups bluetooth avahi-daemon`
-- Check CPU throttling: `vcgencmd get_throttled` (should return `0x0`)
-
-### Service Won't Start
-
-```bash
-# Check logs
-journalctl -u symi --no-pager -n 100
-
-# Common fix: rebuild
-cd ~/symi  # if using hackable install
-npm run build
-sudo systemctl restart symi
-```
-
-### ARM Binary Issues
-
-If a skill fails with "exec format error":
-
-1. Check if the binary has an ARM64 build
-2. Try building from source
-3. Or use a Docker container with ARM support
-
-### WiFi Drops
-
-For headless Pis on WiFi:
-
-```bash
-# Disable WiFi power management
-sudo iwconfig wlan0 power off
-
-# Make permanent
-echo 'wireless-power off' | sudo tee -a /etc/network/interfaces
-```
-
----
-
-## Cost Comparison
-
-| Setup          | One-Time Cost | Monthly Cost | Notes                     |
-| -------------- | ------------- | ------------ | ------------------------- |
-| **Pi 4 (2GB)** | ~$45          | $0           | + power (~$5/yr)          |
-| **Pi 4 (4GB)** | ~$55          | $0           | Recommended               |
-| **Pi 5 (4GB)** | ~$60          | $0           | Best performance          |
-| **Pi 5 (8GB)** | ~$80          | $0           | Overkill but future-proof |
-| DigitalOcean   | $0            | $6/mo        | $72/year                  |
-| Hetzner        | $0            | €3.79/mo     | ~$50/year                 |
-
-**Break-even:** A Pi pays for itself in ~6-12 months vs cloud VPS.
-
----
-
-## See Also
-
-- [Linux guide](/platforms/linux) — general Linux setup
-- [DigitalOcean guide](/platforms/digitalocean) — cloud alternative
-- [Hetzner guide](/install/hetzner) — Docker setup
-- [Tailscale](/gateway/tailscale) — remote access
-- [Nodes](/nodes) — pair your laptop/phone with the Pi gateway

package/docs/platforms/windows.md

@@ -1,159 +0,0 @@
----
-summary: "Windows (WSL2) support + companion app status"
-read_when:
-  - Installing Symi on Windows
-  - Looking for Windows companion app status
-title: "Windows (WSL2)"
----
-
-# Windows (WSL2)
-
-Symi on Windows is recommended **via WSL2** (Ubuntu recommended). The
-CLI + Gateway run inside Linux, which keeps the runtime consistent and makes
-tooling far more compatible (Node/Bun/pnpm, Linux binaries, skills). Native
-Windows might be trickier. WSL2 gives you the full Linux experience — one command
-to install: `wsl --install`.
-
-Native Windows companion apps are planned.
-
-## Install (WSL2)
-
-- [Getting Started](/start/getting-started) (use inside WSL)
-- [Install & updates](/install/updating)
-- Official WSL2 guide (Microsoft): [https://learn.microsoft.com/windows/wsl/install](https://learn.microsoft.com/windows/wsl/install)
-
-## Gateway
-
-- [Gateway runbook](/gateway)
-- [Configuration](/gateway/configuration)
-
-## Gateway service install (CLI)
-
-Inside WSL2:
-
-```
-symi onboard --install-daemon
-```
-
-Or:
-
-```
-symi gateway install
-```
-
-Or:
-
-```
-symi configure
-```
-
-Select **Gateway service** when prompted.
-
-Repair/migrate:
-
-```
-symi doctor
-```
-
-## Advanced: expose WSL services over LAN (portproxy)
-
-WSL has its own virtual network. If another machine needs to reach a service
-running **inside WSL** (SSH, a local TTS server, or the Gateway), you must
-forward a Windows port to the current WSL IP. The WSL IP changes after restarts,
-so you may need to refresh the forwarding rule.
-
-Example (PowerShell **as Administrator**):
-
-```powershell
-$Distro = "Ubuntu-24.04"
-$ListenPort = 2222
-$TargetPort = 22
-
-$WslIp = (wsl -d $Distro -- hostname -I).Trim().Split(" ")[0]
-if (-not $WslIp) { throw "WSL IP not found." }
-
-netsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=$ListenPort `
-  connectaddress=$WslIp connectport=$TargetPort
-```
-
-Allow the port through Windows Firewall (one-time):
-
-```powershell
-New-NetFirewallRule -DisplayName "WSL SSH $ListenPort" -Direction Inbound `
-  -Protocol TCP -LocalPort $ListenPort -Action Allow
-```
-
-Refresh the portproxy after WSL restarts:
-
-```powershell
-netsh interface portproxy delete v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 | Out-Null
-netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.0 `
-  connectaddress=$WslIp connectport=$TargetPort | Out-Null
-```
-
-Notes:
-
-- SSH from another machine targets the **Windows host IP** (example: `ssh user@windows-host -p 2222`).
-- Remote nodes must point at a **reachable** Gateway URL (not `127.0.0.1`); use
-  `symi status --all` to confirm.
-- Use `listenaddress=0.0.0.0` for LAN access; `127.0.0.1` keeps it local only.
-- If you want this automatic, register a Scheduled Task to run the refresh
-  step at login.
-
-## Step-by-step WSL2 install
-
-### 1) Install WSL2 + Ubuntu
-
-Open PowerShell (Admin):
-
-```powershell
-wsl --install
-# Or pick a distro explicitly:
-wsl --list --online
-wsl --install -d Ubuntu-24.04
-```
-
-Reboot if Windows asks.
-
-### 2) Enable systemd (required for gateway install)
-
-In your WSL terminal:
-
-```bash
-sudo tee /etc/wsl.conf >/dev/null <<'EOF'
-[boot]
-systemd=true
-EOF
-```
-
-Then from PowerShell:
-
-```powershell
-wsl --shutdown
-```
-
-Re-open Ubuntu, then verify:
-
-```bash
-systemctl --user status
-```
-
-### 3) Install Symi (inside WSL)
-
-Follow the Linux Getting Started flow inside WSL:
-
-```bash
-git clone https://github.com/symi/symi.git
-cd symi
-pnpm install
-pnpm ui:build # auto-installs UI deps on first run
-pnpm build
-symi onboard
-```
-
-Full guide: [Getting Started](/start/getting-started)
-
-## Windows companion app
-
-We do not have a Windows companion app yet. Contributions are welcome if you want
-contributions to make it happen.

package/docs/plugins/agent-tools.md

@@ -1,99 +0,0 @@
----
-summary: "Write agent tools in a plugin (schemas, optional tools, allowlists)"
-read_when:
-  - You want to add a new agent tool in a plugin
-  - You need to make a tool opt-in via allowlists
-title: "Plugin Agent Tools"
----
-
-# Plugin agent tools
-
-Symi plugins can register **agent tools** (JSON‑schema functions) that are exposed
-to the LLM during agent runs. Tools can be **required** (always available) or
-**optional** (opt‑in).
-
-Agent tools are configured under `tools` in the main config, or per‑agent under
-`agents.list[].tools`. The allowlist/denylist policy controls which tools the agent
-can call.
-
-## Basic tool
-
-```ts
-import { Type } from "@sinclair/typebox";
-
-export default function (api) {
-  api.registerTool({
-    name: "my_tool",
-    description: "Do a thing",
-    parameters: Type.Object({
-      input: Type.String(),
-    }),
-    async execute(_id, params) {
-      return { content: [{ type: "text", text: params.input }] };
-    },
-  });
-}
-```
-
-## Optional tool (opt‑in)
-
-Optional tools are **never** auto‑enabled. Users must add them to an agent
-allowlist.
-
-```ts
-export default function (api) {
-  api.registerTool(
-    {
-      name: "workflow_tool",
-      description: "Run a local workflow",
-      parameters: {
-        type: "object",
-        properties: {
-          pipeline: { type: "string" },
-        },
-        required: ["pipeline"],
-      },
-      async execute(_id, params) {
-        return { content: [{ type: "text", text: params.pipeline }] };
-      },
-    },
-    { optional: true },
-  );
-}
-```
-
-Enable optional tools in `agents.list[].tools.allow` (or global `tools.allow`):
-
-```json5
-{
-  agents: {
-    list: [
-      {
-        id: "main",
-        tools: {
-          allow: [
-            "workflow_tool", // specific tool name
-            "workflow", // plugin id (enables all tools from that plugin)
-            "group:plugins", // all plugin tools
-          ],
-        },
-      },
-    ],
-  },
-}
-```
-
-Other config knobs that affect tool availability:
-
-- Allowlists that only name plugin tools are treated as plugin opt-ins; core tools remain
-  enabled unless you also include core tools or groups in the allowlist.
-- `tools.profile` / `agents.list[].tools.profile` (base allowlist)
-- `tools.byProvider` / `agents.list[].tools.byProvider` (provider‑specific allow/deny)
-- `tools.sandbox.tools.*` (sandbox tool policy when sandboxed)
-
-## Rules + tips
-
-- Tool names must **not** clash with core tool names; conflicting tools are skipped.
-- Plugin ids used in allowlists must not clash with core tool names.
-- Prefer `optional: true` for tools that trigger side effects or require extra
-  binaries/credentials.

package/docs/plugins/community.md

@@ -1,44 +0,0 @@
----
-summary: "Community plugins: quality bar, hosting requirements, and PR submission path"
-read_when:
-  - You want to publish a third-party Symi plugin
-  - You want to propose a plugin for docs listing
-title: "Community plugins"
----
-
-# Community plugins
-
-This page tracks high-quality **community-maintained plugins** for Symi.
-
-We accept PRs that add community plugins here when they meet the quality bar.
-
-## Required for listing
-
-- Plugin package is published on npmjs (installable via `symi plugins install <npm-spec>`).
-- Source code is hosted on GitHub (public repository).
-- Repository includes setup/use docs and an issue tracker.
-- Plugin has a clear maintenance signal (active maintainer, recent updates, or responsive issue handling).
-
-## How to submit
-
-Open a PR that adds your plugin to this page with:
-
-- Plugin name
-- npm package name
-- GitHub repository URL
-- One-line description
-- Install command
-
-## Review bar
-
-We prefer plugins that are useful, documented, and safe to operate.
-Low-effort wrappers, unclear ownership, or unmaintained packages may be declined.
-
-## Candidate format
-
-Use this format when adding entries:
-
-- **Plugin Name** — short description
-  npm: `@scope/package`
-  repo: `https://github.com/org/repo`
-  install: `symi plugins install @scope/package`