@symerian/symi 3.0.20 → 3.0.22

package/docs/cli/config.md

@@ -1,50 +0,0 @@
----
-summary: "CLI reference for `symi config` (get/set/unset config values)"
-read_when:
-  - You want to read or edit config non-interactively
-title: "config"
----
-
-# `symi config`
-
-Config helpers: get/set/unset values by path. Run without a subcommand to open
-the configure wizard (same as `symi configure`).
-
-## Examples
-
-```bash
-symi config get browser.executablePath
-symi config set browser.executablePath "/usr/bin/google-chrome"
-symi config set agents.defaults.heartbeat.every "2h"
-symi config set agents.list[0].tools.exec.node "node-id-or-name"
-symi config unset tools.web.search.apiKey
-```
-
-## Paths
-
-Paths use dot or bracket notation:
-
-```bash
-symi config get agents.defaults.workspace
-symi config get agents.list[0].id
-```
-
-Use the agent list index to target a specific agent:
-
-```bash
-symi config get agents.list
-symi config set agents.list[1].tools.exec.node "node-id-or-name"
-```
-
-## Values
-
-Values are parsed as JSON5 when possible; otherwise they are treated as strings.
-Use `--strict-json` to require JSON5 parsing. `--json` remains supported as a legacy alias.
-
-```bash
-symi config set agents.defaults.heartbeat.every "0m"
-symi config set gateway.port 19001 --strict-json
-symi config set channels.whatsapp.groups '["*"]' --strict-json
-```
-
-Restart the gateway after edits.

package/docs/cli/configure.md

@@ -1,32 +0,0 @@
----
-summary: "CLI reference for `symi configure` (interactive configuration prompts)"
-read_when:
-  - You want to tweak credentials, devices, or agent defaults interactively
-title: "configure"
----
-
-# `symi configure`
-
-Interactive prompt to set up credentials, devices, and agent defaults.
-
-Note: The **Model** section now includes a multi-select for the
-`agents.defaults.models` allowlist (what shows up in `/model` and the model picker).
-
-Tip: `symi config` without a subcommand opens the same wizard. Use
-`symi config get|set|unset` for non-interactive edits.
-
-Related:
-
-- Gateway configuration reference: [Configuration](/gateway/configuration)
-- Config CLI: [Config](/cli/config)
-
-Notes:
-
-- Choosing where the Gateway runs always updates `gateway.mode`. You can select "Continue" without other sections if that is all you need.
-
-## Examples
-
-```bash
-symi configure
-symi configure --section models --section channels
-```

package/docs/cli/cron.md

@@ -1,44 +0,0 @@
----
-summary: "CLI reference for `symi cron` (schedule and run background jobs)"
-read_when:
-  - You want scheduled jobs and wakeups
-  - You’re debugging cron execution and logs
-title: "cron"
----
-
-# `symi cron`
-
-Manage cron jobs for the Gateway scheduler.
-
-Related:
-
-- Cron jobs: [Cron jobs](/automation/cron-jobs)
-
-Tip: run `symi cron --help` for the full command surface.
-
-Note: isolated `cron add` jobs default to `--announce` delivery. Use `--no-deliver` to keep
-output internal. `--deliver` remains as a deprecated alias for `--announce`.
-
-Note: one-shot (`--at`) jobs delete after success by default. Use `--keep-after-run` to keep them.
-
-Note: recurring jobs now use exponential retry backoff after consecutive errors (30s → 1m → 5m → 15m → 60m), then return to normal schedule after the next successful run.
-
-## Common edits
-
-Update delivery settings without changing the message:
-
-```bash
-symi cron edit <job-id> --announce --channel telegram --to "123456789"
-```
-
-Disable delivery for an isolated job:
-
-```bash
-symi cron edit <job-id> --no-deliver
-```
-
-Announce to a specific channel:
-
-```bash
-symi cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
-```

package/docs/cli/dashboard.md

@@ -1,16 +0,0 @@
----
-summary: "CLI reference for `symi dashboard` (open the Control UI)"
-read_when:
-  - You want to open the Control UI with your current token
-  - You want to print the URL without launching a browser
-title: "dashboard"
----
-
-# `symi dashboard`
-
-Open the Control UI using your current auth.
-
-```bash
-symi dashboard
-symi dashboard --no-open
-```

package/docs/cli/devices.md

