@symerian/symi 3.0.21 → 3.0.22

package/docs/cli/plugins.md

@@ -1,92 +0,0 @@
----
-summary: "CLI reference for `symi plugins` (list, install, uninstall, enable/disable, doctor)"
-read_when:
-  - You want to install or manage in-process Gateway plugins
-  - You want to debug plugin load failures
-title: "plugins"
----
-
-# `symi plugins`
-
-Manage Gateway plugins/extensions (loaded in-process).
-
-Related:
-
-- Plugin system: [Plugins](/tools/plugin)
-- Plugin manifest + schema: [Plugin manifest](/plugins/manifest)
-- Security hardening: [Security](/gateway/security)
-
-## Commands
-
-```bash
-symi plugins list
-symi plugins info <id>
-symi plugins enable <id>
-symi plugins disable <id>
-symi plugins uninstall <id>
-symi plugins doctor
-symi plugins update <id>
-symi plugins update --all
-```
-
-Bundled plugins ship with Symi but start disabled. Use `plugins enable` to
-activate them.
-
-All plugins must ship a `symi.plugin.json` file with an inline JSON Schema
-(`configSchema`, even if empty). Missing/invalid manifests or schemas prevent
-the plugin from loading and fail config validation.
-
-### Install
-
-```bash
-symi plugins install <path-or-spec>
-symi plugins install <npm-spec> --pin
-```
-
-Security note: treat plugin installs like running code. Prefer pinned versions.
-
-Npm specs are **registry-only** (package name + optional version/tag). Git/URL/file
-specs are rejected. Dependency installs run with `--ignore-scripts` for safety.
-
-Supported archives: `.zip`, `.tgz`, `.tar.gz`, `.tar`.
-
-Use `--link` to avoid copying a local directory (adds to `plugins.load.paths`):
-
-```bash
-symi plugins install -l ./my-plugin
-```
-
-Use `--pin` on npm installs to save the resolved exact spec (`name@version`) in
-`plugins.installs` while keeping the default behavior unpinned.
-
-### Uninstall
-
-```bash
-symi plugins uninstall <id>
-symi plugins uninstall <id> --dry-run
-symi plugins uninstall <id> --keep-files
-```
-
-`uninstall` removes plugin records from `plugins.entries`, `plugins.installs`,
-the plugin allowlist, and linked `plugins.load.paths` entries when applicable.
-For active memory plugins, the memory slot resets to `memory-core`.
-
-By default, uninstall also removes the plugin install directory under the active
-state dir extensions root (`$SYMI_STATE_DIR/extensions/<id>`). Use
-`--keep-files` to keep files on disk.
-
-`--keep-config` is supported as a deprecated alias for `--keep-files`.
-
-### Update
-
-```bash
-symi plugins update <id>
-symi plugins update --all
-symi plugins update <id> --dry-run
-```
-
-Updates only apply to plugins installed from npm (tracked in `plugins.installs`).
-
-When a stored integrity hash exists and the fetched artifact hash changes,
-Symi prints a warning and asks for confirmation before proceeding. Use
-global `--yes` to bypass prompts in CI/non-interactive runs.

package/docs/cli/reset.md

@@ -1,17 +0,0 @@
----
-summary: "CLI reference for `symi reset` (reset local state/config)"
-read_when:
-  - You want to wipe local state while keeping the CLI installed
-  - You want a dry-run of what would be removed
-title: "reset"
----
-
-# `symi reset`
-
-Reset local config/state (keeps the CLI installed).
-
-```bash
-symi reset
-symi reset --dry-run
-symi reset --scope config+creds+sessions --yes --non-interactive
-```

package/docs/cli/sandbox.md

