@symerian/symi 3.0.20 → 3.0.22

package/docs/channels/zalouser.md

@@ -1,140 +0,0 @@
----
-summary: "Zalo personal account support via zca-cli (QR login), capabilities, and configuration"
-read_when:
-  - Setting up Zalo Personal for Symi
-  - Debugging Zalo Personal login or message flow
-title: "Zalo Personal"
----
-
-# Zalo Personal (unofficial)
-
-Status: experimental. This integration automates a **personal Zalo account** via `zca-cli`.
-
-> **Warning:** This is an unofficial integration and may result in account suspension/ban. Use at your own risk.
-
-## Plugin required
-
-Zalo Personal ships as a plugin and is not bundled with the core install.
-
-- Install via CLI: `symi plugins install @symi/zalouser`
-- Or from a source checkout: `symi plugins install ./extensions/zalouser`
-- Details: [Plugins](/tools/plugin)
-
-## Prerequisite: zca-cli
-
-The Gateway machine must have the `zca` binary available in `PATH`.
-
-- Verify: `zca --version`
-- If missing, install zca-cli (see `extensions/zalouser/README.md` or the upstream zca-cli docs).
-
-## Onboarding
-
-1. Install the plugin (see above).
-2. Login (QR, on the Gateway machine):
-   - `symi channels login --channel zalouser`
-   - Scan the QR code in the terminal with the Zalo mobile app.
-3. Enable the channel:
-
-```json5
-{
-  channels: {
-    zalouser: {
-      enabled: true,
-      dmPolicy: "pairing",
-    },
-  },
-}
-```
-
-4. Restart the Gateway (or finish onboarding).
-5. DM access defaults to pairing; approve the pairing code on first contact.
-
-## What it is
-
-- Uses `zca listen` to receive inbound messages.
-- Uses `zca msg ...` to send replies (text/media/link).
-- Designed for “personal account” use cases where Zalo Bot API is not available.
-
-## Naming
-
-Channel id is `zalouser` to make it explicit this automates a **personal Zalo user account** (unofficial). We keep `zalo` reserved for a potential future official Zalo API integration.
-
-## Finding IDs (directory)
-
-Use the directory CLI to discover peers/groups and their IDs:
-
-```bash
-symi directory self --channel zalouser
-symi directory peers list --channel zalouser --query "name"
-symi directory groups list --channel zalouser --query "work"
-```
-
-## Limits
-
-- Outbound text is chunked to ~2000 characters (Zalo client limits).
-- Streaming is blocked by default.
-
-## Access control (DMs)
-
-`channels.zalouser.dmPolicy` supports: `pairing | allowlist | open | disabled` (default: `pairing`).
-`channels.zalouser.allowFrom` accepts user IDs or names. The wizard resolves names to IDs via `zca friend find` when available.
-
-Approve via:
-
-- `symi pairing list zalouser`
-- `symi pairing approve zalouser <code>`
-
-## Group access (optional)
-
-- Default: `channels.zalouser.groupPolicy = "open"` (groups allowed). Use `channels.defaults.groupPolicy` to override the default when unset.
-- Restrict to an allowlist with:
-  - `channels.zalouser.groupPolicy = "allowlist"`
-  - `channels.zalouser.groups` (keys are group IDs or names)
-- Block all groups: `channels.zalouser.groupPolicy = "disabled"`.
-- The configure wizard can prompt for group allowlists.
-- On startup, Symi resolves group/user names in allowlists to IDs and logs the mapping; unresolved entries are kept as typed.
-
-Example:
-
-```json5
-{
-  channels: {
-    zalouser: {
-      groupPolicy: "allowlist",
-      groups: {
-        "123456789": { allow: true },
-        "Work Chat": { allow: true },
-      },
-    },
-  },
-}
-```
-
-## Multi-account
-
-Accounts map to zca profiles. Example:
-
-```json5
-{
-  channels: {
-    zalouser: {
-      enabled: true,
-      defaultAccount: "default",
-      accounts: {
-        work: { enabled: true, profile: "work" },
-      },
-    },
-  },
-}
-```
-
-## Troubleshooting
-
-**`zca` not found:**
-
-- Install zca-cli and ensure it’s on `PATH` for the Gateway process.
-
-**Login doesn’t stick:**
-
-- `symi channels status --probe`
-- Re-login: `symi channels logout --channel zalouser && symi channels login --channel zalouser`

package/docs/ci.md

