synurex 2026.2.19-1

package/docs/cli/logs.md

@@ -0,0 +1,24 @@
+---
+summary: "CLI reference for `Synurex logs` (tail gateway logs via RPC)"
+read_when:
+  - You need to tail Gateway logs remotely (without SSH)
+  - You want JSON log lines for tooling
+title: "logs"
+---
+
+# `Synurex logs`
+
+Tail Gateway file logs over RPC (works in remote mode).
+
+Related:
+
+- Logging overview: [Logging](/logging)
+
+## Examples
+
+```bash
+Synurex logs
+Synurex logs --follow
+Synurex logs --json
+Synurex logs --limit 500
+```

package/docs/cli/memory.md

@@ -0,0 +1,45 @@
+---
+summary: "CLI reference for `Synurex memory` (status/index/search)"
+read_when:
+  - You want to index or search semantic memory
+  - You’re debugging memory availability or indexing
+title: "memory"
+---
+
+# `Synurex memory`
+
+Manage semantic memory indexing and search.
+Provided by the active memory plugin (default: `memory-core`; set `plugins.slots.memory = "none"` to disable).
+
+Related:
+
+- Memory concept: [Memory](/concepts/memory)
+- Plugins: [Plugins](/tools/plugin)
+
+## Examples
+
+```bash
+Synurex memory status
+Synurex memory status --deep
+Synurex memory status --deep --index
+Synurex memory status --deep --index --verbose
+Synurex memory index
+Synurex memory index --verbose
+Synurex memory search "release checklist"
+Synurex memory status --agent main
+Synurex memory index --agent main --verbose
+```
+
+## Options
+
+Common:
+
+- `--agent <id>`: scope to a single agent (default: all configured agents).
+- `--verbose`: emit detailed logs during probes and indexing.
+
+Notes:
+
+- `memory status --deep` probes vector + embedding availability.
+- `memory status --deep --index` runs a reindex if the store is dirty.
+- `memory index --verbose` prints per-phase details (provider, model, sources, batch activity).
+- `memory status` includes any extra paths configured via `memorySearch.extraPaths`.

package/docs/cli/message.md