@@ -1,152 +0,0 @@
----
-title: Sandbox CLI
-summary: "Manage sandbox containers and inspect effective sandbox policy"
-read_when: "You are managing sandbox containers or debugging sandbox/tool-policy behavior."
-status: active
----
-
-# Sandbox CLI
-
-Manage Docker-based sandbox containers for isolated agent execution.
-
-## Overview
-
-Symi can run agents in isolated Docker containers for security. The `sandbox` commands help you manage these containers, especially after updates or configuration changes.
-
-## Commands
-
-### `symi sandbox explain`
-
-Inspect the **effective** sandbox mode/scope/workspace access, sandbox tool policy, and elevated gates (with fix-it config key paths).
-
-```bash
-symi sandbox explain
-symi sandbox explain --session agent:main:main
-symi sandbox explain --agent work
-symi sandbox explain --json
-```
-
-### `symi sandbox list`
-
-List all sandbox containers with their status and configuration.
-
-```bash
-symi sandbox list
-symi sandbox list --browser  # List only browser containers
-symi sandbox list --json     # JSON output
-```
-
-**Output includes:**
-
-- Container name and status (running/stopped)
-- Docker image and whether it matches config
-- Age (time since creation)
-- Idle time (time since last use)
-- Associated session/agent
-
-### `symi sandbox recreate`
-
-Remove sandbox containers to force recreation with updated images/config.
-
-```bash
-symi sandbox recreate --all                # Recreate all containers
-symi sandbox recreate --session main       # Specific session
-symi sandbox recreate --agent mybot        # Specific agent
-symi sandbox recreate --browser            # Only browser containers
-symi sandbox recreate --all --force        # Skip confirmation
-```
-
-**Options:**
-
-- `--all`: Recreate all sandbox containers
-- `--session <key>`: Recreate container for specific session
-- `--agent <id>`: Recreate containers for specific agent
-- `--browser`: Only recreate browser containers
-- `--force`: Skip confirmation prompt
-
-**Important:** Containers are automatically recreated when the agent is next used.
-
-## Use Cases
-
-### After updating Docker images
-
-```bash
-# Pull new image
-docker pull symi-sandbox:latest
-docker tag symi-sandbox:latest symi-sandbox:bookworm-slim
-
-# Update config to use new image
-# Edit config: agents.defaults.sandbox.docker.image (or agents.list[].sandbox.docker.image)
-
-# Recreate containers
-symi sandbox recreate --all
-```
-
-### After changing sandbox configuration
-
-```bash
-# Edit config: agents.defaults.sandbox.* (or agents.list[].sandbox.*)
-
-# Recreate to apply new config
-symi sandbox recreate --all
-```
-
-### After changing setupCommand
-
-```bash
-symi sandbox recreate --all
-# or just one agent:
-symi sandbox recreate --agent family
-```
-
-### For a specific agent only
-
-```bash
-# Update only one agent's containers
-symi sandbox recreate --agent alfred
-```
-
-## Why is this needed?
-
-**Problem:** When you update sandbox Docker images or configuration:
-
-- Existing containers continue running with old settings
-- Containers are only pruned after 24h of inactivity
-- Regularly-used agents keep old containers running indefinitely
-
-**Solution:** Use `symi sandbox recreate` to force removal of old containers. They'll be recreated automatically with current settings when next needed.
-
-Tip: prefer `symi sandbox recreate` over manual `docker rm`. It uses the
-Gateway’s container naming and avoids mismatches when scope/session keys change.
-
-## Configuration
-
-Sandbox settings live in `~/.symi/symi.json` under `agents.defaults.sandbox` (per-agent overrides go in `agents.list[].sandbox`):
-
-```jsonc
-{
-  "agents": {
-    "defaults": {
-      "sandbox": {
-        "mode": "all", // off, non-main, all
-        "scope": "agent", // session, agent, shared
-        "docker": {
-          "image": "symi-sandbox:bookworm-slim",
-          "containerPrefix": "symi-sbx-",
-          // ... more Docker options
-        },
-        "prune": {
-          "idleHours": 24, // Auto-prune after 24h idle
-          "maxAgeDays": 7, // Auto-prune after 7 days
-        },
-      },
-    },
-  },
-}
-```
-
-## See Also
-
-- [Sandbox Documentation](/gateway/sandboxing)
-- [Agent Configuration](/concepts/agent-workspace)
-- [Doctor Command](/gateway/doctor) - Check sandbox setup

package/docs/cli/security.md