@@ -1,50 +0,0 @@
----
-title: CI Pipeline
-description: How the Symi CI pipeline works
----
-
-# CI Pipeline
-
-The CI runs on every push to `main` and every pull request. It uses smart scoping to skip expensive jobs when only docs or native code changed.
-
-## Job Overview
-
-| Job               | Purpose                                         | When it runs              |
-| ----------------- | ----------------------------------------------- | ------------------------- |
-| `docs-scope`      | Detect docs-only changes                        | Always                    |
-| `changed-scope`   | Detect which areas changed (node/macos/android) | Non-docs PRs              |
-| `check`           | TypeScript types, lint, format                  | Non-docs changes          |
-| `check-docs`      | Markdown lint + broken link check               | Docs changed              |
-| `code-analysis`   | LOC threshold check (1000 lines)                | PRs only                  |
-| `secrets`         | Detect leaked secrets                           | Always                    |
-| `build-artifacts` | Build dist once, share with other jobs          | Non-docs, node changes    |
-| `release-check`   | Validate npm pack contents                      | After build               |
-| `checks`          | Node/Bun tests + protocol check                 | Non-docs, node changes    |
-| `checks-windows`  | Windows-specific tests                          | Non-docs, node changes    |
-| `macos`           | Swift lint/build/test + TS tests                | PRs with macos changes    |
-| `android`         | Gradle build + tests                            | Non-docs, android changes |
-
-## Fail-Fast Order
-
-Jobs are ordered so cheap checks fail before expensive ones run:
-
-1. `docs-scope` + `code-analysis` + `check` (parallel, ~1-2 min)
-2. `build-artifacts` (blocked on above)
-3. `checks`, `checks-windows`, `macos`, `android` (blocked on build)
-
-## Runners
-
-| Runner                           | Jobs                                       |
-| -------------------------------- | ------------------------------------------ |
-| `blacksmith-16vcpu-ubuntu-2404`  | Most Linux jobs, including scope detection |
-| `blacksmith-16vcpu-windows-2025` | `checks-windows`                           |
-| `macos-latest`                   | `macos`, `ios`                             |
-
-## Local Equivalents
-
-```bash
-pnpm check          # types + lint + format
-pnpm test           # vitest tests
-pnpm check:docs     # docs format + lint + broken links
-pnpm release:check  # validate npm pack
-```

package/docs/cli/acp.md