@@ -0,0 +1,239 @@
+---
+summary: "CLI reference for `Synurex message` (send + channel actions)"
+read_when:
+  - Adding or modifying message CLI actions
+  - Changing outbound channel behavior
+title: "message"
+---
+
+# `Synurex message`
+
+Single outbound command for sending messages and channel actions
+(Discord/Google Chat/Slack/Mattermost (plugin)/Telegram/WhatsApp/Signal/iMessage/MS Teams).
+
+## Usage
+
+```
+Synurex message <subcommand> [flags]
+```
+
+Channel selection:
+
+- `--channel` required if more than one channel is configured.
+- If exactly one channel is configured, it becomes the default.
+- Values: `whatsapp|telegram|discord|googlechat|slack|mattermost|signal|imessage|msteams` (Mattermost requires plugin)
+
+Target formats (`--target`):
+
+- WhatsApp: E.164 or group JID
+- Telegram: chat id or `@username`
+- Discord: `channel:<id>` or `user:<id>` (or `<@id>` mention; raw numeric ids are treated as channels)
+- Google Chat: `spaces/<spaceId>` or `users/<userId>`
+- Slack: `channel:<id>` or `user:<id>` (raw channel id is accepted)
+- Mattermost (plugin): `channel:<id>`, `user:<id>`, or `@username` (bare ids are treated as channels)
+- Signal: `+E.164`, `group:<id>`, `signal:+E.164`, `signal:group:<id>`, or `username:<name>`/`u:<name>`
+- iMessage: handle, `chat_id:<id>`, `chat_guid:<guid>`, or `chat_identifier:<id>`
+- MS Teams: conversation id (`19:...@thread.tacv2`) or `conversation:<id>` or `user:<aad-object-id>`
+
+Name lookup:
+
+- For supported providers (Discord/Slack/etc), channel names like `Help` or `#help` are resolved via the directory cache.
+- On cache miss, Synurex will attempt a live directory lookup when the provider supports it.
+
+## Common flags
+
+- `--channel <name>`
+- `--account <id>`
+- `--target <dest>` (target channel or user for send/poll/read/etc)
+- `--targets <name>` (repeat; broadcast only)
+- `--json`
+- `--dry-run`
+- `--verbose`
+
+## Actions
+
+### Core
+
+- `send`
+  - Channels: WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/MS Teams
+  - Required: `--target`, plus `--message` or `--media`
+  - Optional: `--media`, `--reply-to`, `--thread-id`, `--gif-playback`
+  - Telegram only: `--buttons` (requires `channels.telegram.capabilities.inlineButtons` to allow it)
+  - Telegram only: `--thread-id` (forum topic id)
+  - Slack only: `--thread-id` (thread timestamp; `--reply-to` uses the same field)
+  - WhatsApp only: `--gif-playback`
+
+- `poll`
+  - Channels: WhatsApp/Discord/MS Teams
+  - Required: `--target`, `--poll-question`, `--poll-option` (repeat)
+  - Optional: `--poll-multi`
+  - Discord only: `--poll-duration-hours`, `--message`
+
+- `react`
+  - Channels: Discord/Google Chat/Slack/Telegram/WhatsApp/Signal
+  - Required: `--message-id`, `--target`
+  - Optional: `--emoji`, `--remove`, `--participant`, `--from-me`, `--target-author`, `--target-author-uuid`
+  - Note: `--remove` requires `--emoji` (omit `--emoji` to clear own reactions where supported; see /tools/reactions)
+  - WhatsApp only: `--participant`, `--from-me`
+  - Signal group reactions: `--target-author` or `--target-author-uuid` required
+
+- `reactions`
+  - Channels: Discord/Google Chat/Slack
+  - Required: `--message-id`, `--target`
+  - Optional: `--limit`
+
+- `read`
+  - Channels: Discord/Slack
+  - Required: `--target`
+  - Optional: `--limit`, `--before`, `--after`
+  - Discord only: `--around`
+
+- `edit`
+  - Channels: Discord/Slack
+  - Required: `--message-id`, `--message`, `--target`
+
+- `delete`
+  - Channels: Discord/Slack/Telegram
+  - Required: `--message-id`, `--target`
+
+- `pin` / `unpin`
+  - Channels: Discord/Slack
+  - Required: `--message-id`, `--target`
+
+- `pins` (list)
+  - Channels: Discord/Slack
+  - Required: `--target`
+
+- `permissions`
+  - Channels: Discord
+  - Required: `--target`
+
+- `search`
+  - Channels: Discord
+  - Required: `--guild-id`, `--query`
+  - Optional: `--channel-id`, `--channel-ids` (repeat), `--author-id`, `--author-ids` (repeat), `--limit`
+
+### Threads
+
+- `thread create`
+  - Channels: Discord
+  - Required: `--thread-name`, `--target` (channel id)
+  - Optional: `--message-id`, `--auto-archive-min`
+
+- `thread list`
+  - Channels: Discord
+  - Required: `--guild-id`
+  - Optional: `--channel-id`, `--include-archived`, `--before`, `--limit`
+
+- `thread reply`
+  - Channels: Discord
+  - Required: `--target` (thread id), `--message`
+  - Optional: `--media`, `--reply-to`
+
+### Emojis
+
+- `emoji list`
+  - Discord: `--guild-id`
+  - Slack: no extra flags
+
+- `emoji upload`
+  - Channels: Discord
+  - Required: `--guild-id`, `--emoji-name`, `--media`
+  - Optional: `--role-ids` (repeat)
+
+### Stickers
+
+- `sticker send`
+  - Channels: Discord
+  - Required: `--target`, `--sticker-id` (repeat)
+  - Optional: `--message`
+
+- `sticker upload`
+  - Channels: Discord
+  - Required: `--guild-id`, `--sticker-name`, `--sticker-desc`, `--sticker-tags`, `--media`
+
+### Roles / Channels / Members / Voice
+
+- `role info` (Discord): `--guild-id`
+- `role add` / `role remove` (Discord): `--guild-id`, `--user-id`, `--role-id`
+- `channel info` (Discord): `--target`
+- `channel list` (Discord): `--guild-id`
+- `member info` (Discord/Slack): `--user-id` (+ `--guild-id` for Discord)
+- `voice status` (Discord): `--guild-id`, `--user-id`
+
+### Events
+
+- `event list` (Discord): `--guild-id`
+- `event create` (Discord): `--guild-id`, `--event-name`, `--start-time`
+  - Optional: `--end-time`, `--desc`, `--channel-id`, `--location`, `--event-type`
+
+### Moderation (Discord)
+
+- `timeout`: `--guild-id`, `--user-id` (optional `--duration-min` or `--until`; omit both to clear timeout)
+- `kick`: `--guild-id`, `--user-id` (+ `--reason`)
+- `ban`: `--guild-id`, `--user-id` (+ `--delete-days`, `--reason`)
+  - `timeout` also supports `--reason`
+
+### Broadcast
+
+- `broadcast`
+  - Channels: any configured channel; use `--channel all` to target all providers
+  - Required: `--targets` (repeat)
+  - Optional: `--message`, `--media`, `--dry-run`
+
+## Examples
+
+Send a Discord reply:
+
+```
+Synurex message send --channel discord \
+  --target channel:123 --message "hi" --reply-to 456
+```
+
+Create a Discord poll:
+
+```
+Synurex message poll --channel discord \
+  --target channel:123 \
+  --poll-question "Snack?" \
+  --poll-option Pizza --poll-option Sushi \
+  --poll-multi --poll-duration-hours 48
+```
+
+Send a Teams proactive message:
+
+```
+Synurex message send --channel msteams \
+  --target conversation:19:abc@thread.tacv2 --message "hi"
+```
+
+Create a Teams poll:
+
+```
+Synurex message poll --channel msteams \
+  --target conversation:19:abc@thread.tacv2 \
+  --poll-question "Lunch?" \
+  --poll-option Pizza --poll-option Sushi
+```
+
+React in Slack:
+
+```
+Synurex message react --channel slack \
+  --target C123 --message-id 456 --emoji "✅"
+```
+
+React in a Signal group:
+
+```
+Synurex message react --channel signal \
+  --target signal:group:abc123 --message-id 1737630212345 \
+  --emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000
+```
+
+Send Telegram inline buttons:
+
+```
+Synurex message send --channel telegram --target @mychat --message "Choose:" \
+  --buttons '[ [{"text":"Yes","callback_data":"cmd:yes"}], [{"text":"No","callback_data":"cmd:no"}] ]'
+```