@@ -1,64 +0,0 @@
----
-summary: "CLI reference for `symi security` (audit and fix common security footguns)"
-read_when:
-  - You want to run a quick security audit on config/state
-  - You want to apply safe “fix” suggestions (chmod, tighten defaults)
-title: "security"
----
-
-# `symi security`
-
-Security tools (audit + optional fixes).
-
-Related:
-
-- Security guide: [Security](/gateway/security)
-
-## Audit
-
-```bash
-symi security audit
-symi security audit --deep
-symi security audit --fix
-symi security audit --json
-```
-
-The audit warns when multiple DM senders share the main session and recommends **secure DM mode**: `session.dmScope="per-channel-peer"` (or `per-account-channel-peer` for multi-account channels) for shared inboxes.
-This is for cooperative/shared inbox hardening. A single Gateway shared by mutually untrusted/adversarial operators is not a recommended setup; split trust boundaries with separate gateways (or separate OS users/hosts).
-It also warns when small models (`<=300B`) are used without sandboxing and with web/browser tools enabled.
-For webhook ingress, it warns when `hooks.defaultSessionKey` is unset, when request `sessionKey` overrides are enabled, and when overrides are enabled without `hooks.allowedSessionKeyPrefixes`.
-It also warns when sandbox Docker settings are configured while sandbox mode is off, when `gateway.nodes.denyCommands` uses ineffective pattern-like/unknown entries, when global `tools.profile="minimal"` is overridden by agent tool profiles, and when installed extension plugin tools may be reachable under permissive tool policy.
-It also warns when sandbox browser uses Docker `bridge` network without `sandbox.browser.cdpSourceRange`.
-It also warns when existing sandbox browser Docker containers have missing/stale hash labels (for example pre-migration containers missing `symi.browserConfigEpoch`) and recommends `symi sandbox recreate --browser --all`.
-It also warns when npm-based plugin/hook install records are unpinned, missing integrity metadata, or drift from currently installed package versions.
-It warns when `gateway.auth.mode="none"` leaves Gateway HTTP APIs reachable without a shared secret (`/tools/invoke` plus any enabled `/v1/*` endpoint).
-
-## JSON output
-
-Use `--json` for CI/policy checks:
-
-```bash
-symi security audit --json | jq '.summary'
-symi security audit --deep --json | jq '.findings[] | select(.severity=="critical") | .checkId'
-```
-
-If `--fix` and `--json` are combined, output includes both fix actions and final report:
-
-```bash
-symi security audit --fix --json | jq '{fix: .fix.ok, summary: .report.summary}'
-```
-
-## What `--fix` changes
-
-`--fix` applies safe, deterministic remediations:
-
-- flips common `groupPolicy="open"` to `groupPolicy="allowlist"` (including account variants in supported channels)
-- sets `logging.redactSensitive` from `"off"` to `"tools"`
-- tightens permissions for state/config and common sensitive files (`credentials/*.json`, `auth-profiles.json`, `sessions.json`, session `*.jsonl`)
-
-`--fix` does **not**:
-
-- rotate tokens/passwords/API keys
-- disable tools (`gateway`, `cron`, `exec`, etc.)
-- change gateway bind/auth/network exposure choices
-- remove or rewrite plugins/skills

package/docs/cli/sessions.md

@@ -1,16 +0,0 @@
----
-summary: "CLI reference for `symi sessions` (list stored sessions + usage)"
-read_when:
-  - You want to list stored sessions and see recent activity
-title: "sessions"
----
-
-# `symi sessions`
-
-List stored conversation sessions.
-
-```bash
-symi sessions
-symi sessions --active 120
-symi sessions --json
-```

package/docs/cli/setup.md

@@ -1,29 +0,0 @@
----
-summary: "CLI reference for `symi setup` (initialize config + workspace)"
-read_when:
-  - You’re doing first-run setup without the full onboarding wizard
-  - You want to set the default workspace path
-title: "setup"
----
-
-# `symi setup`
-
-Initialize `~/.symi/symi.json` and the agent workspace.
-
-Related:
-
-- Getting started: [Getting started](/start/getting-started)
-- Wizard: [Onboarding](/start/onboarding)
-
-## Examples
-
-```bash
-symi setup
-symi setup --workspace ~/.symi/workspace
-```
-
-To run the wizard via setup:
-
-```bash
-symi setup --wizard
-```

package/docs/cli/skills.md

@@ -1,26 +0,0 @@
----
-summary: "CLI reference for `symi skills` (list/info/check) and skill eligibility"
-read_when:
-  - You want to see which skills are available and ready to run
-  - You want to debug missing binaries/env/config for skills
-title: "skills"
----
-
-# `symi skills`
-
-Inspect skills (bundled + workspace + managed overrides) and see what’s eligible vs missing requirements.
-
-Related:
-
-- Skills system: [Skills](/tools/skills)
-- Skills config: [Skills config](/tools/skills-config)
-- SymiHub installs: [SymiHub](/tools/symihub)
-
-## Commands
-
-```bash
-symi skills list
-symi skills list --eligible
-symi skills info <name>
-symi skills check
-```