@@ -1,73 +0,0 @@
----
-summary: "CLI reference for `symi devices` (device pairing + token rotation/revocation)"
-read_when:
-  - You are approving device pairing requests
-  - You need to rotate or revoke device tokens
-title: "devices"
----
-
-# `symi devices`
-
-Manage device pairing requests and device-scoped tokens.
-
-## Commands
-
-### `symi devices list`
-
-List pending pairing requests and paired devices.
-
-```
-symi devices list
-symi devices list --json
-```
-
-### `symi devices approve [requestId] [--latest]`
-
-Approve a pending device pairing request. If `requestId` is omitted, Symi
-automatically approves the most recent pending request.
-
-```
-symi devices approve
-symi devices approve <requestId>
-symi devices approve --latest
-```
-
-### `symi devices reject <requestId>`
-
-Reject a pending device pairing request.
-
-```
-symi devices reject <requestId>
-```
-
-### `symi devices rotate --device <id> --role <role> [--scope <scope...>]`
-
-Rotate a device token for a specific role (optionally updating scopes).
-
-```
-symi devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
-```
-
-### `symi devices revoke --device <id> --role <role>`
-
-Revoke a device token for a specific role.
-
-```
-symi devices revoke --device <deviceId> --role node
-```
-
-## Common options
-
-- `--url <url>`: Gateway WebSocket URL (defaults to `gateway.remote.url` when configured).
-- `--token <token>`: Gateway token (if required).
-- `--password <password>`: Gateway password (password auth).
-- `--timeout <ms>`: RPC timeout.
-- `--json`: JSON output (recommended for scripting).
-
-Note: when you set `--url`, the CLI does not fall back to config or environment credentials.
-Pass `--token` or `--password` explicitly. Missing explicit credentials is an error.
-
-## Notes
-
-- Token rotation returns a new token (sensitive). Treat it like a secret.
-- These commands require `operator.pairing` (or `operator.admin`) scope.

package/docs/cli/directory.md

@@ -1,62 +0,0 @@
----
-summary: "CLI reference for `symi directory` (self, peers, groups)"
-read_when:
-  - You want to look up contacts/groups/self ids for a channel
-  - You are developing a channel directory adapter
-title: "directory"
----
-
-# `symi directory`
-
-Directory lookups for channels that support it (contacts/peers, groups, and “me”).
-
-## Common flags
-
-- `--channel <name>`: channel id/alias (required when multiple channels are configured; auto when only one is configured)
-- `--account <id>`: account id (default: channel default)
-- `--json`: output JSON
-
-## Notes
-
-- `directory` is meant to help you find IDs you can paste into other commands (especially `symi message send --target ...`).
-- For many channels, results are config-backed (allowlists / configured groups) rather than a live provider directory.
-- Default output is `id` (and sometimes `name`) separated by a tab; use `--json` for scripting.
-
-## Using results with `message send`
-
-```bash
-symi directory peers list --channel slack --query "U0"
-symi message send --channel slack --target user:U012ABCDEF --message "hello"
-```
-
-## ID formats (by channel)
-
-- WhatsApp: `+15551234567` (DM), `1234567890-1234567890@g.us` (group)
-- Telegram: `@username` or numeric chat id; groups are numeric ids
-- Slack: `user:U…` and `channel:C…`
-- Matrix (plugin): `user:@user:server`, `room:!roomId:server`, or `#alias:server`
-- Microsoft Teams (plugin): `user:<id>` and `conversation:<id>`
-- Zalo (plugin): user id (Bot API)
-- Zalo Personal / `zalouser` (plugin): thread id (DM/group) from `zca` (`me`, `friend list`, `group list`)
-
-## Self (“me”)
-
-```bash
-symi directory self --channel zalouser
-```
-
-## Peers (contacts/users)
-
-```bash
-symi directory peers list --channel zalouser
-symi directory peers list --channel zalouser --query "name"
-symi directory peers list --channel zalouser --limit 50
-```
-
-## Groups
-
-```bash
-symi directory groups list --channel zalouser
-symi directory groups list --channel zalouser --query "work"
-symi directory groups members --channel zalouser --group-id <id>
-```

package/docs/cli/dns.md

@@ -1,23 +0,0 @@
----
-summary: "CLI reference for `symi dns` (wide-area discovery helpers)"
-read_when:
-  - You want wide-area discovery (DNS-SD) via Tailscale + CoreDNS
-  - You’re setting up split DNS for a custom discovery domain (example: symi.internal)
-title: "dns"
----
-
-# `symi dns`
-
-DNS helpers for wide-area discovery (Tailscale + CoreDNS). Currently focused on macOS + Homebrew CoreDNS.
-
-Related:
-
-- Gateway discovery: [Discovery](/gateway/discovery)
-- Wide-area discovery config: [Configuration](/gateway/configuration)
-
-## Setup
-
-```bash
-symi dns setup
-symi dns setup --apply
-```

package/docs/cli/docs.md

@@ -1,15 +0,0 @@
----
-summary: "CLI reference for `symi docs` (search the live docs index)"
-read_when:
-  - You want to search the live Symi docs from the terminal
-title: "docs"
----
-
-# `symi docs`
-
-Search the live docs index.
-
-```bash
-symi docs browser extension
-symi docs sandbox allowHostControl
-```