@@ -1,182 +0,0 @@
----
-summary: "Run the ACP bridge for IDE integrations"
-read_when:
-  - Setting up ACP-based IDE integrations
-  - Debugging ACP session routing to the Gateway
-title: "acp"
----
-
-# acp
-
-Run the ACP (Agent Client Protocol) bridge that talks to a Symi Gateway.
-
-This command speaks ACP over stdio for IDEs and forwards prompts to the Gateway
-over WebSocket. It keeps ACP sessions mapped to Gateway session keys.
-
-## Usage
-
-```bash
-symi acp
-
-# Remote Gateway
-symi acp --url wss://gateway-host:18789 --token <token>
-
-# Remote Gateway (token from file)
-symi acp --url wss://gateway-host:18789 --token-file ~/.symi/gateway.token
-
-# Attach to an existing session key
-symi acp --session agent:main:main
-
-# Attach by label (must already exist)
-symi acp --session-label "support inbox"
-
-# Reset the session key before the first prompt
-symi acp --session agent:main:main --reset-session
-```
-
-## ACP client (debug)
-
-Use the built-in ACP client to sanity-check the bridge without an IDE.
-It spawns the ACP bridge and lets you type prompts interactively.
-
-```bash
-symi acp client
-
-# Point the spawned bridge at a remote Gateway
-symi acp client --server-args --url wss://gateway-host:18789 --token-file ~/.symi/gateway.token
-
-# Override the server command (default: symi)
-symi acp client --server "node" --server-args symi.mjs acp --url ws://127.0.0.1:19001
-```
-
-## How to use this
-
-Use ACP when an IDE (or other client) speaks Agent Client Protocol and you want
-it to drive a Symi Gateway session.
-
-1. Ensure the Gateway is running (local or remote).
-2. Configure the Gateway target (config or flags).
-3. Point your IDE to run `symi acp` over stdio.
-
-Example config (persisted):
-
-```bash
-symi config set gateway.remote.url wss://gateway-host:18789
-symi config set gateway.remote.token <token>
-```
-
-Example direct run (no config write):
-
-```bash
-symi acp --url wss://gateway-host:18789 --token <token>
-# preferred for local process safety
-symi acp --url wss://gateway-host:18789 --token-file ~/.symi/gateway.token
-```
-
-## Selecting agents
-
-ACP does not pick agents directly. It routes by the Gateway session key.
-
-Use agent-scoped session keys to target a specific agent:
-
-```bash
-symi acp --session agent:main:main
-symi acp --session agent:design:main
-symi acp --session agent:qa:bug-123
-```
-
-Each ACP session maps to a single Gateway session key. One agent can have many
-sessions; ACP defaults to an isolated `acp:<uuid>` session unless you override
-the key or label.
-
-## Zed editor setup
-
-Add a custom ACP agent in `~/.config/zed/settings.json` (or use Zed’s Settings UI):
-
-```json
-{
-  "agent_servers": {
-    "Symi ACP": {
-      "type": "custom",
-      "command": "symi",
-      "args": ["acp"],
-      "env": {}
-    }
-  }
-}
-```
-
-To target a specific Gateway or agent:
-
-```json
-{
-  "agent_servers": {
-    "Symi ACP": {
-      "type": "custom",
-      "command": "symi",
-      "args": [
-        "acp",
-        "--url",
-        "wss://gateway-host:18789",
-        "--token",
-        "<token>",
-        "--session",
-        "agent:design:main"
-      ],
-      "env": {}
-    }
-  }
-}
-```
-
-In Zed, open the Agent panel and select “Symi ACP” to start a thread.
-
-## Session mapping
-
-By default, ACP sessions get an isolated Gateway session key with an `acp:` prefix.
-To reuse a known session, pass a session key or label:
-
-- `--session <key>`: use a specific Gateway session key.
-- `--session-label <label>`: resolve an existing session by label.
-- `--reset-session`: mint a fresh session id for that key (same key, new transcript).
-
-If your ACP client supports metadata, you can override per session:
-
-```json
-{
-  "_meta": {
-    "sessionKey": "agent:main:main",
-    "sessionLabel": "support inbox",
-    "resetSession": true
-  }
-}
-```
-
-Learn more about session keys at [/concepts/session](/concepts/session).
-
-## Options
-
-- `--url <url>`: Gateway WebSocket URL (defaults to gateway.remote.url when configured).
-- `--token <token>`: Gateway auth token.
-- `--token-file <path>`: read Gateway auth token from file.
-- `--password <password>`: Gateway auth password.
-- `--password-file <path>`: read Gateway auth password from file.
-- `--session <key>`: default session key.
-- `--session-label <label>`: default session label to resolve.
-- `--require-existing`: fail if the session key/label does not exist.
-- `--reset-session`: reset the session key before first use.
-- `--no-prefix-cwd`: do not prefix prompts with the working directory.
-- `--verbose, -v`: verbose logging to stderr.
-
-Security note:
-
-- `--token` and `--password` can be visible in local process listings on some systems.
-- Prefer `--token-file`/`--password-file` or environment variables (`SYMI_GATEWAY_TOKEN`, `SYMI_GATEWAY_PASSWORD`).
-
-### `acp client` options
-
-- `--cwd <dir>`: working directory for the ACP session.
-- `--server <command>`: ACP server command (default: `symi`).
-- `--server-args <args...>`: extra arguments passed to the ACP server.
-- `--server-verbose`: enable verbose logging on the ACP server.
-- `--verbose, -v`: verbose client logging.

package/docs/cli/agent.md

@@ -1,24 +0,0 @@
----
-summary: "CLI reference for `symi agent` (send one agent turn via the Gateway)"
-read_when:
-  - You want to run one agent turn from scripts (optionally deliver reply)
-title: "agent"
----
-
-# `symi agent`
-
-Run an agent turn via the Gateway (use `--local` for embedded).
-Use `--agent <id>` to target a configured agent directly.
-
-Related:
-
-- Agent send tool: [Agent send](/tools/agent-send)
-
-## Examples
-
-```bash
-symi agent --to +15555550123 --message "status update" --deliver
-symi agent --agent ops --message "Summarize logs"
-symi agent --session-id 1234 --message "Summarize inbox" --thinking medium
-symi agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
-```

package/docs/cli/agents.md

