@symerian/symi 3.0.21 → 3.0.22

package/docs/help/troubleshooting.md

@@ -1,264 +0,0 @@
----
-summary: "Symptom first troubleshooting hub for Symi"
-read_when:
-  - Symi is not working and you need the fastest path to a fix
-  - You want a triage flow before diving into deep runbooks
-title: "Troubleshooting"
----
-
-# Troubleshooting
-
-If you only have 2 minutes, use this page as a triage front door.
-
-## First 60 seconds
-
-Run this exact ladder in order:
-
-```bash
-symi status
-symi status --all
-symi gateway probe
-symi gateway status
-symi doctor
-symi channels status --probe
-symi logs --follow
-```
-
-Good output in one line:
-
-- `symi status` → shows configured channels and no obvious auth errors.
-- `symi status --all` → full report is present and shareable.
-- `symi gateway probe` → expected gateway target is reachable.
-- `symi gateway status` → `Runtime: running` and `RPC probe: ok`.
-- `symi doctor` → no blocking config/service errors.
-- `symi channels status --probe` → channels report `connected` or `ready`.
-- `symi logs --follow` → steady activity, no repeating fatal errors.
-
-## Decision tree
-
-```mermaid
-flowchart TD
-  A[Symi is not working] --> B{What breaks first}
-  B --> C[No replies]
-  B --> D[Dashboard or Control UI will not connect]
-  B --> E[Gateway will not start or service not running]
-  B --> F[Channel connects but messages do not flow]
-  B --> G[Cron or heartbeat did not fire or did not deliver]
-  B --> H[Node is paired but camera canvas screen exec fails]
-  B --> I[Browser tool fails]
-
-  C --> C1[/No replies section/]
-  D --> D1[/Control UI section/]
-  E --> E1[/Gateway section/]
-  F --> F1[/Channel flow section/]
-  G --> G1[/Automation section/]
-  H --> H1[/Node tools section/]
-  I --> I1[/Browser section/]
-```
-
-<AccordionGroup>
-  <Accordion title="No replies">
-    ```bash
-    symi status
-    symi gateway status
-    symi channels status --probe
-    symi pairing list <channel>
-    symi logs --follow
-    ```
-
-    Good output looks like:
-
-    - `Runtime: running`
-    - `RPC probe: ok`
-    - Your channel shows connected/ready in `channels status --probe`
-    - Sender appears approved (or DM policy is open/allowlist)
-
-    Common log signatures:
-
-    - `pairing request` → sender is unapproved and waiting for DM pairing approval.
-    - `blocked` / `allowlist` in channel logs → sender, room, or group is filtered.
-
-    Deep pages:
-
-    - [/gateway/troubleshooting#no-replies](/gateway/troubleshooting#no-replies)
-    - [/channels/troubleshooting](/channels/troubleshooting)
-    - [/channels/pairing](/channels/pairing)
-
-  </Accordion>
-
-  <Accordion title="Dashboard or Control UI will not connect">
-    ```bash
-    symi status
-    symi gateway status
-    symi logs --follow
-    symi doctor
-    symi channels status --probe
-    ```
-
-    Good output looks like:
-
-    - `Dashboard: http://...` is shown in `symi gateway status`
-    - `RPC probe: ok`
-    - No auth loop in logs
-
-    Common log signatures:
-
-    - `device identity required` → HTTP/non-secure context cannot complete device auth.
-    - `unauthorized` / reconnect loop → wrong token/password or auth mode mismatch.
-    - `gateway connect failed:` → UI is targeting the wrong URL/port or unreachable gateway.
-
-    Deep pages:
-
-    - [/gateway/troubleshooting#dashboard-control-ui-connectivity](/gateway/troubleshooting#dashboard-control-ui-connectivity)
-    - [/web/control-ui](/web/control-ui)
-    - [/gateway/authentication](/gateway/authentication)
-
-  </Accordion>
-
-  <Accordion title="Gateway will not start or service installed but not running">
-    ```bash
-    symi status
-    symi gateway status
-    symi logs --follow
-    symi doctor
-    symi channels status --probe
-    ```
-
-    Good output looks like:
-
-    - `Service: ... (loaded)`
-    - `Runtime: running`
-    - `RPC probe: ok`
-
-    Common log signatures:
-
-    - `Gateway start blocked: set gateway.mode=local` → gateway mode is unset/remote.
-    - `refusing to bind gateway ... without auth` → non-loopback bind without token/password.
-    - `another gateway instance is already listening` or `EADDRINUSE` → port already taken.
-
-    Deep pages:
-
-    - [/gateway/troubleshooting#gateway-service-not-running](/gateway/troubleshooting#gateway-service-not-running)
-    - [/gateway/background-process](/gateway/background-process)
-    - [/gateway/configuration](/gateway/configuration)
-
-  </Accordion>
-
-  <Accordion title="Channel connects but messages do not flow">
-    ```bash
-    symi status
-    symi gateway status
-    symi logs --follow
-    symi doctor
-    symi channels status --probe
-    ```
-
-    Good output looks like:
-
-    - Channel transport is connected.
-    - Pairing/allowlist checks pass.
-    - Mentions are detected where required.
-
-    Common log signatures:
-
-    - `mention required` → group mention gating blocked processing.
-    - `pairing` / `pending` → DM sender is not approved yet.
-    - `not_in_channel`, `missing_scope`, `Forbidden`, `401/403` → channel permission token issue.
-
-    Deep pages:
-
-    - [/gateway/troubleshooting#channel-connected-messages-not-flowing](/gateway/troubleshooting#channel-connected-messages-not-flowing)
-    - [/channels/troubleshooting](/channels/troubleshooting)
-
-  </Accordion>
-
-  <Accordion title="Cron or heartbeat did not fire or did not deliver">
-    ```bash
-    symi status
-    symi gateway status
-    symi cron status
-    symi cron list
-    symi cron runs --id <jobId> --limit 20
-    symi logs --follow
-    ```
-
-    Good output looks like:
-
-    - `cron.status` shows enabled with a next wake.
-    - `cron runs` shows recent `ok` entries.
-    - Heartbeat is enabled and not outside active hours.
-
-    Common log signatures:
-
-    - `cron: scheduler disabled; jobs will not run automatically` → cron is disabled.
-    - `heartbeat skipped` with `reason=quiet-hours` → outside configured active hours.
-    - `requests-in-flight` → main lane busy; heartbeat wake was deferred.
-    - `unknown accountId` → heartbeat delivery target account does not exist.
-
-    Deep pages:
-
-    - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/gateway/troubleshooting#cron-and-heartbeat-delivery)
-    - [/automation/troubleshooting](/automation/troubleshooting)
-    - [/gateway/heartbeat](/gateway/heartbeat)
-
-  </Accordion>
-
-  <Accordion title="Node is paired but tool fails camera canvas screen exec">
-    ```bash
-    symi status
-    symi gateway status
-    symi nodes status
-    symi nodes describe --node <idOrNameOrIp>
-    symi logs --follow
-    ```
-
-    Good output looks like:
-
-    - Node is listed as connected and paired for role `node`.
-    - Capability exists for the command you are invoking.
-    - Permission state is granted for the tool.
-
-    Common log signatures:
-
-    - `NODE_BACKGROUND_UNAVAILABLE` → bring node app to foreground.
-    - `*_PERMISSION_REQUIRED` → OS permission was denied/missing.
-    - `SYSTEM_RUN_DENIED: approval required` → exec approval is pending.
-    - `SYSTEM_RUN_DENIED: allowlist miss` → command not on exec allowlist.
-
-    Deep pages:
-
-    - [/gateway/troubleshooting#node-paired-tool-fails](/gateway/troubleshooting#node-paired-tool-fails)
-    - [/nodes/troubleshooting](/nodes/troubleshooting)
-    - [/tools/exec-approvals](/tools/exec-approvals)
-
-  </Accordion>
-
-  <Accordion title="Browser tool fails">
-    ```bash
-    symi status
-    symi gateway status
-    symi browser status
-    symi logs --follow
-    symi doctor
-    ```
-
-    Good output looks like:
-
-    - Browser status shows `running: true` and a chosen browser/profile.
-    - `symi` profile starts or `chrome` relay has an attached tab.
-
-    Common log signatures:
-
-    - `Failed to start Chrome CDP on port` → local browser launch failed.
-    - `browser.executablePath not found` → configured binary path is wrong.
-    - `Chrome extension relay is running, but no tab is connected` → extension not attached.
-    - `Browser attachOnly is enabled ... not reachable` → attach-only profile has no live CDP target.
-
-    Deep pages:
-
-    - [/gateway/troubleshooting#browser-tool-fails](/gateway/troubleshooting#browser-tool-fails)
-    - [/tools/browser-linux-troubleshooting](/tools/browser-linux-troubleshooting)
-    - [/tools/chrome-extension](/tools/chrome-extension)
-
-  </Accordion>
-</AccordionGroup>

package/docs/images/groups-flow.svg

@@ -1,52 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="960" height="260" viewBox="0 0 960 260" role="img" aria-label="Group message flow">
-  <defs>
-    <style>
-      .box { fill: #f6f5f3; stroke: #2b2b2b; stroke-width: 2; }
-      .drop { fill: #fff1f1; stroke: #a33; stroke-width: 2; }
-      .note { fill: #fffaf0; stroke: #9a7b00; stroke-width: 2; }
-      .text { font: 14px "SF Pro Text", -apple-system, Helvetica, Arial, sans-serif; fill: #1a1a1a; }
-      .label { font: 12px "SF Pro Text", -apple-system, Helvetica, Arial, sans-serif; fill: #333; }
-      .arrow { stroke: #2b2b2b; stroke-width: 2; fill: none; marker-end: url(#arrow); }
-    </style>
-    <marker id="arrow" markerWidth="10" markerHeight="10" refX="8" refY="3" orient="auto">
-      <path d="M0,0 L8,3 L0,6 Z" fill="#2b2b2b" />
-    </marker>
-  </defs>
-
-  <rect class="box" x="20" y="40" width="140" height="60" rx="8" />
-  <text class="text" x="90" y="75" text-anchor="middle">Group message</text>
-
-  <rect class="box" x="200" y="40" width="160" height="60" rx="8" />
-  <text class="text" x="280" y="68" text-anchor="middle">Group policy</text>
-  <text class="label" x="280" y="86" text-anchor="middle">open / disabled / allowlist</text>
-
-  <rect class="box" x="400" y="40" width="150" height="60" rx="8" />
-  <text class="text" x="475" y="75" text-anchor="middle">Allowlist</text>
-
-  <rect class="box" x="580" y="40" width="170" height="60" rx="8" />
-  <text class="text" x="665" y="68" text-anchor="middle">Mention gating</text>
-  <text class="label" x="665" y="86" text-anchor="middle">requireMention</text>
-
-  <rect class="box" x="780" y="40" width="140" height="60" rx="8" />
-  <text class="text" x="850" y="75" text-anchor="middle">Reply</text>
-
-  <line class="arrow" x1="160" y1="70" x2="200" y2="70" />
-  <line class="arrow" x1="360" y1="70" x2="400" y2="70" />
-  <line class="arrow" x1="550" y1="70" x2="580" y2="70" />
-  <line class="arrow" x1="750" y1="70" x2="780" y2="70" />
-
-  <rect class="drop" x="220" y="150" width="120" height="50" rx="8" />
-  <text class="text" x="280" y="180" text-anchor="middle">Drop</text>
-  <line class="arrow" x1="280" y1="100" x2="280" y2="150" />
-  <text class="label" x="250" y="130" text-anchor="end">disabled</text>
-
-  <rect class="drop" x="410" y="150" width="120" height="50" rx="8" />
-  <text class="text" x="470" y="180" text-anchor="middle">Drop</text>
-  <line class="arrow" x1="475" y1="100" x2="470" y2="150" />
-  <text class="label" x="445" y="130" text-anchor="end">not allowed</text>
-
-  <rect class="note" x="600" y="150" width="200" height="50" rx="8" />
-  <text class="text" x="700" y="175" text-anchor="middle">Store for context</text>
-  <text class="label" x="700" y="192" text-anchor="middle">(no mention)</text>
-  <line class="arrow" x1="665" y1="100" x2="700" y2="150" />
-</svg>

package/docs/index.md

@@ -1,186 +0,0 @@
----
-summary: "Symi is a multi-channel gateway for AI agents that runs on any OS."
-read_when:
-  - Introducing Symi to newcomers
-title: "Symi"
----
-
-# Symi 🦞
-
-<p align="center">
-    <img
-        src="/assets/symi-logo-text-dark.png"
-        alt="Symi"
-        width="500"
-        class="dark:hidden"
-    />
-    <img
-        src="/assets/symi-logo-text.png"
-        alt="Symi"
-        width="500"
-        class="hidden dark:block"
-    />
-</p>
-
-> _"EXFOLIATE! EXFOLIATE!"_ — A space pipeline, probably
-
-<p align="center">
-  Send a message, get an agent response from your pocket. Plugins add Mattermost and more.
-</p>
-
-<Columns>
-  <Card title="Get Started" href="/start/getting-started" icon="rocket">
-    Install Symi and bring up the Gateway in minutes.
-  </Card>
-  <Card title="Run the Wizard" href="/start/wizard" icon="sparkles">
-    Guided setup with `symi onboard` and pairing flows.
-  </Card>
-  <Card title="Open the Control UI" href="/web/control-ui" icon="layout-dashboard">
-    Launch the browser dashboard for chat, config, and sessions.
-  </Card>
-</Columns>
-
-## What is Symi?
-
-**Who is it for?** Developers and power users who want a personal AI assistant they can message from anywhere — without giving up control of their data or relying on a hosted service.
-
-**What makes it different?**
-
-- **Self-hosted**: runs on your hardware, your rules
-- **Agent-native**: built for coding agents with tool use, sessions, memory, and multi-agent routing
-- **Open source**: MIT licensed, community-driven
-
-**What do you need?** Node 22+, an API key (Anthropic recommended), and 5 minutes.
-
-## How it works
-
-```mermaid
-flowchart LR
-  A["Chat apps + plugins"] --> B["Gateway"]
-  B --> C["Pi agent"]
-  B --> D["CLI"]
-  B --> E["Web Control UI"]
-  B --> F["macOS app"]
-  B --> G["iOS and Android nodes"]
-```
-
-The Gateway is the single source of truth for sessions, routing, and channel connections.
-
-## Key capabilities
-
-<Columns>
-  <Card title="Multi-channel gateway" icon="network">
-  </Card>
-  <Card title="Plugin channels" icon="plug">
-    Add Mattermost and more with extension packages.
-  </Card>
-  <Card title="Multi-agent routing" icon="route">
-    Isolated sessions per agent, workspace, or sender.
-  </Card>
-  <Card title="Media support" icon="image">
-    Send and receive images, audio, and documents.
-  </Card>
-  <Card title="Web Control UI" icon="monitor">
-    Browser dashboard for chat, config, sessions, and nodes.
-  </Card>
-  <Card title="Mobile nodes" icon="smartphone">
-    Pair iOS and Android nodes with Canvas support.
-  </Card>
-</Columns>
-
-## Quick start
-
-<Steps>
-  <Step title="Install Symi">
-    ```bash
-    npm install -g @symerian/symi@latest
-    ```
-  </Step>
-  <Step title="Onboard and install the service">
-    ```bash
-    symi onboard --install-daemon
-    ```
-  </Step>
-  <Step title="Pair WhatsApp and start the Gateway">
-    ```bash
-    symi channels login
-    symi gateway --port 18789
-    ```
-  </Step>
-</Steps>
-
-Need the full install and dev setup? See [Quick start](/start/quickstart).
-
-## Dashboard
-
-Open the browser Control UI after the Gateway starts.
-
-- Local default: [http://127.0.0.1:18789/](http://127.0.0.1:18789/)
-- Remote access: [Web surfaces](/web) and [Tailscale](/gateway/tailscale)
-
-<p align="center">
-  <img src="whatsapp-symi.jpg" alt="Symi" width="420" />
-</p>
-
-## Configuration (optional)
-
-Config lives at `~/.symi/symi.json`.
-
-- If you **do nothing**, Symi uses the bundled Pi binary in RPC mode with per-sender sessions.
-- If you want to lock it down, start with `channels.whatsapp.allowFrom` and (for groups) mention rules.
-
-Example:
-
-```json5
-{
-  channels: {
-    whatsapp: {
-      allowFrom: ["+15555550123"],
-      groups: { "*": { requireMention: true } },
-    },
-  },
-  messages: { groupChat: { mentionPatterns: ["@symi"] } },
-}
-```
-
-## Start here
-
-<Columns>
-  <Card title="Docs hubs" href="/start/hubs" icon="book-open">
-    All docs and guides, organized by use case.
-  </Card>
-  <Card title="Configuration" href="/gateway/configuration" icon="settings">
-    Core Gateway settings, tokens, and provider config.
-  </Card>
-  <Card title="Remote access" href="/gateway/remote" icon="globe">
-    SSH and tailnet access patterns.
-  </Card>
-  <Card title="Channels" href="/channels/telegram" icon="message-square">
-  </Card>
-  <Card title="Nodes" href="/nodes" icon="smartphone">
-    iOS and Android nodes with pairing and Canvas.
-  </Card>
-  <Card title="Help" href="/help" icon="life-buoy">
-    Common fixes and troubleshooting entry point.
-  </Card>
-</Columns>
-
-## Learn more
-
-<Columns>
-  <Card title="Full feature list" href="/concepts/features" icon="list">
-    Complete channel, routing, and media capabilities.
-  </Card>
-  <Card title="Multi-agent routing" href="/concepts/multi-agent" icon="route">
-    Workspace isolation and per-agent sessions.
-  </Card>
-  <Card title="Security" href="/gateway/security" icon="shield">
-    Tokens, allowlists, and safety controls.
-  </Card>
-  <Card title="Troubleshooting" href="/gateway/troubleshooting" icon="wrench">
-    Gateway diagnostics and common errors.
-  </Card>
-  <Card title="About and credits" href="/reference/credits" icon="info">
-    Project origins, contributors, and license.
-  </Card>
-</Columns>