package/docs/cli/models.md

@@ -0,0 +1,79 @@
+---
+summary: "CLI reference for `Synurex models` (status/list/set/scan, aliases, fallbacks, auth)"
+read_when:
+  - You want to change default models or view provider auth status
+  - You want to scan available models/providers and debug auth profiles
+title: "models"
+---
+
+# `Synurex models`
+
+Model discovery, scanning, and configuration (default model, fallbacks, auth profiles).
+
+Related:
+
+- Providers + models: [Models](/providers/models)
+- Provider auth setup: [Getting started](/start/getting-started)
+
+## Common commands
+
+```bash
+Synurex models status
+Synurex models list
+Synurex models set <model-or-alias>
+Synurex models scan
+```
+
+`Synurex models status` shows the resolved default/fallbacks plus an auth overview.
+When provider usage snapshots are available, the OAuth/token status section includes
+provider usage headers.
+Add `--probe` to run live auth probes against each configured provider profile.
+Probes are real requests (may consume tokens and trigger rate limits).
+Use `--agent <id>` to inspect a configured agent’s model/auth state. When omitted,
+the command uses `SYNUREX_AGENT_DIR`/`PI_CODING_AGENT_DIR` if set, otherwise the
+configured default agent.
+
+Notes:
+
+- `models set <model-or-alias>` accepts `provider/model` or an alias.
+- Model refs are parsed by splitting on the **first** `/`. If the model ID includes `/` (OpenRouter-style), include the provider prefix (example: `openrouter/moonshotai/kimi-k2`).
+- If you omit the provider, Synurex treats the input as an alias or a model for the **default provider** (only works when there is no `/` in the model ID).
+
+### `models status`
+
+Options:
+
+- `--json`
+- `--plain`
+- `--check` (exit 1=expired/missing, 2=expiring)
+- `--probe` (live probe of configured auth profiles)
+- `--probe-provider <name>` (probe one provider)
+- `--probe-profile <id>` (repeat or comma-separated profile ids)
+- `--probe-timeout <ms>`
+- `--probe-concurrency <n>`
+- `--probe-max-tokens <n>`
+- `--agent <id>` (configured agent id; overrides `SYNUREX_AGENT_DIR`/`PI_CODING_AGENT_DIR`)
+
+## Aliases + fallbacks
+
+```bash
+Synurex models aliases list
+Synurex models fallbacks list
+```
+
+## Auth profiles
+
+```bash
+Synurex models auth add
+Synurex models auth login --provider <id>
+Synurex models auth setup-token
+Synurex models auth paste-token
+```
+
+`models auth login` runs a provider plugin’s auth flow (OAuth/API key). Use
+`Synurex plugins list` to see which providers are installed.
+
+Notes:
+
+- `setup-token` prompts for a setup-token value (generate it with `claude setup-token` on any machine).
+- `paste-token` accepts a token string generated elsewhere or from automation.