package/docs/cli/status.md

@@ -1,25 +0,0 @@
----
-summary: "CLI reference for `symi status` (diagnostics, probes, usage snapshots)"
-read_when:
-  - You want a quick diagnosis of channel health + recent session recipients
-  - You want a pasteable “all” status for debugging
-title: "status"
----
-
-# `symi status`
-
-Diagnostics for channels + sessions.
-
-```bash
-symi status
-symi status --all
-symi status --deep
-symi status --usage
-```
-
-Notes:
-
-- Output includes per-agent session stores when multiple agents are configured.
-- Overview includes Gateway + node host service install/runtime status when available.
-- Overview includes update channel + git SHA (for source checkouts).
-- Update info surfaces in the Overview; if an update is available, status prints a hint to run `symi update` (see [Updating](/install/updating)).

package/docs/cli/system.md

@@ -1,60 +0,0 @@
----
-summary: "CLI reference for `symi system` (system events, heartbeat, presence)"
-read_when:
-  - You want to enqueue a system event without creating a cron job
-  - You need to enable or disable heartbeats
-  - You want to inspect system presence entries
-title: "system"
----
-
-# `symi system`
-
-System-level helpers for the Gateway: enqueue system events, control heartbeats,
-and view presence.
-
-## Common commands
-
-```bash
-symi system event --text "Check for urgent follow-ups" --mode now
-symi system heartbeat enable
-symi system heartbeat last
-symi system presence
-```
-
-## `system event`
-
-Enqueue a system event on the **main** session. The next heartbeat will inject
-it as a `System:` line in the prompt. Use `--mode now` to trigger the heartbeat
-immediately; `next-heartbeat` waits for the next scheduled tick.
-
-Flags:
-
-- `--text <text>`: required system event text.
-- `--mode <mode>`: `now` or `next-heartbeat` (default).
-- `--json`: machine-readable output.
-
-## `system heartbeat last|enable|disable`
-
-Heartbeat controls:
-
-- `last`: show the last heartbeat event.
-- `enable`: turn heartbeats back on (use this if they were disabled).
-- `disable`: pause heartbeats.
-
-Flags:
-
-- `--json`: machine-readable output.
-
-## `system presence`
-
-List the current system presence entries the Gateway knows about (nodes,
-instances, and similar status lines).
-
-Flags:
-
-- `--json`: machine-readable output.
-
-## Notes
-
-- Requires a running Gateway reachable by your current config (local or remote).
-- System events are ephemeral and not persisted across restarts.

package/docs/cli/tui.md

@@ -1,23 +0,0 @@
----
-summary: "CLI reference for `symi tui` (terminal UI connected to the Gateway)"
-read_when:
-  - You want a terminal UI for the Gateway (remote-friendly)
-  - You want to pass url/token/session from scripts
-title: "tui"
----
-
-# `symi tui`
-
-Open the terminal UI connected to the Gateway.
-
-Related:
-
-- TUI guide: [TUI](/web/tui)
-
-## Examples
-
-```bash
-symi tui
-symi tui --url ws://127.0.0.1:18789 --token <token>
-symi tui --session main --deliver
-```

package/docs/cli/uninstall.md

@@ -1,17 +0,0 @@
----
-summary: "CLI reference for `symi uninstall` (remove gateway service + local data)"
-read_when:
-  - You want to remove the gateway service and/or local state
-  - You want a dry-run first
-title: "uninstall"
----
-
-# `symi uninstall`
-
-Uninstall the gateway service + local data (CLI remains).
-
-```bash
-symi uninstall
-symi uninstall --all --yes
-symi uninstall --dry-run
-```

package/docs/cli/update.md