package/docs/cli/doctor.md

@@ -1,41 +0,0 @@
----
-summary: "CLI reference for `symi doctor` (health checks + guided repairs)"
-read_when:
-  - You have connectivity/auth issues and want guided fixes
-  - You updated and want a sanity check
-title: "doctor"
----
-
-# `symi doctor`
-
-Health checks + quick fixes for the gateway and channels.
-
-Related:
-
-- Troubleshooting: [Troubleshooting](/gateway/troubleshooting)
-- Security audit: [Security](/gateway/security)
-
-## Examples
-
-```bash
-symi doctor
-symi doctor --repair
-symi doctor --deep
-```
-
-Notes:
-
-- Interactive prompts (like keychain/OAuth fixes) only run when stdin is a TTY and `--non-interactive` is **not** set. Headless runs (cron, Telegram, no terminal) will skip prompts.
-- `--fix` (alias for `--repair`) writes a backup to `~/.symi/symi.json.bak` and drops unknown config keys, listing each removal.
-
-## macOS: `launchctl` env overrides
-
-If you previously ran `launchctl setenv SYMI_GATEWAY_TOKEN ...` (or `...PASSWORD`), that value overrides your config file and can cause persistent “unauthorized” errors.
-
-```bash
-launchctl getenv SYMI_GATEWAY_TOKEN
-launchctl getenv SYMI_GATEWAY_PASSWORD
-
-launchctl unsetenv SYMI_GATEWAY_TOKEN
-launchctl unsetenv SYMI_GATEWAY_PASSWORD
-```

package/docs/cli/gateway.md