package/docs/cli/node.md

@@ -0,0 +1,112 @@
+---
+summary: "CLI reference for `Synurex node` (headless node host)"
+read_when:
+  - Running the headless node host
+  - Pairing a non-macOS node for system.run
+title: "node"
+---
+
+# `Synurex node`
+
+Run a **headless node host** that connects to the Gateway WebSocket and exposes
+`system.run` / `system.which` on this machine.
+
+## Why use a node host?
+
+Use a node host when you want agents to **run commands on other machines** in your
+network without installing a full macOS companion app there.
+
+Common use cases:
+
+- Run commands on remote Linux/Windows boxes (build servers, lab machines, NAS).
+- Keep exec **sandboxed** on the gateway, but delegate approved runs to other hosts.
+- Provide a lightweight, headless execution target for automation or CI nodes.
+
+Execution is still guarded by **exec approvals** and per‑agent allowlists on the
+node host, so you can keep command access scoped and explicit.
+
+## Browser proxy (zero-config)
+
+Node hosts automatically advertise a browser proxy if `browser.enabled` is not
+disabled on the node. This lets the agent use browser automation on that node
+without extra configuration.
+
+Disable it on the node if needed:
+
+```json5
+{
+  nodeHost: {
+    browserProxy: {
+      enabled: false,
+    },
+  },
+}
+```
+
+## Run (foreground)
+
+```bash
+Synurex node run --host <gateway-host> --port 18789
+```
+
+Options:
+
+- `--host <host>`: Gateway WebSocket host (default: `127.0.0.1`)
+- `--port <port>`: Gateway WebSocket port (default: `18789`)
+- `--tls`: Use TLS for the gateway connection
+- `--tls-fingerprint <sha256>`: Expected TLS certificate fingerprint (sha256)
+- `--node-id <id>`: Override node id (clears pairing token)
+- `--display-name <name>`: Override the node display name
+
+## Service (background)
+
+Install a headless node host as a user service.
+
+```bash
+Synurex node install --host <gateway-host> --port 18789
+```
+
+Options:
+
+- `--host <host>`: Gateway WebSocket host (default: `127.0.0.1`)
+- `--port <port>`: Gateway WebSocket port (default: `18789`)
+- `--tls`: Use TLS for the gateway connection
+- `--tls-fingerprint <sha256>`: Expected TLS certificate fingerprint (sha256)
+- `--node-id <id>`: Override node id (clears pairing token)
+- `--display-name <name>`: Override the node display name
+- `--runtime <runtime>`: Service runtime (`node` or `bun`)
+- `--force`: Reinstall/overwrite if already installed
+
+Manage the service:
+
+```bash
+Synurex node status
+Synurex node stop
+Synurex node restart
+Synurex node uninstall
+```
+
+Use `Synurex node run` for a foreground node host (no service).
+
+Service commands accept `--json` for machine-readable output.
+
+## Pairing
+
+The first connection creates a pending node pair request on the Gateway.
+Approve it via:
+
+```bash
+Synurex nodes pending
+Synurex nodes approve <requestId>
+```
+
+The node host stores its node id, token, display name, and gateway connection info in
+`~/.synurex/node.json`.
+
+## Exec approvals
+
+`system.run` is gated by local exec approvals:
+
+- `~/.synurex/exec-approvals.json`
+- [Exec approvals](/tools/exec-approvals)
+- `Synurex approvals --node <id|name|ip>` (edit from the Gateway)