@@ -1,75 +0,0 @@
----
-summary: "CLI reference for `symi agents` (list/add/delete/set identity)"
-read_when:
-  - You want multiple isolated agents (workspaces + routing + auth)
-title: "agents"
----
-
-# `symi agents`
-
-Manage isolated agents (workspaces + auth + routing).
-
-Related:
-
-- Multi-agent routing: [Multi-Agent Routing](/concepts/multi-agent)
-- Agent workspace: [Agent workspace](/concepts/agent-workspace)
-
-## Examples
-
-```bash
-symi agents list
-symi agents add work --workspace ~/.symi/workspace-work
-symi agents set-identity --workspace ~/.symi/workspace --from-identity
-symi agents set-identity --agent main --avatar avatars/symi.png
-symi agents delete work
-```
-
-## Identity files
-
-Each agent workspace can include an `IDENTITY.md` at the workspace root:
-
-- Example path: `~/.symi/workspace/IDENTITY.md`
-- `set-identity --from-identity` reads from the workspace root (or an explicit `--identity-file`)
-
-Avatar paths resolve relative to the workspace root.
-
-## Set identity
-
-`set-identity` writes fields into `agents.list[].identity`:
-
-- `name`
-- `theme`
-- `emoji`
-- `avatar` (workspace-relative path, http(s) URL, or data URI)
-
-Load from `IDENTITY.md`:
-
-```bash
-symi agents set-identity --workspace ~/.symi/workspace --from-identity
-```
-
-Override fields explicitly:
-
-```bash
-symi agents set-identity --agent main --name "Symi" --emoji "🦞" --avatar avatars/symi.png
-```
-
-Config sample:
-
-```json5
-{
-  agents: {
-    list: [
-      {
-        id: "main",
-        identity: {
-          name: "Symi",
-          theme: "space pipeline",
-          emoji: "🦞",
-          avatar: "avatars/symi.png",
-        },
-      },
-    ],
-  },
-}
-```

package/docs/cli/approvals.md

@@ -1,50 +0,0 @@
----
-summary: "CLI reference for `symi approvals` (exec approvals for gateway or node hosts)"
-read_when:
-  - You want to edit exec approvals from the CLI
-  - You need to manage allowlists on gateway or node hosts
-title: "approvals"
----
-
-# `symi approvals`
-
-Manage exec approvals for the **local host**, **gateway host**, or a **node host**.
-By default, commands target the local approvals file on disk. Use `--gateway` to target the gateway, or `--node` to target a specific node.
-
-Related:
-
-- Exec approvals: [Exec approvals](/tools/exec-approvals)
-- Nodes: [Nodes](/nodes)
-
-## Common commands
-
-```bash
-symi approvals get
-symi approvals get --node <id|name|ip>
-symi approvals get --gateway
-```
-
-## Replace approvals from a file
-
-```bash
-symi approvals set --file ./exec-approvals.json
-symi approvals set --node <id|name|ip> --file ./exec-approvals.json
-symi approvals set --gateway --file ./exec-approvals.json
-```
-
-## Allowlist helpers
-
-```bash
-symi approvals allowlist add "~/Projects/**/bin/rg"
-symi approvals allowlist add --agent main --node <id|name|ip> "/usr/bin/uptime"
-symi approvals allowlist add --agent "*" "/usr/bin/uname"
-
-symi approvals allowlist remove "~/Projects/**/bin/rg"
-```
-
-## Notes
-
-- `--node` uses the same resolver as `symi nodes` (id, name, ip, or id prefix).
-- `--agent` defaults to `"*"`, which applies to all agents.
-- The node host must advertise `system.execApprovals.get/set` (macOS app or headless node host).
-- Approvals files are stored per host at `~/.symi/exec-approvals.json`.

package/docs/cli/browser.md