@@ -1,202 +0,0 @@
----
-summary: "Symi Gateway CLI (`symi gateway`) — run, query, and discover gateways"
-read_when:
-  - Running the Gateway from the CLI (dev or servers)
-  - Debugging Gateway auth, bind modes, and connectivity
-  - Discovering gateways via Bonjour (LAN + tailnet)
-title: "gateway"
----
-
-# Gateway CLI
-
-The Gateway is Symi’s WebSocket server (channels, nodes, sessions, hooks).
-
-Subcommands in this page live under `symi gateway …`.
-
-Related docs:
-
-- [/gateway/bonjour](/gateway/bonjour)
-- [/gateway/discovery](/gateway/discovery)
-- [/gateway/configuration](/gateway/configuration)
-
-## Run the Gateway
-
-Run a local Gateway process:
-
-```bash
-symi gateway
-```
-
-Foreground alias:
-
-```bash
-symi gateway run
-```
-
-Notes:
-
-- By default, the Gateway refuses to start unless `gateway.mode=local` is set in `~/.symi/symi.json`. Use `--allow-unconfigured` for ad-hoc/dev runs.
-- Binding beyond loopback without auth is blocked (safety guardrail).
-- `SIGUSR1` triggers an in-process restart when authorized (`commands.restart` is enabled by default; set `commands.restart: false` to block manual restart, while gateway tool/config apply/update remain allowed).
-- `SIGINT`/`SIGTERM` handlers stop the gateway process, but they don’t restore any custom terminal state. If you wrap the CLI with a TUI or raw-mode input, restore the terminal before exit.
-
-### Options
-
-- `--port <port>`: WebSocket port (default comes from config/env; usually `18789`).
-- `--bind <loopback|lan|tailnet|auto|custom>`: listener bind mode.
-- `--auth <token|password>`: auth mode override.
-- `--token <token>`: token override (also sets `SYMI_GATEWAY_TOKEN` for the process).
-- `--password <password>`: password override (also sets `SYMI_GATEWAY_PASSWORD` for the process).
-- `--tailscale <off|serve|funnel>`: expose the Gateway via Tailscale.
-- `--tailscale-reset-on-exit`: reset Tailscale serve/funnel config on shutdown.
-- `--allow-unconfigured`: allow gateway start without `gateway.mode=local` in config.
-- `--dev`: create a dev config + workspace if missing (skips BOOTSTRAP.md).
-- `--reset`: reset dev config + credentials + sessions + workspace (requires `--dev`).
-- `--force`: kill any existing listener on the selected port before starting.
-- `--verbose`: verbose logs.
-- `--claude-cli-logs`: only show claude-cli logs in the console (and enable its stdout/stderr).
-- `--ws-log <auto|full|compact>`: websocket log style (default `auto`).
-- `--compact`: alias for `--ws-log compact`.
-- `--raw-stream`: log raw model stream events to jsonl.
-- `--raw-stream-path <path>`: raw stream jsonl path.
-
-## Query a running Gateway
-
-All query commands use WebSocket RPC.
-
-Output modes:
-
-- Default: human-readable (colored in TTY).
-- `--json`: machine-readable JSON (no styling/spinner).
-- `--no-color` (or `NO_COLOR=1`): disable ANSI while keeping human layout.
-
-Shared options (where supported):
-
-- `--url <url>`: Gateway WebSocket URL.
-- `--token <token>`: Gateway token.
-- `--password <password>`: Gateway password.
-- `--timeout <ms>`: timeout/budget (varies per command).
-- `--expect-final`: wait for a “final” response (agent calls).
-
-Note: when you set `--url`, the CLI does not fall back to config or environment credentials.
-Pass `--token` or `--password` explicitly. Missing explicit credentials is an error.
-
-### `gateway health`
-
-```bash
-symi gateway health --url ws://127.0.0.1:18789
-```
-
-### `gateway status`
-
-`gateway status` shows the Gateway service (launchd/systemd/schtasks) plus an optional RPC probe.
-
-```bash
-symi gateway status
-symi gateway status --json
-```
-
-Options:
-
-- `--url <url>`: override the probe URL.
-- `--token <token>`: token auth for the probe.
-- `--password <password>`: password auth for the probe.
-- `--timeout <ms>`: probe timeout (default `10000`).
-- `--no-probe`: skip the RPC probe (service-only view).
-- `--deep`: scan system-level services too.
-
-### `gateway probe`
-
-`gateway probe` is the “debug everything” command. It always probes:
-
-- your configured remote gateway (if set), and
-- localhost (loopback) **even if remote is configured**.
-
-If multiple gateways are reachable, it prints all of them. Multiple gateways are supported when you use isolated profiles/ports (e.g., a rescue bot), but most installs still run a single gateway.
-
-```bash
-symi gateway probe
-symi gateway probe --json
-```
-
-#### Remote over SSH (Mac app parity)
-
-The macOS app “Remote over SSH” mode uses a local port-forward so the remote gateway (which may be bound to loopback only) becomes reachable at `ws://127.0.0.1:<port>`.
-
-CLI equivalent:
-
-```bash
-symi gateway probe --ssh user@gateway-host
-```
-
-Options:
-
-- `--ssh <target>`: `user@host` or `user@host:port` (port defaults to `22`).
-- `--ssh-identity <path>`: identity file.
-- `--ssh-auto`: pick the first discovered gateway host as SSH target (LAN/WAB only).
-
-Config (optional, used as defaults):
-
-- `gateway.remote.sshTarget`
-- `gateway.remote.sshIdentity`
-
-### `gateway call <method>`
-
-Low-level RPC helper.
-
-```bash
-symi gateway call status
-symi gateway call logs.tail --params '{"sinceMs": 60000}'
-```
-
-## Manage the Gateway service
-
-```bash
-symi gateway install
-symi gateway start
-symi gateway stop
-symi gateway restart
-symi gateway uninstall
-```
-
-Notes:
-
-- `gateway install` supports `--port`, `--runtime`, `--token`, `--force`, `--json`.
-- Lifecycle commands accept `--json` for scripting.
-
-## Discover gateways (Bonjour)
-
-`gateway discover` scans for Gateway beacons (`_symi-gw._tcp`).
-
-- Multicast DNS-SD: `local.`
-- Unicast DNS-SD (Wide-Area Bonjour): choose a domain (example: `symi.internal.`) and set up split DNS + a DNS server; see [/gateway/bonjour](/gateway/bonjour)
-
-Only gateways with Bonjour discovery enabled (default) advertise the beacon.
-
-Wide-Area discovery records include (TXT):
-
-- `role` (gateway role hint)
-- `transport` (transport hint, e.g. `gateway`)
-- `gatewayPort` (WebSocket port, usually `18789`)
-- `sshPort` (SSH port; defaults to `22` if not present)
-- `tailnetDns` (MagicDNS hostname, when available)
-- `gatewayTls` / `gatewayTlsSha256` (TLS enabled + cert fingerprint)
-- `cliPath` (optional hint for remote installs)
-
-### `gateway discover`
-
-```bash
-symi gateway discover
-```
-
-Options:
-
-- `--timeout <ms>`: per-command timeout (browse/resolve); default `2000`.
-- `--json`: machine-readable output (also disables styling/spinner).
-
-Examples:
-
-```bash
-symi gateway discover --timeout 4000
-symi gateway discover --json | jq '.beacons[].wsUrl'
-```

package/docs/cli/health.md

@@ -1,21 +0,0 @@
----
-summary: "CLI reference for `symi health` (gateway health endpoint via RPC)"
-read_when:
-  - You want to quickly check the running Gateway’s health
-title: "health"
----
-
-# `symi health`
-
-Fetch health from the running Gateway.
-
-```bash
-symi health
-symi health --json
-symi health --verbose
-```
-
-Notes:
-
-- `--verbose` runs live probes and prints per-account timings when multiple accounts are configured.
-- Output includes per-agent session stores when multiple agents are configured.