package/docs/cli/nodes.md

@@ -0,0 +1,73 @@
+---
+summary: "CLI reference for `Synurex nodes` (list/status/approve/invoke, camera/canvas/screen)"
+read_when:
+  - You’re managing paired nodes (cameras, screen, canvas)
+  - You need to approve requests or invoke node commands
+title: "nodes"
+---
+
+# `Synurex nodes`
+
+Manage paired nodes (devices) and invoke node capabilities.
+
+Related:
+
+- Nodes overview: [Nodes](/nodes)
+- Camera: [Camera nodes](/nodes/camera)
+- Images: [Image nodes](/nodes/images)
+
+Common options:
+
+- `--url`, `--token`, `--timeout`, `--json`
+
+## Common commands
+
+```bash
+Synurex nodes list
+Synurex nodes list --connected
+Synurex nodes list --last-connected 24h
+Synurex nodes pending
+Synurex nodes approve <requestId>
+Synurex nodes status
+Synurex nodes status --connected
+Synurex nodes status --last-connected 24h
+```
+
+`nodes list` prints pending/paired tables. Paired rows include the most recent connect age (Last Connect).
+Use `--connected` to only show currently-connected nodes. Use `--last-connected <duration>` to
+filter to nodes that connected within a duration (e.g. `24h`, `7d`).
+
+## Invoke / run
+
+```bash
+Synurex nodes invoke --node <id|name|ip> --command <command> --params <json>
+Synurex nodes run --node <id|name|ip> <command...>
+Synurex nodes run --raw "git status"
+Synurex nodes run --agent main --node <id|name|ip> --raw "git status"
+```
+
+Invoke flags:
+
+- `--params <json>`: JSON object string (default `{}`).
+- `--invoke-timeout <ms>`: node invoke timeout (default `15000`).
+- `--idempotency-key <key>`: optional idempotency key.
+
+### Exec-style defaults
+
+`nodes run` mirrors the model’s exec behavior (defaults + approvals):
+
+- Reads `tools.exec.*` (plus `agents.list[].tools.exec.*` overrides).
+- Uses exec approvals (`exec.approval.request`) before invoking `system.run`.
+- `--node` can be omitted when `tools.exec.node` is set.
+- Requires a node that advertises `system.run` (macOS companion app or headless node host).
+
+Flags:
+
+- `--cwd <path>`: working directory.
+- `--env <key=val>`: env override (repeatable).
+- `--command-timeout <ms>`: command timeout.
+- `--invoke-timeout <ms>`: node invoke timeout (default `30000`).
+- `--needs-screen-recording`: require screen recording permission.
+- `--raw <command>`: run a shell string (`/bin/sh -lc` or `cmd.exe /c`).
+- `--agent <id>`: agent-scoped approvals/allowlists (defaults to configured agent).
+- `--ask <off|on-miss|always>`, `--security <deny|allowlist|full>`: overrides.

