@symerian/symi 3.0.20 → 3.0.22

package/docs/security/formal-verification.md

@@ -1,164 +0,0 @@
----
-title: Formal Verification (Security Models)
-summary: Machine-checked security models for Symi’s highest-risk paths.
-permalink: /security/formal-verification/
----
-
-# Formal Verification (Security Models)
-
-This page tracks Symi’s **formal security models** (TLA+/TLC today; more as needed).
-
-> Note: some older links may refer to the previous project name.
-
-**Goal (north star):** provide a machine-checked argument that Symi enforces its
-intended security policy (authorization, session isolation, tool gating, and
-misconfiguration safety), under explicit assumptions.
-
-**What this is (today):** an executable, attacker-driven **security regression suite**:
-
-- Each claim has a runnable model-check over a finite state space.
-- Many claims have a paired **negative model** that produces a counterexample trace for a realistic bug class.
-
-**What this is not (yet):** a proof that “Symi is secure in all respects” or that the full TypeScript implementation is correct.
-
-## Where the models live
-
-Models are maintained in a separate repo: [vignesh07/symi-formal-models](https://github.com/vignesh07/symi-formal-models).
-
-## Important caveats
-
-- These are **models**, not the full TypeScript implementation. Drift between model and code is possible.
-- Results are bounded by the state space explored by TLC; “green” does not imply security beyond the modeled assumptions and bounds.
-- Some claims rely on explicit environmental assumptions (e.g., correct deployment, correct configuration inputs).
-
-## Reproducing results
-
-Today, results are reproduced by cloning the models repo locally and running TLC (see below). A future iteration could offer:
-
-- CI-run models with public artifacts (counterexample traces, run logs)
-- a hosted “run this model” workflow for small, bounded checks
-
-Getting started:
-
-```bash
-git clone https://github.com/vignesh07/symi-formal-models
-cd symi-formal-models
-
-# Java 11+ required (TLC runs on the JVM).
-# The repo vendors a pinned `tla2tools.jar` (TLA+ tools) and provides `bin/tlc` + Make targets.
-
-make <target>
-```
-
-### Gateway exposure and open gateway misconfiguration
-
-**Claim:** binding beyond loopback without auth can make remote compromise possible / increases exposure; token/password blocks unauth attackers (per the model assumptions).
-
-- Green runs:
-  - `make gateway-exposure-v2`
-  - `make gateway-exposure-v2-protected`
-- Red (expected):
-  - `make gateway-exposure-v2-negative`
-
-See also: `docs/gateway-exposure-matrix.md` in the models repo.
-
-### Nodes.run pipeline (highest-risk capability)
-
-**Claim:** `nodes.run` requires (a) node command allowlist plus declared commands and (b) live approval when configured; approvals are tokenized to prevent replay (in the model).
-
-- Green runs:
-  - `make nodes-pipeline`
-  - `make approvals-token`
-- Red (expected):
-  - `make nodes-pipeline-negative`
-  - `make approvals-token-negative`
-
-### Pairing store (DM gating)
-
-**Claim:** pairing requests respect TTL and pending-request caps.
-
-- Green runs:
-  - `make pairing`
-  - `make pairing-cap`
-- Red (expected):
-  - `make pairing-negative`
-  - `make pairing-cap-negative`
-
-### Ingress gating (mentions + control-command bypass)
-
-**Claim:** in group contexts requiring mention, an unauthorized “control command” cannot bypass mention gating.
-
-- Green:
-  - `make ingress-gating`
-- Red (expected):
-  - `make ingress-gating-negative`
-
-### Routing/session-key isolation
-
-**Claim:** DMs from distinct peers do not collapse into the same session unless explicitly linked/configured.
-
-- Green:
-  - `make routing-isolation`
-- Red (expected):
-  - `make routing-isolation-negative`
-
-## v1++: additional bounded models (concurrency, retries, trace correctness)
-
-These are follow-on models that tighten fidelity around real-world failure modes (non-atomic updates, retries, and message fan-out).
-
-### Pairing store concurrency / idempotency
-
-**Claim:** a pairing store should enforce `MaxPending` and idempotency even under interleavings (i.e., “check-then-write” must be atomic / locked; refresh shouldn’t create duplicates).
-
-What it means:
-
-- Under concurrent requests, you can’t exceed `MaxPending` for a channel.
-- Repeated requests/refreshes for the same `(channel, sender)` should not create duplicate live pending rows.
-
-- Green runs:
-  - `make pairing-race` (atomic/locked cap check)
-  - `make pairing-idempotency`
-  - `make pairing-refresh`
-  - `make pairing-refresh-race`
-- Red (expected):
-  - `make pairing-race-negative` (non-atomic begin/commit cap race)
-  - `make pairing-idempotency-negative`
-  - `make pairing-refresh-negative`
-  - `make pairing-refresh-race-negative`
-
-### Ingress trace correlation / idempotency
-
-**Claim:** ingestion should preserve trace correlation across fan-out and be idempotent under provider retries.
-
-What it means:
-
-- When one external event becomes multiple internal messages, every part keeps the same trace/event identity.
-- Retries do not result in double-processing.
-- If provider event IDs are missing, dedupe falls back to a safe key (e.g., trace ID) to avoid dropping distinct events.
-
-- Green:
-  - `make ingress-trace`
-  - `make ingress-trace2`
-  - `make ingress-idempotency`
-  - `make ingress-dedupe-fallback`
-- Red (expected):
-  - `make ingress-trace-negative`
-  - `make ingress-trace2-negative`
-  - `make ingress-idempotency-negative`
-  - `make ingress-dedupe-fallback-negative`
-
-### Routing dmScope precedence + identityLinks
-
-**Claim:** routing must keep DM sessions isolated by default, and only collapse sessions when explicitly configured (channel precedence + identity links).
-
-What it means:
-
-- Channel-specific dmScope overrides must win over global defaults.
-- identityLinks should collapse only within explicit linked groups, not across unrelated peers.
-
-- Green:
-  - `make routing-precedence`
-  - `make routing-identitylinks`
-- Red (expected):
-  - `make routing-precedence-negative`
-  - `make routing-identitylinks-negative`

package/docs/start/bootstrapping.md

@@ -1,41 +0,0 @@
----
-summary: "Agent bootstrapping ritual that seeds the workspace and identity files"
-read_when:
-  - Understanding what happens on the first agent run
-  - Explaining where bootstrapping files live
-  - Debugging onboarding identity setup
-title: "Agent Bootstrapping"
-sidebarTitle: "Bootstrapping"
----
-
-# Agent Bootstrapping
-
-Bootstrapping is the **first‑run** ritual that prepares an agent workspace and
-collects identity details. It happens after onboarding, when the agent starts
-for the first time.
-
-## What bootstrapping does
-
-On the first agent run, Symi bootstraps the workspace (default
-`~/.symi/workspace`):
-
-- Seeds `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`.
-- Runs a short Q&A ritual (one question at a time).
-- Writes identity + preferences to `IDENTITY.md`, `USER.md`, `SYMICORE.md`.
-- Removes `BOOTSTRAP.md` when finished so it only runs once.
-
-## Where it runs
-
-Bootstrapping always runs on the **gateway host**. If the macOS app connects to
-a remote Gateway, the workspace and bootstrapping files live on that remote
-machine.
-
-<Note>
-When the Gateway runs on another machine, edit workspace files on the gateway
-host (for example, `user@gateway-host:~/.symi/workspace`).
-</Note>
-
-## Related docs
-
-- macOS app onboarding: [Onboarding](/start/onboarding)
-- Workspace layout: [Agent workspace](/concepts/agent-workspace)

package/docs/start/docs-directory.md

@@ -1,63 +0,0 @@
----
-summary: "Curated links to the most used Symi docs."
-read_when:
-  - You want quick access to key docs pages
-title: "Docs directory"
----
-
-<Note>
-This page is a curated index. If you are new, start with [Getting Started](/start/getting-started).
-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)](/channels/pairing)
-- [Nix mode](/install/nix)
-- [Symi assistant setup](/start/symi)
-- [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)
-- [Mattermost (plugin)](/channels/mattermost)
-- [BlueBubbles (iMessage)](/channels/bluebubbles)
-- [iMessage (legacy)](/channels/imessage)
-- [Groups](/channels/groups)
-- [WhatsApp group messages](/channels/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

@@ -1,135 +0,0 @@
----
-summary: "Get Symi installed and run your first chat in minutes."
-read_when:
-  - First time setup from zero
-  - You want the fastest path to a working chat
-title: "Getting Started"
----
-
-# Getting Started
-
-Goal: go from zero to a first working chat with minimal setup.
-
-<Info>
-Fastest chat: open the Control UI (no channel setup needed). Run `symi dashboard`
-and chat in the browser, or open `http://127.0.0.1:18789/` on the
-<Tooltip headline="Gateway host" tip="The machine running the Symi gateway service.">gateway host</Tooltip>.
-Docs: [Dashboard](/web/dashboard) and [Control UI](/web/control-ui).
-</Info>
-
-## Prereqs
-
-- Node 22 or newer
-
-<Tip>
-Check your Node version with `node --version` if you are unsure.
-</Tip>
-
-## Quick setup (CLI)
-
-<Steps>
-  <Step title="Install Symi (recommended)">
-    <Tabs>
-      <Tab title="macOS/Linux">
-        ```bash
-        curl -fsSL https://jaysteelmind.github.io/getsymi/install.sh | bash
-        ```
-        <img
-  src="/assets/install-script.svg"
-  alt="Install Script Process"
-  className="rounded-lg"
-/>
-      </Tab>
-      <Tab title="Windows (PowerShell)">
-        ```powershell
-        iwr -useb https://jaysteelmind.github.io/getsymi/install.ps1 | iex
-        ```
-      </Tab>
-    </Tabs>
-
-    <Note>
-    Other install methods and requirements: [Install](/install).
-    </Note>
-
-  </Step>
-  <Step title="Run the onboarding wizard">
-    ```bash
-    symi onboard --install-daemon
-    ```
-
-    The wizard configures auth, gateway settings, and optional channels.
-    See [Onboarding Wizard](/start/wizard) for details.
-
-  </Step>
-  <Step title="Check the Gateway">
-    If you installed the service, it should already be running:
-
-    ```bash
-    symi gateway status
-    ```
-
-  </Step>
-  <Step title="Open the Control UI">
-    ```bash
-    symi dashboard
-    ```
-  </Step>
-</Steps>
-
-<Check>
-If the Control UI loads, your Gateway is ready for use.
-</Check>
-
-## Optional checks and extras
-
-<AccordionGroup>
-  <Accordion title="Run the Gateway in the foreground">
-    Useful for quick tests or troubleshooting.
-
-    ```bash
-    symi gateway --port 18789
-    ```
-
-  </Accordion>
-  <Accordion title="Send a test message">
-    Requires a configured channel.
-
-    ```bash
-    symi message send --target +15555550123 --message "Hello from Symi"
-    ```
-
-  </Accordion>
-</AccordionGroup>
-
-## Useful environment variables
-
-If you run Symi as a service account or want custom config/state locations:
-
-- `SYMI_HOME` sets the home directory used for internal path resolution.
-- `SYMI_STATE_DIR` overrides the state directory.
-- `SYMI_CONFIG_PATH` overrides the config file path.
-
-Full environment variable reference: [Environment vars](/help/environment).
-
-## Go deeper
-
-<Columns>
-  <Card title="Onboarding Wizard (details)" href="/start/wizard">
-    Full CLI wizard reference and advanced options.
-  </Card>
-  <Card title="macOS app onboarding" href="/start/onboarding">
-    First run flow for the macOS app.
-  </Card>
-</Columns>
-
-## What you will have
-
-- A running Gateway
-- Auth configured
-- Control UI access or a connected channel
-
-## Next steps
-
-- DM safety and approvals: [Pairing](/channels/pairing)
-- Connect more channels: [Channels](/channels)
-- Advanced workflows and from source: [Setup](/start/setup)

package/docs/start/hubs.md

@@ -1,196 +0,0 @@
----
-summary: "Hubs that link to every Symi doc"
-read_when:
-  - You want a complete map of the documentation
-title: "Docs Hubs"
----
-
-# Docs hubs
-
-<Note>
-If you are new to Symi, start with [Getting Started](/start/getting-started).
-</Note>
-
-Use these hubs to discover every page, including deep dives and reference docs that don’t appear in the left nav.
-
-## Start here
-
-- [Index](/)
-- [Getting Started](/start/getting-started)
-- [Quick start](/start/quickstart)
-- [Onboarding](/start/onboarding)
-- [Wizard](/start/wizard)
-- [Setup](/start/setup)
-- [Dashboard (local Gateway)](http://127.0.0.1:18789/)
-- [Help](/help)
-- [Docs directory](/start/docs-directory)
-- [Configuration](/gateway/configuration)
-- [Configuration examples](/gateway/configuration-examples)
-- [Symi assistant](/start/symi)
-- [Showcase](/start/showcase)
-- [Lore](/start/lore)
-
-## Installation + updates
-
-- [Docker](/install/docker)
-- [Nix](/install/nix)
-- [Updating / rollback](/install/updating)
-- [Bun workflow (experimental)](/install/bun)
-
-## Core concepts
-
-- [Architecture](/concepts/architecture)
-- [Features](/concepts/features)
-- [Network hub](/network)
-- [Agent runtime](/concepts/agent)
-- [Agent workspace](/concepts/agent-workspace)
-- [Memory](/concepts/memory)
-- [Agent loop](/concepts/agent-loop)
-- [Streaming + chunking](/concepts/streaming)
-- [Multi-agent routing](/concepts/multi-agent)
-- [Compaction](/concepts/compaction)
-- [Sessions](/concepts/session)
-- [Sessions (alias)](/concepts/sessions)
-- [Session pruning](/concepts/session-pruning)
-- [Session tools](/concepts/session-tool)
-- [Queue](/concepts/queue)
-- [Slash commands](/tools/slash-commands)
-- [RPC adapters](/reference/rpc)
-- [TypeBox schemas](/concepts/typebox)
-- [Timezone handling](/concepts/timezone)
-- [Presence](/concepts/presence)
-- [Discovery + transports](/gateway/discovery)
-- [Bonjour](/gateway/bonjour)
-- [Channel routing](/channels/channel-routing)
-- [Groups](/channels/groups)
-- [Group messages](/channels/group-messages)
-- [Model failover](/concepts/model-failover)
-- [OAuth](/concepts/oauth)
-
-## Providers + ingress
-
-- [Chat channels hub](/channels)
-- [Model providers hub](/providers/models)
-- [WhatsApp](/channels/whatsapp)
-- [Telegram](/channels/telegram)
-- [Telegram (grammY notes)](/channels/grammy)
-- [Slack](/channels/slack)
-- [Mattermost](/channels/mattermost) (plugin)
-- [Signal](/channels/signal)
-- [BlueBubbles (iMessage)](/channels/bluebubbles)
-- [iMessage (legacy)](/channels/imessage)
-- [Location parsing](/channels/location)
-- [WebChat](/web/webchat)
-- [Webhooks](/automation/webhook)
-- [Gmail Pub/Sub](/automation/gmail-pubsub)
-
-## Gateway + operations
-
-- [Gateway runbook](/gateway)
-- [Network model](/gateway/network-model)
-- [Gateway pairing](/gateway/pairing)
-- [Gateway lock](/gateway/gateway-lock)
-- [Background process](/gateway/background-process)
-- [Health](/gateway/health)
-- [Heartbeat](/gateway/heartbeat)
-- [Doctor](/gateway/doctor)
-- [Logging](/gateway/logging)
-- [Sandboxing](/gateway/sandboxing)
-- [Dashboard](/web/dashboard)
-- [Control UI](/web/control-ui)
-- [Remote access](/gateway/remote)
-- [Remote gateway README](/gateway/remote-gateway-readme)
-- [Tailscale](/gateway/tailscale)
-- [Security](/gateway/security)
-- [Troubleshooting](/gateway/troubleshooting)
-
-## Tools + automation
-
-- [Tools surface](/tools)
-- [OpenProse](/prose)
-- [CLI reference](/cli)
-- [Exec tool](/tools/exec)
-- [Elevated mode](/tools/elevated)
-- [Cron jobs](/automation/cron-jobs)
-- [Cron vs Heartbeat](/automation/cron-vs-heartbeat)
-- [Thinking + verbose](/tools/thinking)
-- [Models](/concepts/models)
-- [Sub-agents](/tools/subagents)
-- [Agent send CLI](/tools/agent-send)
-- [Terminal UI](/web/tui)
-- [Browser control](/tools/browser)
-- [Browser (Linux troubleshooting)](/tools/browser-linux-troubleshooting)
-- [Polls](/automation/poll)
-
-## Nodes, media, voice
-
-- [Nodes overview](/nodes)
-- [Camera](/nodes/camera)
-- [Images](/nodes/images)
-- [Audio](/nodes/audio)
-- [Location command](/nodes/location-command)
-- [Voice wake](/nodes/voicewake)
-- [Talk mode](/nodes/talk)
-
-## Platforms
-
-- [Platforms overview](/platforms)
-- [macOS](/platforms/macos)
-- [iOS](/platforms/ios)
-- [Android](/platforms/android)
-- [Windows (WSL2)](/platforms/windows)
-- [Linux](/platforms/linux)
-- [Web surfaces](/web)
-
-## macOS companion app (advanced)
-
-- [macOS dev setup](/platforms/mac/dev-setup)
-- [macOS menu bar](/platforms/mac/menu-bar)
-- [macOS voice wake](/platforms/mac/voicewake)
-- [macOS voice overlay](/platforms/mac/voice-overlay)
-- [macOS WebChat](/platforms/mac/webchat)
-- [macOS Canvas](/platforms/mac/canvas)
-- [macOS child process](/platforms/mac/child-process)
-- [macOS health](/platforms/mac/health)
-- [macOS icon](/platforms/mac/icon)
-- [macOS logging](/platforms/mac/logging)
-- [macOS permissions](/platforms/mac/permissions)
-- [macOS remote](/platforms/mac/remote)
-- [macOS signing](/platforms/mac/signing)
-- [macOS release](/platforms/mac/release)
-- [macOS gateway (launchd)](/platforms/mac/bundled-gateway)
-- [macOS XPC](/platforms/mac/xpc)
-- [macOS skills](/platforms/mac/skills)
-- [macOS Peekaboo](/platforms/mac/peekaboo)
-
-## Workspace + templates
-
-- [Skills](/tools/skills)
-- [SymiHub](/tools/symihub)
-- [Skills config](/tools/skills-config)
-- [Default AGENTS](/reference/AGENTS.default)
-- [Templates: AGENTS](/reference/templates/AGENTS)
-- [Templates: BOOTSTRAP](/reference/templates/BOOTSTRAP)
-- [Templates: HEARTBEAT](/reference/templates/HEARTBEAT)
-- [Templates: IDENTITY](/reference/templates/IDENTITY)
-- [Templates: SOUL](/reference/templates/SOUL)
-- [Templates: TOOLS](/reference/templates/TOOLS)
-- [Templates: USER](/reference/templates/USER)
-
-## Experiments (exploratory)
-
-- [Onboarding config protocol](/experiments/onboarding-config-protocol)
-- [Cron hardening notes](/experiments/plans/cron-add-hardening)
-- [Group policy hardening notes](/experiments/plans/group-policy-hardening)
-- [Research: memory](/experiments/research/memory)
-- [Model config exploration](/experiments/proposals/model-config)
-
-## Project
-
-- [Credits](/reference/credits)
-
-## Testing + release
-
-- [Testing](/reference/test)
-- [Release checklist](/reference/RELEASING)
-- [Device models](/reference/device-models)