@@ -1,98 +0,0 @@
----
-summary: "CLI reference for `symi update` (safe-ish source update + gateway auto-restart)"
-read_when:
-  - You want to update a source checkout safely
-  - You need to understand `--update` shorthand behavior
-title: "update"
----
-
-# `symi update`
-
-Safely update Symi and switch between stable/beta/dev channels.
-
-If you installed via **npm/pnpm** (global install, no git metadata), updates happen via the package manager flow in [Updating](/install/updating).
-
-## Usage
-
-```bash
-symi update
-symi update status
-symi update wizard
-symi update --channel beta
-symi update --channel dev
-symi update --tag beta
-symi update --no-restart
-symi update --json
-symi --update
-```
-
-## Options
-
-- `--no-restart`: skip restarting the Gateway service after a successful update.
-- `--channel <stable|beta|dev>`: set the update channel (git + npm; persisted in config).
-- `--tag <dist-tag|version>`: override the npm dist-tag or version for this update only.
-- `--json`: print machine-readable `UpdateRunResult` JSON.
-- `--timeout <seconds>`: per-step timeout (default is 1200s).
-
-Note: downgrades require confirmation because older versions can break configuration.
-
-## `update status`
-
-Show the active update channel + git tag/branch/SHA (for source checkouts), plus update availability.
-
-```bash
-symi update status
-symi update status --json
-symi update status --timeout 10
-```
-
-Options:
-
-- `--json`: print machine-readable status JSON.
-- `--timeout <seconds>`: timeout for checks (default is 3s).
-
-## `update wizard`
-
-Interactive flow to pick an update channel and confirm whether to restart the Gateway
-after updating (default is to restart). If you select `dev` without a git checkout, it
-offers to create one.
-
-## What it does
-
-When you switch channels explicitly (`--channel ...`), Symi also keeps the
-install method aligned:
-
-- `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.
-
-## Git checkout flow
-
-Channels:
-
-- `stable`: checkout the latest non-beta tag, then build + doctor.
-- `beta`: checkout the latest `-beta` tag, then build + doctor.
-- `dev`: checkout `main`, then fetch + rebase.
-
-High-level:
-
-1. Requires a clean worktree (no uncommitted changes).
-2. Switches to the selected channel (tag or branch).
-3. Fetches upstream (dev only).
-4. Dev only: preflight lint + TypeScript build in a temp worktree; if the tip fails, walks back up to 10 commits to find the newest clean build.
-5. Rebases onto the selected commit (dev only).
-6. Installs deps (pnpm preferred; npm fallback).
-7. Builds + builds the Control UI.
-8. Runs `symi doctor` as the final “safe update” check.
-9. Syncs plugins to the active channel (dev uses bundled extensions; stable/beta uses npm) and updates npm-installed plugins.
-
-## `--update` shorthand
-
-`symi --update` rewrites to `symi update` (useful for shells and launcher scripts).
-
-## See also
-
-- `symi doctor` (offers to run update first on git checkouts)
-- [Development channels](/install/development-channels)
-- [Updating](/install/updating)
-- [CLI reference](/cli)

package/docs/cli/voicecall.md

@@ -1,34 +0,0 @@
----
-summary: "CLI reference for `symi voicecall` (voice-call plugin command surface)"
-read_when:
-  - You use the voice-call plugin and want the CLI entry points
-  - You want quick examples for `voicecall call|continue|status|tail|expose`
-title: "voicecall"
----
-
-# `symi voicecall`
-
-`voicecall` is a plugin-provided command. It only appears if the voice-call plugin is installed and enabled.
-
-Primary doc:
-
-- Voice-call plugin: [Voice Call](/plugins/voice-call)
-
-## Common commands
-
-```bash
-symi voicecall status --call-id <id>
-symi voicecall call --to "+15555550123" --message "Hello" --mode notify
-symi voicecall continue --call-id <id> --message "Any questions?"
-symi voicecall end --call-id <id>
-```
-
-## Exposing webhooks (Tailscale)
-
-```bash
-symi voicecall expose --mode serve
-symi voicecall expose --mode funnel
-symi voicecall unexpose
-```
-
-Security note: only expose the webhook endpoint to networks you trust. Prefer Tailscale Serve over Funnel when possible.

package/docs/cli/webhooks.md

@@ -1,25 +0,0 @@
----
-summary: "CLI reference for `symi webhooks` (webhook helpers + Gmail Pub/Sub)"
-read_when:
-  - You want to wire Gmail Pub/Sub events into Symi
-  - You want webhook helper commands
-title: "webhooks"
----
-
-# `symi webhooks`
-
-Webhook helpers and integrations (Gmail Pub/Sub, webhook helpers).
-
-Related:
-
-- Webhooks: [Webhook](/automation/webhook)
-- Gmail Pub/Sub: [Gmail Pub/Sub](/automation/gmail-pubsub)
-
-## Gmail
-
-```bash
-symi webhooks gmail setup --account you@example.com
-symi webhooks gmail run
-```
-
-See [Gmail Pub/Sub documentation](/automation/gmail-pubsub) for details.