@symerian/symi 3.0.20 → 3.0.22

package/docs/install/ansible.md

@@ -1,207 +0,0 @@
----
-summary: "Automated, hardened Symi installation with Ansible, Tailscale VPN, and firewall isolation"
-read_when:
-  - You want automated server deployment with security hardening
-  - You need firewall-isolated setup with VPN access
-  - You're deploying to remote Debian/Ubuntu servers
-title: "Ansible"
----
-
-# Ansible Installation
-
-The recommended way to deploy Symi to production servers is via **[symi-ansible](https://github.com/symi/symi-ansible)** — an automated installer with security-first architecture.
-
-## Quick Start
-
-One-command install:
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/symi/symi-ansible/main/install.sh | bash
-```
-
-> **📦 Full guide: [github.com/symi/symi-ansible](https://github.com/symi/symi-ansible)**
->
-> The symi-ansible repo is the source of truth for Ansible deployment. This page is a quick overview.
-
-## What You Get
-
-- 🔒 **Firewall-first security**: UFW + Docker isolation (only SSH + Tailscale accessible)
-- 🔐 **Tailscale VPN**: Secure remote access without exposing services publicly
-- 🐳 **Docker**: Isolated sandbox containers, localhost-only bindings
-- 🛡️ **Defense in depth**: 4-layer security architecture
-- 🚀 **One-command setup**: Complete deployment in minutes
-- 🔧 **Systemd integration**: Auto-start on boot with hardening
-
-## Requirements
-
-- **OS**: Debian 11+ or Ubuntu 20.04+
-- **Access**: Root or sudo privileges
-- **Network**: Internet connection for package installation
-- **Ansible**: 2.14+ (installed automatically by quick-start script)
-
-## What Gets Installed
-
-The Ansible playbook installs and configures:
-
-1. **Tailscale** (mesh VPN for secure remote access)
-2. **UFW firewall** (SSH + Tailscale ports only)
-3. **Docker CE + Compose V2** (for agent sandboxes)
-4. **Node.js 22.x + pnpm** (runtime dependencies)
-5. **Symi** (host-based, not containerized)
-6. **Systemd service** (auto-start with security hardening)
-
-Note: The gateway runs **directly on the host** (not in Docker), but agent sandboxes use Docker for isolation. See [Sandboxing](/gateway/sandboxing) for details.
-
-## Post-Install Setup
-
-After installation completes, switch to the symi user:
-
-```bash
-sudo -i -u symi
-```
-
-The post-install script will guide you through:
-
-1. **Onboarding wizard**: Configure Symi settings
-2. **Gateway testing**: Verify the installation
-3. **Tailscale setup**: Connect to your VPN mesh
-
-### Quick commands
-
-```bash
-# Check service status
-sudo systemctl status symi
-
-# View live logs
-sudo journalctl -u symi -f
-
-# Restart gateway
-sudo systemctl restart symi
-
-# Provider login (run as symi user)
-sudo -i -u symi
-symi channels login
-```
-
-## Security Architecture
-
-### 4-Layer Defense
-
-1. **Firewall (UFW)**: Only SSH (22) + Tailscale (41641/udp) exposed publicly
-2. **VPN (Tailscale)**: Gateway accessible only via VPN mesh
-3. **Docker Isolation**: DOCKER-USER iptables chain prevents external port exposure
-4. **Systemd Hardening**: NoNewPrivileges, PrivateTmp, unprivileged user
-
-### Verification
-
-Test external attack surface:
-
-```bash
-nmap -p- YOUR_SERVER_IP
-```
-
-Should show **only port 22** (SSH) open. All other services (gateway, Docker) are locked down.
-
-### Docker Availability
-
-Docker is installed for **agent sandboxes** (isolated tool execution), not for running the gateway itself. The gateway binds to localhost only and is accessible via Tailscale VPN.
-
-See [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) for sandbox configuration.
-
-## Manual Installation
-
-If you prefer manual control over the automation:
-
-```bash
-# 1. Install prerequisites
-sudo apt update && sudo apt install -y ansible git
-
-# 2. Clone repository
-git clone https://github.com/symi/symi-ansible.git
-cd symi-ansible
-
-# 3. Install Ansible collections
-ansible-galaxy collection install -r requirements.yml
-
-# 4. Run playbook
-./run-playbook.sh
-
-# Or run directly (then manually execute /tmp/symi-setup.sh after)
-# ansible-playbook playbook.yml --ask-become-pass
-```
-
-## Updating Symi
-
-The Ansible installer sets up Symi for manual updates. See [Updating](/install/updating) for the standard update flow.
-
-To re-run the Ansible playbook (e.g., for configuration changes):
-
-```bash
-cd symi-ansible
-./run-playbook.sh
-```
-
-Note: This is idempotent and safe to run multiple times.
-
-## Troubleshooting
-
-### Firewall blocks my connection
-
-If you're locked out:
-
-- Ensure you can access via Tailscale VPN first
-- SSH access (port 22) is always allowed
-- The gateway is **only** accessible via Tailscale by design
-
-### Service won't start
-
-```bash
-# Check logs
-sudo journalctl -u symi -n 100
-
-# Verify permissions
-sudo ls -la /opt/symi
-
-# Test manual start
-sudo -i -u symi
-cd ~/symi
-pnpm start
-```
-
-### Docker sandbox issues
-
-```bash
-# Verify Docker is running
-sudo systemctl status docker
-
-# Check sandbox image
-sudo docker images | grep symi-sandbox
-
-# Build sandbox image if missing
-cd /opt/symi/symi
-sudo -u symi ./scripts/sandbox-setup.sh
-```
-
-### Provider login fails
-
-Make sure you're running as the `symi` user:
-
-```bash
-sudo -i -u symi
-symi channels login
-```
-
-## Advanced Configuration
-
-For detailed security architecture and troubleshooting:
-
-- [Security Architecture](https://github.com/symi/symi-ansible/blob/main/docs/security.md)
-- [Technical Details](https://github.com/symi/symi-ansible/blob/main/docs/architecture.md)
-- [Troubleshooting Guide](https://github.com/symi/symi-ansible/blob/main/docs/troubleshooting.md)
-
-## Related
-
-- [symi-ansible](https://github.com/symi/symi-ansible) — full deployment guide
-- [Docker](/install/docker) — containerized gateway setup
-- [Sandboxing](/gateway/sandboxing) — agent sandbox configuration
-- [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) — per-agent isolation

package/docs/install/bun.md

@@ -1,59 +0,0 @@
----
-summary: "Bun workflow (experimental): installs and gotchas vs pnpm"
-read_when:
-  - You want the fastest local dev loop (bun + watch)
-  - You hit Bun install/patch/lifecycle script issues
-title: "Bun (Experimental)"
----
-
-# Bun (experimental)
-
-Goal: run this repo with **Bun** (optional, not recommended for WhatsApp/Telegram)
-without diverging from pnpm workflows.
-
-⚠️ **Not recommended for Gateway runtime** (WhatsApp/Telegram bugs). Use Node for production.
-
-## Status
-
-- Bun is an optional local runtime for running TypeScript directly (`bun run …`, `bun --watch …`).
-- `pnpm` is the default for builds and remains fully supported (and used by some docs tooling).
-- Bun cannot use `pnpm-lock.yaml` and will ignore it.
-
-## Install
-
-Default:
-
-```sh
-bun install
-```
-
-Note: `bun.lock`/`bun.lockb` are gitignored, so there’s no repo churn either way. If you want _no lockfile writes_:
-
-```sh
-bun install --no-save
-```
-
-## Build / Test (Bun)
-
-```sh
-bun run build
-bun run vitest run
-```
-
-## Bun lifecycle scripts (blocked by default)
-
-Bun may block dependency lifecycle scripts unless explicitly trusted (`bun pm untrusted` / `bun pm trust`).
-For this repo, the commonly blocked scripts are not required:
-
-- `@whiskeysockets/baileys` `preinstall`: checks Node major >= 20 (we run Node 22+).
-- `protobufjs` `postinstall`: emits warnings about incompatible version schemes (no build artifacts).
-
-If you hit a real runtime issue that requires these scripts, trust them explicitly:
-
-```sh
-bun pm trust @whiskeysockets/baileys protobufjs
-```
-
-## Caveats
-
-- Some scripts still hardcode pnpm (e.g. `docs:build`, `ui:*`, `protocol:check`). Run those via pnpm for now.

package/docs/install/development-channels.md

@@ -1,75 +0,0 @@
----
-summary: "Stable, beta, and dev channels: semantics, switching, and tagging"
-read_when:
-  - You want to switch between stable/beta/dev
-  - You are tagging or publishing prereleases
-title: "Development Channels"
----
-
-# Development channels
-
-Last updated: 2026-01-21
-
-Symi ships three update channels:
-
-- **stable**: npm dist-tag `latest`.
-- **beta**: npm dist-tag `beta` (builds under test).
-- **dev**: moving head of `main` (git). npm dist-tag: `dev` (when published).
-
-We ship builds to **beta**, test them, then **promote a vetted build to `latest`**
-without changing the version number — dist-tags are the source of truth for npm installs.
-
-## Switching channels
-
-Git checkout:
-
-```bash
-symi update --channel stable
-symi update --channel beta
-symi update --channel dev
-```
-
-- `stable`/`beta` check out the latest matching tag (often the same tag).
-- `dev` switches to `main` and rebases on the upstream.
-
-npm/pnpm global install:
-
-```bash
-symi update --channel stable
-symi update --channel beta
-symi update --channel dev
-```
-
-This updates via the corresponding npm dist-tag (`latest`, `beta`, `dev`).
-
-When you **explicitly** switch channels with `--channel`, Symi also aligns
-the install method:
-
-- `dev` ensures a git checkout (default `~/symi`, override with `SYMI_GIT_DIR`),
-  updates it, and installs the global CLI from that checkout.
-- `stable`/`beta` installs from npm using the matching dist-tag.
-
-Tip: if you want stable + dev in parallel, keep two clones and point your gateway at the stable one.
-
-## Plugins and channels
-
-When you switch channels with `symi update`, Symi also syncs plugin sources:
-
-- `dev` prefers bundled plugins from the git checkout.
-- `stable` and `beta` restore npm-installed plugin packages.
-
-## Tagging best practices
-
-- Tag releases you want git checkouts to land on (`vYYYY.M.D` or `vYYYY.M.D-<patch>`).
-- Keep tags immutable: never move or reuse a tag.
-- npm dist-tags remain the source of truth for npm installs:
-  - `latest` → stable
-  - `beta` → candidate build
-  - `dev` → main snapshot (optional)
-
-## macOS app availability
-
-Beta and dev builds may **not** include a macOS app release. That’s OK:
-
-- The git tag and npm dist-tag can still be published.
-- Call out “no macOS build for this beta” in release notes or changelog.