@@ -1,107 +0,0 @@
----
-summary: "CLI reference for `symi browser` (profiles, tabs, actions, extension relay)"
-read_when:
-  - You use `symi browser` and want examples for common tasks
-  - You want to control a browser running on another machine via a node host
-  - You want to use the Chrome extension relay (attach/detach via toolbar button)
-title: "browser"
----
-
-# `symi browser`
-
-Manage Symi’s browser control server and run browser actions (tabs, snapshots, screenshots, navigation, clicks, typing).
-
-Related:
-
-- Browser tool + API: [Browser tool](/tools/browser)
-- Chrome extension relay: [Chrome extension](/tools/chrome-extension)
-
-## Common flags
-
-- `--url <gatewayWsUrl>`: Gateway WebSocket URL (defaults to config).
-- `--token <token>`: Gateway token (if required).
-- `--timeout <ms>`: request timeout (ms).
-- `--browser-profile <name>`: choose a browser profile (default from config).
-- `--json`: machine-readable output (where supported).
-
-## Quick start (local)
-
-```bash
-symi browser --browser-profile chrome tabs
-symi browser --browser-profile symi start
-symi browser --browser-profile symi open https://example.com
-symi browser --browser-profile symi snapshot
-```
-
-## Profiles
-
-Profiles are named browser routing configs. In practice:
-
-- `symi`: launches/attaches to a dedicated Symi-managed Chrome instance (isolated user data dir).
-- `chrome`: controls your existing Chrome tab(s) via the Chrome extension relay.
-
-```bash
-symi browser profiles
-symi browser create-profile --name work --color "#f2646b"
-symi browser delete-profile --name work
-```
-
-Use a specific profile:
-
-```bash
-symi browser --browser-profile work tabs
-```
-
-## Tabs
-
-```bash
-symi browser tabs
-symi browser open https://docs.symi.ai
-symi browser focus <targetId>
-symi browser close <targetId>
-```
-
-## Snapshot / screenshot / actions
-
-Snapshot:
-
-```bash
-symi browser snapshot
-```
-
-Screenshot:
-
-```bash
-symi browser screenshot
-```
-
-Navigate/click/type (ref-based UI automation):
-
-```bash
-symi browser navigate https://example.com
-symi browser click <ref>
-symi browser type <ref> "hello"
-```
-
-## Chrome extension relay (attach via toolbar button)
-
-This mode lets the agent control an existing Chrome tab that you attach manually (it does not auto-attach).
-
-Install the unpacked extension to a stable path:
-
-```bash
-symi browser extension install
-symi browser extension path
-```
-
-Then Chrome → `chrome://extensions` → enable “Developer mode” → “Load unpacked” → select the printed folder.
-
-Full guide: [Chrome extension](/tools/chrome-extension)
-
-## Remote browser control (node host proxy)
-
-If the Gateway runs on a different machine than the browser, run a **node host** on the machine that has Chrome/Brave/Edge/Chromium. The Gateway will proxy browser actions to that node (no separate browser control server required).
-
-Use `gateway.nodes.browser.mode` to control auto-routing and `gateway.nodes.browser.node` to pin a specific node if multiple are connected.
-
-Security + remote setup: [Browser tool](/tools/browser), [Remote access](/gateway/remote), [Tailscale](/gateway/tailscale), [Security](/gateway/security)

package/docs/cli/channels.md

@@ -1,73 +0,0 @@
----
-summary: "CLI reference for `symi channels` (accounts, status, login/logout, logs)"
-read_when:
-  - You want to check channel status or tail channel logs
-title: "channels"
----
-
-# `symi channels`
-
-Manage chat channel accounts and their runtime status on the Gateway.
-
-Related docs:
-
-- Channel guides: [Channels](/channels/index)
-- Gateway configuration: [Configuration](/gateway/configuration)
-
-## Common commands
-
-```bash
-symi channels list
-symi channels status
-symi channels capabilities
-symi channels resolve --channel slack "#general" "@jane"
-symi channels logs --channel all
-```
-
-## Add / remove accounts
-
-```bash
-symi channels add --channel telegram --token <bot-token>
-symi channels remove --channel telegram --delete
-```
-
-Tip: `symi channels add --help` shows per-channel flags (token, app token, signal-cli paths, etc).
-
-## Login / logout (interactive)
-
-```bash
-symi channels login --channel whatsapp
-symi channels logout --channel whatsapp
-```
-
-## Troubleshooting
-
-- Run `symi status --deep` for a broad probe.
-- Use `symi doctor` for guided fixes.
-- `symi channels list` prints `Claude: HTTP 403 ... user:profile` → usage snapshot needs the `user:profile` scope. Use `--no-usage`, or provide a claude.ai session key (`CLAUDE_WEB_SESSION_KEY` / `CLAUDE_WEB_COOKIE`), or re-auth via Claude Code CLI.
-
-## Capabilities probe
-
-Fetch provider capability hints (intents/scopes where available) plus static feature support:
-
-```bash
-symi channels capabilities
-```
-
-Notes:
-
-- `--channel` is optional; omit it to list every channel (including extensions).
-
-## Resolve names to IDs
-
-Resolve channel/user names to IDs using the provider directory:
-
-```bash
-symi channels resolve --channel slack "#general" "@jane"
-symi channels resolve --channel matrix "Project Room"
-```
-
-Notes:
-
-- Use `--kind user|group|auto` to force the target type.
-- Resolution prefers active matches when multiple entries share the same name.