package/docs/cli/onboard.md

@@ -0,0 +1,43 @@
+---
+summary: "CLI reference for `Synurex onboard` (interactive onboarding wizard)"
+read_when:
+  - You want guided setup for gateway, workspace, auth, channels, and skills
+title: "onboard"
+---
+
+# `Synurex onboard`
+
+Interactive onboarding wizard (local or remote Gateway setup).
+
+## Related guides
+
+- CLI onboarding hub: [Onboarding Wizard (CLI)](/start/wizard)
+- CLI onboarding reference: [CLI Onboarding Reference](/start/wizard-cli-reference)
+- CLI automation: [CLI Automation](/start/wizard-cli-automation)
+- macOS onboarding: [Onboarding (macOS App)](/start/onboarding)
+
+## Examples
+
+```bash
+Synurex onboard
+Synurex onboard --flow quickstart
+Synurex onboard --flow manual
+Synurex onboard --mode remote --remote-url ws://gateway-host:18789
+```
+
+Flow notes:
+
+- `quickstart`: minimal prompts, auto-generates a gateway token.
+- `manual`: full prompts for port/bind/auth (alias of `advanced`).
+- Fastest first chat: `Synurex dashboard` (Control UI, no channel setup).
+
+## Common follow-up commands
+
+```bash
+Synurex configure
+Synurex agents add <name>
+```
+
+<Note>
+`--json` does not imply non-interactive mode. Use `--non-interactive` for scripts.
+</Note>

package/docs/cli/pairing.md

@@ -0,0 +1,21 @@
+---
+summary: "CLI reference for `Synurex pairing` (approve/list pairing requests)"
+read_when:
+  - You’re using pairing-mode DMs and need to approve senders
+title: "pairing"
+---
+
+# `Synurex pairing`
+
+Approve or inspect DM pairing requests (for channels that support pairing).
+
+Related:
+
+- Pairing flow: [Pairing](/channels/pairing)
+
+## Commands
+
+```bash
+Synurex pairing list whatsapp
+Synurex pairing approve whatsapp <code> --notify
+```

package/docs/cli/plugins.md

@@ -0,0 +1,62 @@
+---
+summary: "CLI reference for `Synurex plugins` (list, install, enable/disable, doctor)"
+read_when:
+  - You want to install or manage in-process Gateway plugins
+  - You want to debug plugin load failures
+title: "plugins"
+---
+
+# `Synurex 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
+Synurex plugins list
+Synurex plugins info <id>
+Synurex plugins enable <id>
+Synurex plugins disable <id>
+Synurex plugins doctor
+Synurex plugins update <id>
+Synurex plugins update --all
+```
+
+Bundled plugins ship with Synurex but start disabled. Use `plugins enable` to
+activate them.
+
+All plugins must ship a `Synurex.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
+Synurex plugins install <path-or-spec>
+```
+
+Security note: treat plugin installs like running code. Prefer pinned versions.
+
+Supported archives: `.zip`, `.tgz`, `.tar.gz`, `.tar`.
+
+Use `--link` to avoid copying a local directory (adds to `plugins.load.paths`):
+
+```bash
+Synurex plugins install -l ./my-plugin
+```
+
+### Update
+
+```bash
+Synurex plugins update <id>
+Synurex plugins update --all
+Synurex plugins update <id> --dry-run
+```
+
+Updates only apply to plugins installed from npm (tracked in `plugins.installs`).