@nordbyte/nordrelay 0.8.0 → 0.8.2

package/README.md

@@ -1,1274 +1,158 @@
 # NordRelay
+![NordRelay Banner](docs/assets/nordrelay.png) [![Latest release](https://img.shields.io/github/v/release/nordbyte/nordrelay?style=flat-square)](https://github.com/nordbyte/nordrelay/releases/latest) [![CI](https://img.shields.io/github/actions/workflow/status/nordbyte/nordrelay/ci.yml?branch=main&style=flat-square)](https://github.com/nordbyte/nordrelay/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-ffd60a?style=flat-square)](LICENSE) [![npm](https://img.shields.io/npm/v/@nordbyte/nordrelay?logo=npm&logoColor=white&style=flat-square)](https://www.npmjs.com/package/@nordbyte/nordrelay) [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-339933?logo=node.js&logoColor=white&style=flat-square)](package.json) [![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178c6?logo=typescript&logoColor=white&style=flat-square)](tsconfig.json)
 
-NordRelay is a remote control plane for coding agents across messaging channels and paired NordRelay instances. The current implementation connects Codex, Pi, Hermes, OpenClaw, and Claude Code coding-agent sessions to Telegram, Discord, Slack, the WebUI, and trusted peer nodes, keeps independent sessions per chat, thread, forum topic, DM, or remote target, streams replies and tool activity back to the active channel, supports files, photos, voice input, model controls, session browsing, retry/abort, CLI handback, and scoped multi-host control.
+NordRelay is a secure remote control plane for coding agents. It connects Codex, Pi, Hermes, OpenClaw, and Claude Code sessions to Telegram, Discord, Slack, the WebUI, and trusted peer nodes, with streaming replies, file/photo/voice input, queues, artifacts, user permissions, and multi-host control.
 
-The repo is both a local Codex marketplace and a standalone Node app. The plugin lives in `plugins/nordrelay/`; the full bot runtime lives in `src/` and uses `@openai/codex-sdk` for Codex, Pi RPC mode for Pi, the Hermes API Server for Hermes, the OpenClaw Gateway WebSocket RPC surface for OpenClaw, and the Claude Agent SDK for Claude Code.
+Use the README for the first install and quick start. Full feature, command, configuration, deployment, and architecture details live in [docs/](docs/).
 
-## Features
+## Quick Start
 
-Session control:
+Requirements:
 
-- Independent coding-agent sessions per Telegram private chat, group chat, forum topic, Discord DM/channel/thread, Slack DM/channel/thread, WebUI, and peer target.
-- `/agent` switches a chat context between enabled agents such as Codex, Pi, Hermes, OpenClaw, and Claude Code.
-- Persistent channel context metadata in the active workspace under `.nordrelay/contexts.json`.
-- `/new` starts a fresh thread, with workspace selection when known workspaces are available.
-- `/session` shows thread id, workspace, launch profile, launch behavior, model, reasoning, fast mode, context usage, token totals, and subscription limit remaining percentages.
-- `/sessions` opens a paginated browser for recent sessions from the selected agent.
-- `/sessions <query>` filters recent sessions by id, title, workspace, model, or first message.
-- `/sync` manually refreshes the active chat session from local CLI state when the selected agent supports state watching.
-- `/pin`, `/unpin`, and `/pinned` keep important threads at the top of Telegram session browsing.
-- `/switch <session-id>` switches directly to an existing session.
-- `/attach <session-id>` binds an existing agent session to the current chat or topic.
-- Existing thread metadata is imported on switch/attach, including model, reasoning effort, sandbox mode, and approval policy.
-- Codex session usage is read from local rollout JSONL files, including context-used percent, total input/output tokens, 5h limit remaining, and weekly limit remaining.
-- `/handback` returns a ready-to-run CLI command for continuing in the native agent CLI.
-- `/retry` resends the last prompt for the current chat context.
-- `/queue`, inline run/top/up/down/cancel buttons, `/cancel <queue-id>`, and `/clearqueue` manage queued prompts for a busy chat context.
-- `/queue later <minutes> <prompt>` schedules a prompt for later execution, and `/queue inspect <queue-id>` shows full queue metadata.
-- `/abort`, `/stop`, and the inline Abort button cancel the active agent turn.
-- Busy prompts are queued per chat context instead of being dropped.
-- If the attached thread is currently active in the local agent CLI, chat prompts are queued until that CLI task finishes.
-- Active Codex, Pi, Hermes, OpenClaw, and Claude Code CLI/API turns are mirrored into Telegram, Discord, and Slack with configurable `off`, `status`, `final`, or `full` modes.
-- `/mirror` controls CLI mirroring per chat context.
-- Queues survive connector restarts and are resumed automatically when the external CLI turn becomes idle.
-- `/notify` controls completion/status notifications and quiet hours per chat context.
-- `/workspaces` lists allowed workspaces and shows workspace guardrail warnings.
-- `/status`, `/health`, and `/version` report connector runtime health from chat adapters.
-- `/tasks` and `/progress` show the current turn status, queue length, active tool, elapsed time, and last error.
-- `/activity` shows a compact timeline of recent rollout events for the active thread, with filters and export.
-- `/diagnostics` reports redacted runtime, config, user/group authorization, channel rate-limit, mirror, voice, session, queue, and progress details.
-- `/support` exports a redacted diagnostics ZIP with config, health, versions, agent paths, recent logs, audit events, update jobs, state backend, and OS/Node/npm info.
-- `/lock`, `/unlock`, and `/locks` provide a team write-lock for shared sessions so one user can operate while others watch.
-- `/audit` shows recent prompt, queue, lock, command, authentication, permission-denied, user, group, Telegram-link, Telegram-chat, Discord-link, Discord-channel, Slack-link, Slack-channel, and web-session audit events for admins.
+- Node.js 22 or newer.
+- At least one supported coding agent installed and authenticated, for example Codex CLI.
+- A Telegram, Discord, or Slack bot/app token if you want chat access.
 
-Adapter architecture:
-
-- Telegram supports text, typing, streaming edits, inline buttons, files, photos, voice, forum topics, and polling/webhook transport.
-- Discord supports text, typing, streaming edits, buttons, files, photos, voice/audio transcription, guild channels, threads, DMs, message commands, and slash commands.
-- Slack supports text, typing/status, streaming edits, Block Kit buttons, files, images, audio transcription, channels, DMs, threads, Socket Mode, and HTTP Events mode.
-- Slack startup and `/diagnostics` include readiness checks for token/transport configuration, registered channels, Slack API auth probes, channel visibility probes, file-upload readiness notes, and rate-limit counters.
-- `/channels` shows available and planned messaging adapters for Telegram, Discord, Slack, WhatsApp, and Matrix.
-- Codex, Pi, Hermes, OpenClaw, and Claude Code are implemented as agent adapters.
-- `/agents` shows available/planned agent adapters and whether Codex, Pi, Hermes, OpenClaw, and Claude Code are enabled.
-- Agent and chat adapters expose a shared conformance matrix so command coverage and feature support can be tested and surfaced consistently.
-- Shared command-action renderers and a channel runtime contract keep inbound commands, outbound messages, typing, files, inline actions, and streaming-ready delivery separate from channel-specific API calls.
-
-Peer federation:
-
-- Optional NordRelay-to-NordRelay pairing lets one instance operate agents on trusted Ubuntu, macOS, Windows, LAN, or remote hosts.
-- Peer serving is disabled by default and uses a dedicated API port separate from the dashboard.
-- Pairing requires an explicit one-time invitation code, Ed25519 node identity verification, a per-peer shared secret, request HMAC signatures, timestamp/nonce replay protection, and TLS fingerprint pinning.
-- Peer scopes restrict which remote WebUI/API actions are allowed, including read, prompt, queue, file, diagnostic, log, and session permissions.
-- Peer records can also restrict allowed agent ids, allowed workspace roots, and per-peer workspace aliases such as `app=/srv/app`.
-- The WebUI has a Peers page plus a local/remote target selector; dashboard pages, SSE streaming, queue actions, artifact downloads, health checks, and the global session browser proxy through the selected peer when allowed.
-- Telegram, Discord, and Slack expose `/peers` and `/target` so a linked user can choose whether prompts run locally or on a paired NordRelay instance.
-- Remote prompts stream text, tool status, turn completion, and errors back to the originating Telegram, Discord, or Slack context.
-
-Codex runtime:
-
-- Uses `@openai/codex-sdk` to start, resume, and stream Codex threads.
-- Prefers the host `codex` executable on `PATH`, so Codex CLI updates are picked up automatically; the SDK-bundled CLI is used only as fallback.
-- Supports model selection through `/model`, using Codex model cache when available and fallback models otherwise.
-- Supports reasoning effort selection through `/reasoning` and the backward-compatible `/effort` alias: `minimal`, `low`, `medium`, `high`, `xhigh`.
-- Supports launch profiles through `/launch_profiles` and `/launch`.
-- Built-in launch profiles include Default, Read Only, Review, and optional Full Access.
-- Custom launch profiles can be configured with `CODEX_LAUNCH_PROFILES_JSON`.
-- Unsafe `danger-full-access` profiles require `ENABLE_UNSAFE_LAUNCH_PROFILES=true` and channel confirmation.
-- Review or unsafe launch profiles require an inline channel approval before each prompt is executed.
-- Fast mode can be toggled with `/fast` and mirrors Codex's `fast_default_opt_out` setting from `~/.codex/config.toml`.
-- Active chat sessions periodically sync model, reasoning, workspace, launch metadata, and fast-mode defaults from local agent state where supported.
-- Active local Codex CLI tasks are detected from rollout JSONL files so chat adapters do not race the CLI on the same thread.
-- `/diagnostics` includes rollout path, activity status, stale/idle reason, line count, and last update time.
-- Optional per-turn token usage footer with `SHOW_TURN_TOKEN_USAGE=true`.
-
-Pi runtime:
-
-- Pi support is opt-in with `NORDRELAY_PI_ENABLED=true`.
-- The default chat agent is selected with `NORDRELAY_DEFAULT_AGENT=codex`, `pi`, `hermes`, `openclaw`, or `claude-code`.
-- Pi sessions are driven through official `pi --mode rpc` JSONL commands and events.
-- Existing Pi sessions are discovered from `~/.pi/agent/sessions/` or `PI_SESSION_DIR`.
-- `/sessions`, `/switch`, `/attach`, `/new`, `/session`, `/handback`, `/model`, `/reasoning`, `/abort`, `/stop`, `/retry`, `/queue`, files, photos, and voice input work for Pi contexts.
-- Pi model selection uses `pi --list-models` and sends `set_model` through RPC for active sessions.
-- Pi thinking levels use `/reasoning` and support `off`, `minimal`, `low`, `medium`, `high`, and `xhigh`.
-- Pi token and context stats are read through `get_session_stats` when an RPC session is active.
-- Pi launch profiles expose CLI safety modes such as default, read-only tools, no tools, offline, and safe offline.
-- Pi external CLI activity is detected from Pi session JSONL files so chat/WebUI prompts queue while the same Pi session is busy.
-- Pi CLI turns can be mirrored into chat adapters and the WebUI with status, tool activity, final answers, activity timelines, diagnostics, and generated artifact discovery.
-- Pi provider auth checks report the environment variables expected for the selected provider.
-- Codex-only subscription limit percentages remain Codex-specific; Pi reports token/context stats when available.
-
-Hermes runtime:
-
-- Hermes support is opt-in with `NORDRELAY_HERMES_ENABLED=true`.
-- The default chat agent can be set with `NORDRELAY_DEFAULT_AGENT=hermes`.
-- Hermes turns are executed through the Hermes API Server `/v1/runs` endpoint and streamed through `/v1/runs/{run_id}/events`.
-- `/abort` and `/stop` use the Hermes run stop endpoint when a NordRelay-started Hermes run is active.
-- Existing Hermes sessions are discovered from `~/.hermes/state.db`, or from `HERMES_STATE_DB_PATH` when configured.
-- `/sessions`, `/switch`, `/attach`, `/new`, `/session`, `/handback`, `/model`, `/reasoning`, `/abort`, `/stop`, `/retry`, `/queue`, files, photos, and voice input work for Hermes contexts.
-- Hermes model selection uses `/v1/models` when the API Server is reachable and falls back to the selected/default model.
-- Hermes reasoning uses `/reasoning` and supports `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`.
-- Hermes launch profiles include `default`, `safe`, `readonly`, and `yolo`; profiles map to run instructions and Hermes approval responses.
-- Hermes external activity is detected from `state.db`, so chat/WebUI prompts queue while the same Hermes session has an unfinished CLI turn.
-- Hermes CLI/API turns can be mirrored into chat adapters and the WebUI with status, tool activity, final answers, activity timelines, diagnostics, and generated artifact discovery.
-- `/auth` checks that the Hermes API Server is reachable and that `HERMES_API_KEY` is usable when configured.
-
-OpenClaw runtime:
-
-- OpenClaw support is opt-in with `NORDRELAY_OPENCLAW_ENABLED=true`.
-- The default chat agent can be set with `NORDRELAY_DEFAULT_AGENT=openclaw`.
-- OpenClaw turns are executed through the OpenClaw Gateway WebSocket RPC endpoint configured by `OPENCLAW_GATEWAY_URL`.
-- `/abort` and `/stop` call the OpenClaw Gateway cancel method when a NordRelay-started OpenClaw run is active.
-- Existing OpenClaw sessions are discovered from `openclaw sessions --all-agents --json`, or from the state directory configured with `OPENCLAW_HOME` or `OPENCLAW_STATE_DIR`.
-- `/sessions`, `/switch`, `/attach`, `/new`, `/session`, `/handback`, `/model`, `/reasoning`, `/abort`, `/stop`, `/retry`, `/queue`, files, photos, and voice input work for OpenClaw contexts.
-- OpenClaw model selection uses the Gateway `models.list` method when reachable and falls back to `openclaw models list --json`.
-- OpenClaw thinking uses `/reasoning` and supports `off`, `minimal`, `low`, `medium`, `high`, and `xhigh`.
-- OpenClaw launch profiles include `default`, `safe`, `readonly`, `local`, and `deliver`; profiles map to Gateway run flags and additional instructions.
-- OpenClaw external activity is detected from OpenClaw session state, so chat/WebUI prompts queue while the same OpenClaw session has an unfinished CLI turn.
-- OpenClaw Gateway turns can be mirrored into chat adapters and the WebUI with status, tool activity, final answers, activity timelines, diagnostics, and generated artifact discovery.
-- `/auth` checks that the OpenClaw Gateway is reachable and that `OPENCLAW_GATEWAY_TOKEN` or `OPENCLAW_GATEWAY_PASSWORD` is usable when configured.
-
-Claude Code runtime:
-
-- Claude Code support is opt-in with `NORDRELAY_CLAUDE_CODE_ENABLED=true`.
-- The default chat agent can be set with `NORDRELAY_DEFAULT_AGENT=claude-code`.
-- Claude Code turns are executed through `@anthropic-ai/claude-agent-sdk`, using the host `claude` executable when available and the SDK bundled runtime otherwise.
-- Existing Claude Code sessions are discovered from `~/.claude/projects/`, or from `CLAUDE_CONFIG_DIR/projects` when configured.
-- `/sessions`, `/switch`, `/attach`, `/new`, `/session`, `/handback`, `/model`, `/reasoning`, `/abort`, `/stop`, `/retry`, `/queue`, files, photos, and voice input work for Claude Code contexts.
-- Claude Code model selection exposes common aliases and model ids; explicit values from existing sessions are preserved.
-- Claude Code effort uses `/reasoning` and supports `off`, `low`, `medium`, `high`, and `xhigh`.
-- Claude Code launch profiles include `default`, `accept-edits`, `plan`, `readonly`, `no-tools`, and optional `bypass-permissions`.
-- Claude Code external activity is detected from transcript JSONL files, so chat/WebUI prompts queue while the same Claude Code session has an unfinished CLI turn.
-- Claude Code SDK turns can be mirrored into chat adapters and the WebUI with status, tool activity, final answers, activity timelines, diagnostics, and generated artifact discovery.
-- `/auth` checks the host Claude Code CLI auth state when `claude auth status` is available.
-
-Telegram input:
-
-- Plain text messages become prompts for the selected agent.
-- Voice and audio messages are transcribed before being sent to the selected agent.
-- Voice transcription uses local `faster-whisper` on Linux, local `parakeet-coreml` on macOS Apple Silicon, or OpenAI Whisper when `OPENAI_API_KEY` is set.
-- `/voice` can select backend preference, language, and transcribe-only mode.
-- Photo messages are passed to the selected agent as local image input when supported.
-- Document messages are downloaded, sanitized, size-checked, and staged under `.nordrelay/inbox/<turn-id>/`.
-- Telegram media groups and albums are combined into one agent turn with all photos and documents staged together.
-- Uploaded documents include prompt instructions telling the selected agent where files were staged.
-- Staged document and photo prompts are persisted so `/retry` and queued execution can replay them after a restart.
-- Telegram forum topics are treated as separate work contexts.
-
-Telegram output:
-
-- Assistant replies stream back to Telegram with debounced message edits.
-- Telegram `typing` status is sent while the selected agent is working.
-- Markdown is converted to Telegram HTML where possible, with fallback to plain text.
-- Long replies are split to respect Telegram message limits.
-- Tool activity can be displayed as summary, full output, errors only, or hidden with `TOOL_VERBOSITY`.
-- Command execution, web search, file changes, MCP tool calls, error items, and todo-list updates are surfaced.
-- Todo-list updates are rendered as a live plan/status message.
-- Generated artifacts from `.nordrelay/turns/<turn-id>/out/` are retained for manual retrieval with `/artifacts`.
-- Workspace files detected after mirrored Codex, Pi, Hermes, OpenClaw, or Claude Code CLI/API turns are indexed as `/artifacts` entries, even when automatic artifact delivery is disabled.
-- Automatic artifact summaries and file uploads are disabled by default; set `TELEGRAM_AUTO_SEND_ARTIFACTS=true` to send them after turns.
-- Workspace artifact detection sorts by modification time and supports configurable ignored directories and globs.
-- Image artifacts are sent with Telegram previews; large multi-file outputs are bundled into one ZIP when possible.
-- `/artifacts` lists recent generated files and can resend the latest or a specific artifact turn.
-- `/artifacts` includes inline actions to resend, ZIP, or delete artifact turns.
-- `/artifacts images`, `/artifacts docs`, `/artifacts search <text>`, and `/artifacts delete <turn-id>` filter, find, and clean up artifacts from Telegram.
-- Old artifact and inbox turn directories are pruned automatically with configurable retention.
-- Optional Telegram message reactions can acknowledge work start and completion with `ENABLE_TELEGRAM_REACTIONS=true`.
-
-Discord input and output:
-
-- Enable Discord with `DISCORD_ENABLED=true` and `DISCORD_BOT_TOKEN`. If a requested chat adapter is missing its token, NordRelay disables that adapter and keeps running as long as another chat adapter is usable.
-- Set `DISCORD_CLIENT_ID` to let NordRelay register slash commands automatically.
-- `DISCORD_COMMAND_MODE=both` supports slash commands and `/command` text messages. Set it to `slash` if the bot should not read message commands.
-- `DISCORD_MESSAGE_CONTENT_ENABLED=true` lets regular Discord messages become prompts. The matching privileged intent must also be enabled in the Discord Developer Portal.
-- Discord DMs, guild channels, and threads get independent NordRelay contexts.
-- Discord attachments are staged like Telegram uploads; images are passed as image inputs and audio files are transcribed before prompting.
-- Discord buttons cover session picks, model/reasoning/launch picks, queue actions, artifact actions, update jobs, and abort where Discord component limits allow.
-- Discord slash commands mirror the Telegram command surface where Discord supports it: `/agent`, `/auth`, `/login`, `/logout`, `/session`, `/sessions`, `/new`, `/switch`, `/attach`, `/handback`, `/workspaces`, `/pin`, `/unpin`, `/pinned`, `/model`, `/reasoning`, `/fast`, `/launch`, `/launch_profiles`, `/queue`, `/stop`, `/retry`, `/sync`, `/progress`, `/activity`, `/audit`, `/artifacts`, `/logs`, `/version`, `/diagnostics`, `/restart`, `/update`, `/lock`, `/unlock`, `/mirror`, `/notify`, `/voice`, `/link`, `/whoami`, and `/register_channel`.
-
-Slack input and output:
-
-- Enable Slack with `SLACK_ENABLED=true`, `SLACK_BOT_TOKEN`, and `SLACK_APP_TOKEN` for Socket Mode. If Socket Mode is disabled, set `SLACK_SIGNING_SECRET` and expose the Slack HTTP receiver.
-- `SLACK_MESSAGE_CONTENT_ENABLED=true` lets regular Slack messages become prompts. Keep it disabled if you only want slash-command control.
-- Slack DMs, channels, and message threads get independent NordRelay contexts.
-- Slack files are staged like Telegram/Discord uploads; images are passed as image inputs and audio files are transcribed before prompting.
-- Slack Block Kit buttons cover session picks, model/reasoning/launch picks, queue actions, artifact actions, update jobs, and abort where Slack component limits allow.
-- Slack slash/text commands mirror the shared command surface where Slack supports it: `/agent`, `/auth`, `/login`, `/logout`, `/session`, `/sessions`, `/new`, `/switch`, `/attach`, `/handback`, `/workspaces`, `/pin`, `/unpin`, `/pinned`, `/model`, `/reasoning`, `/fast`, `/launch`, `/launch_profiles`, `/queue`, `/stop`, `/retry`, `/sync`, `/progress`, `/activity`, `/audit`, `/artifacts`, `/logs`, `/version`, `/diagnostics`, `/restart`, `/update`, `/lock`, `/unlock`, `/mirror`, `/notify`, `/voice`, `/link`, `/whoami`, and `/register_channel`.
-
-Authentication and safety:
-
-- WebUI login is required for every dashboard page, API route, SSE stream, artifact download, and health endpoint.
-- Access is managed through NordRelay users, groups, permissions, web sessions, linked Telegram identities, linked Discord identities, and linked Slack identities.
-- Built-in groups are `Admin`, `User`, and `Read Only`; custom groups can be created in the WebUI and can restrict allowed agents, workspace roots, Telegram chats, Discord channels, and Slack channels.
-- The last active admin cannot be disabled or demoted, and web sessions are revoked when passwords or group memberships change.
-- Admins can review and revoke active WebUI sessions from the Users page.
-- Telegram private chats require a linked active NordRelay user.
-- Telegram group and forum chats must be registered before use; admins can run `/register_chat` in the chat or enable chats in the WebUI.
-- Discord DMs require a linked active NordRelay user.
-- Discord guild channels and threads must be registered before use; admins can run `/register_channel` in the channel or enable channels in the WebUI.
-- Slack DMs require a linked active NordRelay user.
-- Slack channels and threads must be registered before use; admins can run `/register_channel` in the channel or enable channels in the WebUI.
-- `/whoami` shows the linked NordRelay account and groups.
-- `/link <code>` links a Telegram account to a NordRelay user after a link code is created in the WebUI or with `nordrelay user link-code`.
-- `/link <code>` also links a Discord or Slack account when the code was created for that channel.
-- WebUI login and chat-account link attempts are rate-limited to reduce brute-force risk.
-- User, group, Telegram-link, Telegram-chat, Discord-link, Discord-channel, Slack-link, Slack-channel, web-session, login, and permission-denied events are written to the audit log.
-- `/auth` reports Codex authentication, Pi provider environment health, Hermes API Server reachability, OpenClaw Gateway reachability, or Claude Code CLI auth for the selected agent.
-- `/login` starts Telegram-managed CLI auth for Codex, Hermes, or Claude Code when enabled.
-- `/logout` signs out of CLI auth for Codex, Hermes, or Claude Code; Codex logout is disabled while `CODEX_API_KEY` is in use.
-- `CODEX_API_KEY` can be used for host-side Codex authentication.
-- Friendly error messages are returned for auth, network, model, rate-limit, timeout, and context-length failures.
-- Outgoing Telegram messages and logs redact common token/API-key patterns, with optional custom redaction patterns.
-- Workspace allow/warn roots can prevent accidental operation in the wrong project directory.
-
-Operations:
-
-- Plugin command/skill starts, stops, restarts, and inspects the connector process.
-- Manual process commands support `start`, `stop`, `restart`, `status`, `update`, and `foreground`.
-- Telegram admin commands support `/logs`, `/diagnostics`, `/support`, `/restart`, and `/update` for NordRelay and agent CLIs.
-- `nordrelay peer identity`, `list`, `invite`, `add`, `test`, and `revoke` manage secure peer federation from the CLI.
-- `nordrelay update`, `/update`, and the WebUI update button detect the install type: npm installs update with `npm install -g @nordbyte/nordrelay@latest`; source checkouts pull `origin/main`, install dependencies, run check, tests, and build, then restart if the connector is running.
-- `/update agents`, `/update <agent>`, `/update install <agent>`, `/update jobs`, `/update log <id>`, `/update cancel <id>`, and `/update input <id> <text>` manage Codex, Pi, Hermes, OpenClaw, and Claude Code updater or installer jobs from Telegram.
-- `/logs` renders redacted connector, NordRelay update, and agent update logs with local-time timestamps, levels, file path, last-modified time, and highlighted warnings/errors.
-- Logs can be emitted as timestamped plain text or JSON records with `CONNECTOR_LOG_FORMAT`.
-- Telegram sends/edits/documents are routed through a rate-limit queue that honors Telegram retry-after responses.
-- Mirror, notification, quiet-hour, and automatic artifact-delivery defaults are configured through channel-neutral `NORDRELAY_*` settings, with Telegram, Discord, and Slack override keys when a channel should differ.
-- The WebUI Tasks page includes a unified Jobs view for active WebUI turns, external CLI turns, queued prompts, agent update/install jobs, self-updates, and diagnostics bundle exports, with log, cancel, and retry actions where supported.
-- Unified Jobs are persisted across restarts and retain recent prompt, queue, update, connector-update, and support-bundle history for WebUI inspection.
-- The WebUI Metrics page reports queue state, active/completed/failed turns, job counts, average prompt duration, and Telegram/Discord/Slack rate-limit counters.
-- Expensive dashboard views such as version checks, adapter health, and diagnostics use a short stale-while-refresh server cache so the UI can render recent data while fresh checks run in the background.
-- Context metadata, queues, and preferences are written atomically with backup recovery.
-- Context metadata, queues, preferences, audit events, and locks can use JSON files or the optional SQLite state backend with `NORDRELAY_STATE_BACKEND=sqlite`.
-- Runtime config, state, and logs are written under `~/.nordrelay/`.
-- `nordrelay init` creates a private runtime config, `nordrelay doctor` validates host prerequisites, and `nordrelay web` starts the connector plus a full local WebUI dashboard.
-- On first WebUI startup without an admin account, NordRelay shows a setup wizard for creating the first admin; remote setup requires the one-time token printed in the server console.
-- The WebUI has responsive header/sidebar/footer navigation, live chat streaming, session controls, queue/artifact/log/diagnostic views, and settings management.
-- The WebUI supports light and dark themes, tabbed settings groups, paginated session browsing, and chat uploads for images, documents, and audio transcription.
-- The WebUI exposes REST and SSE endpoints for chat streaming, sessions, settings, queue, artifacts, logs, health, diagnostics, peers, adapter conformance, and redacted diagnostics bundle export.
-- The dashboard can bind to `127.0.0.1` or `0.0.0.0`; user login and session cookies are mandatory in both modes.
-- Telegram can run with long polling or an HTTP webhook via `TELEGRAM_TRANSPORT=webhook`.
-- Version freshness checks are cached with `NORDRELAY_VERSION_CACHE_TTL_MS`, and installed agent CLI version checks are cached with `NORDRELAY_CLI_VERSION_CACHE_TTL_MS`, to keep `/version` and adapter health responsive.
-- CI runs on Ubuntu, Windows, and macOS with typecheck, Vitest, Playwright WebUI browser tests, package dry run, npm audit, and a separate secret-scan workflow.
-- `npm run dev`, `npm run build`, `npm run check`, `npm test`, `npm run test:e2e`, `npm start`, `npm stop`, and `npm run status` are available.
-- Dockerfile and `docker-compose.yml` are included for containerized operation.
-- A `launchd/start.sh` helper is included for host-managed startup.
-
-## First Run Setup
-
-Recommended npm setup:
+Install NordRelay globally:
 
 ```bash
 npm install -g @nordbyte/nordrelay
 nordrelay init
-nordrelay user list
 nordrelay doctor
 nordrelay start
 ```
 
-npm is the fastest install path and is the recommended default for normal use. `nordrelay init` writes the private runtime config to `~/.nordrelay/nordrelay.env`.
-If you start `nordrelay web` before creating an admin, the dashboard opens a first-run setup wizard. Remote setup requires the one-time setup token printed in the NordRelay console.
-
-Non-interactive setup is also supported:
+Open the dashboard:
 
 ```bash
-nordrelay init \
-  --token 123456789:replace-me \
-  --enable-discord \
-  --discord-token "discord-bot-token" \
-  --discord-client-id "discord-client-id" \
-  --admin-email you@example.com \
-  --admin-name "Your Name" \
-  --admin-password "replace-with-a-long-password" \
-  --telegram-user-id 123456789
+nordrelay web
 ```
 
-`--telegram-user-id` is optional, but linking the first admin during setup is the fastest way to use Telegram immediately.
-Use `--discord-user-id <id>` with `nordrelay user create-admin` or `nordrelay user link-discord` to link Discord directly.
+The dashboard is available at the URL printed by the command, usually:
 
-Source checkout setup:
-
-Install dependencies and build the runtime:
-
-```bash
-npm install
-npm run build
-mkdir -p ~/.nordrelay
-cp .env.example ~/.nordrelay/nordrelay.env
-chmod 600 ~/.nordrelay/nordrelay.env
+```text
+http://127.0.0.1:31878/
 ```
 
-Create the Telegram bot:
+On first WebUI startup, create the first admin user. After that, every dashboard page and chat adapter action is controlled by NordRelay users, groups, linked Telegram/Discord/Slack accounts, and registered channels.
 
-1. Open Telegram and talk to `@BotFather`.
-2. Run `/newbot`.
-3. Choose a display name and bot username.
-4. Copy the bot token into `TELEGRAM_BOT_TOKEN` in `~/.nordrelay/nordrelay.env`.
-5. Create the first admin user with `nordrelay init` or `nordrelay user create-admin`.
-6. Link Telegram from the WebUI, with `nordrelay user link-telegram`, or by creating a link code and sending `/link <code>` to the bot.
+## Minimal Setup
 
-Create the Discord bot:
+The recommended setup path is interactive:
 
-1. Open the Discord Developer Portal and create an application.
-2. Add a bot user and copy the bot token into `DISCORD_BOT_TOKEN`.
-3. Copy the application client ID into `DISCORD_CLIENT_ID`.
-4. Enable the Message Content intent if you want regular Discord messages to become prompts.
-5. Invite the bot with application-command, message-send, message-read, attachment, and thread permissions.
-6. Link Discord from the WebUI, with `nordrelay user link-discord`, or by creating a Discord link code and sending `/link <code>` to the bot.
-7. In guild channels, run `/register_channel` once from an admin-linked Discord account.
+```bash
+nordrelay init
+nordrelay user list
+nordrelay doctor
+nordrelay start
+```
 
-Create the Slack app:
+`nordrelay init` writes private runtime config to:
 
-1. Open Slack API Apps and create a new app for your workspace.
-2. Add a bot user and copy the bot token into `SLACK_BOT_TOKEN`.
-3. Enable Socket Mode and create an app-level token with `connections:write`; copy it into `SLACK_APP_TOKEN`.
-4. Add bot scopes for messages, files, channels, groups, IMs, MPIMs, commands, and chat write access.
-5. Create the slash command configured in `SLACK_COMMAND` (default `/nordrelay`) and install the app to your workspace.
-6. Link Slack from the WebUI, with `nordrelay user link-slack`, or by creating a Slack link code and sending `/link <code>` to the app.
-7. In Slack channels, run `/register_channel` once from an admin-linked Slack account.
+```text
+~/.nordrelay/nordrelay.env
+```
 
-Minimal private-bot `~/.nordrelay/nordrelay.env`:
+A minimal Telegram + Codex configuration looks like this:
 
 ```dotenv
+TELEGRAM_ENABLED=true
 TELEGRAM_BOT_TOKEN=123456789:replace-me
 DISCORD_ENABLED=false
-DISCORD_BOT_TOKEN=
-DISCORD_CLIENT_ID=
 SLACK_ENABLED=false
-SLACK_BOT_TOKEN=
-SLACK_APP_TOKEN=
 NORDRELAY_CODEX_ENABLED=true
-NORDRELAY_PI_ENABLED=false
-NORDRELAY_HERMES_ENABLED=false
-NORDRELAY_OPENCLAW_ENABLED=false
-NORDRELAY_CLAUDE_CODE_ENABLED=false
 NORDRELAY_DEFAULT_AGENT=codex
 CODEX_SANDBOX_MODE=workspace-write
 CODEX_APPROVAL_POLICY=never
 ```
 
-User and chat access management:
-
-- `nordrelay init` creates the first admin user and writes `~/.nordrelay/users.json`.
-- `nordrelay user create-admin --email you@example.com --name "Your Name"` creates another admin.
-- `nordrelay user create --email dev@example.com --name "Dev" --group user` creates a normal user.
-- `nordrelay user link-telegram --email you@example.com --telegram-user-id 123456789` links a Telegram account directly.
-- `nordrelay user link-discord --email you@example.com --discord-user-id 123456789012345678` links a Discord account directly.
-- `nordrelay user link-slack --email you@example.com --slack-user-id U123 --slack-team-id T123` links a Slack account directly.
-- `nordrelay user link-code --email you@example.com` creates a short-lived Telegram code that the user sends as `/link <code>` to the Telegram bot.
-- `nordrelay user discord-link-code --email you@example.com` creates a short-lived Discord code that the user sends as `/link <code>` to the Discord bot.
-- `nordrelay user slack-link-code --email you@example.com` creates a short-lived Slack code that the user sends as `/link <code>` to the Slack app.
-- Telegram group chats are disabled until an admin enables them from the WebUI or runs `/register_chat` inside the group.
-- Discord guild channels are disabled until an admin enables them from the WebUI or runs `/register_channel` inside the channel.
-- Slack channels are disabled until an admin enables them from the WebUI or runs `/register_channel` inside the channel.
-
-Peer setup:
-
-1. On each host that should accept peer connections, set `NORDRELAY_PEER_ENABLED=true` in `~/.nordrelay/nordrelay.env`.
-2. Keep `NORDRELAY_PEER_TLS_ENABLED=true` and `NORDRELAY_PEER_REQUIRE_TLS=true` for LAN or internet use.
-3. Use `NORDRELAY_PEER_HOST=127.0.0.1` for local-only testing, a LAN/interface IP for trusted local networks, or keep the peer API behind a TLS reverse proxy/VPN for internet access.
-4. Set `NORDRELAY_PEER_PUBLIC_URL=https://host.example:31979` when other hosts cannot reach the bind address directly.
-5. Restart NordRelay on the accepting host and create an invitation:
-
-```bash
-nordrelay peer invite --name workstation --scopes inspect,sessions.read,sessions.write,prompt.send,prompt.abort,queue.read,queue.write,files.read,files.write,diagnostics.read,logs.read
-```
-
-6. On the controlling host, run the printed command:
-
-```bash
-nordrelay peer add https://workstation.example:31979 --code one-time-code
-```
-
-7. Confirm the connection:
-
-```bash
-nordrelay peer list
-nordrelay peer test <peer-id>
-```
-
-Use `--workspace-aliases app=/srv/app,demo=/home/me/demo` on invites when a controller should be able to start remote sessions with short workspace names. Use the WebUI Peers page for the same invite, pair, enable/disable, test, alias, global-session, and revoke workflow. Use `/peers` from Telegram, Discord, or Slack to inspect paired nodes and `/target <peer-id>` or `/target local` to choose where subsequent prompts run.
-
-Codex authentication:
-
-- Preferred local setup: run `codex login` on the host before starting the connector.
-- Remote setup: use `/auth` and `/login` in Telegram if `ENABLE_TELEGRAM_LOGIN=true`.
-- API-key setup: set `CODEX_API_KEY`; `/logout` is disabled while `CODEX_API_KEY` is in use.
-
-Pi setup:
-
-- Install Pi from https://pi.dev/ and confirm `pi --help` works on the host.
-- npm installs should use the current package name: `npm install -g @earendil-works/pi-coding-agent`.
-- Set `NORDRELAY_PI_ENABLED=true` in `~/.nordrelay/nordrelay.env`.
-- Keep `NORDRELAY_DEFAULT_AGENT=codex` to start chats in Codex, or set `NORDRELAY_DEFAULT_AGENT=pi` to start chats in Pi.
-- Optional: set `PI_SESSION_DIR` if your Pi sessions are not stored in `~/.pi/agent/sessions/`.
-- Optional: set `PI_DEFAULT_MODEL=openai-codex/gpt-5.5` and `PI_DEFAULT_THINKING=medium`.
-
-Hermes setup:
-
-- Install Hermes Agent and confirm `hermes --help` works on the host.
-- Start the Hermes API Server locally and confirm `GET http://127.0.0.1:8642/health` returns OK.
-- Set `NORDRELAY_HERMES_ENABLED=true` in `~/.nordrelay/nordrelay.env`.
-- Keep `NORDRELAY_DEFAULT_AGENT=codex` to start chats in Codex, or set `NORDRELAY_DEFAULT_AGENT=hermes` to start chats in Hermes.
-- Set `HERMES_API_BASE_URL` if the API Server is not listening on `http://127.0.0.1:8642`.
-- Set `HERMES_API_KEY` when the Hermes API Server is protected with `API_SERVER_KEY`.
-- Optional: use `/login` or run `hermes login --no-browser` on the host to refresh Hermes provider credentials.
-- Optional: set `HERMES_STATE_DB_PATH` if your Hermes session database is not stored at `~/.hermes/state.db`.
-- Optional: set `HERMES_DEFAULT_MODEL`, `HERMES_DEFAULT_REASONING`, and `HERMES_DEFAULT_PROFILE`.
-
-OpenClaw setup:
-
-- Install OpenClaw and confirm `openclaw --help` works on the host.
-- Start the OpenClaw Gateway and confirm the WebSocket endpoint is reachable.
-- Set `NORDRELAY_OPENCLAW_ENABLED=true` in `~/.nordrelay/nordrelay.env`.
-- Keep `NORDRELAY_DEFAULT_AGENT=codex` to start chats in Codex, or set `NORDRELAY_DEFAULT_AGENT=openclaw` to start chats in OpenClaw.
-- Set `OPENCLAW_GATEWAY_URL` if the Gateway is not listening on `ws://127.0.0.1:18789`.
-- Set `OPENCLAW_GATEWAY_TOKEN` or `OPENCLAW_GATEWAY_PASSWORD` when the Gateway requires shared-secret auth.
-- Optional: set `OPENCLAW_AGENT_ID` if you want a specific OpenClaw agent instead of `main`.
-- Optional: set `OPENCLAW_HOME` or `OPENCLAW_STATE_DIR` if your OpenClaw session state is stored outside `~/.openclaw`.
-- Optional: set `OPENCLAW_DEFAULT_MODEL`, `OPENCLAW_DEFAULT_THINKING`, and `OPENCLAW_DEFAULT_PROFILE`.
-
-Claude Code setup:
-
-- Install Claude Code and confirm `claude --help` works on the host, or use the SDK bundled runtime.
-- Use `/login` or run `claude auth login` on the host when your Claude Code installation requires local auth.
-- Set `NORDRELAY_CLAUDE_CODE_ENABLED=true` in `~/.nordrelay/nordrelay.env`.
-- Keep `NORDRELAY_DEFAULT_AGENT=codex` to start chats in Codex, or set `NORDRELAY_DEFAULT_AGENT=claude-code` to start chats in Claude Code.
-- Optional: set `CLAUDE_CODE_CLI_PATH` if `claude` is not on `PATH`.
-- Optional: set `CLAUDE_CONFIG_DIR` if your Claude Code sessions are not stored under `~/.claude`.
-- Optional: set `CLAUDE_CODE_DEFAULT_MODEL`, `CLAUDE_CODE_DEFAULT_EFFORT`, `CLAUDE_CODE_DEFAULT_PROFILE`, and `CLAUDE_CODE_MAX_TURNS`.
-
-Register the local Codex marketplace:
-
-```bash
-codex plugin marketplace add ~/projects/nordrelay
-```
-
-An example local marketplace entry is available at `docs/nordrelay-marketplace.example.json`. Keep personal `.agents/` marketplace files outside the public repo.
-
-## Running
-
-From Codex, ask:
-
-```text
-Starte Telegram Remote
-```
-
-Where Codex exposes namespaced plugin commands, this also works:
+For guided setup in the browser, open the WebUI, go to **Settings**, then use **Setup wizard** for Telegram, Discord, or Slack.
 
-```text
-/nordrelay:remote
-```
+## Common Commands
 
-The command is only a process-manager shortcut; Telegram contains the actual controls.
-
-Manual process commands:
+CLI:
 
 ```bash
-nordrelay init
-nordrelay doctor
-nordrelay start
 nordrelay status
-nordrelay update
-nordrelay restart
-nordrelay stop
-nordrelay foreground
-nordrelay web
-nordrelay peer list
-nordrelay peer invite
-nordrelay peer add https://peer.example:31979 --code one-time-code
-```
-
-Source checkout process commands:
-
-```bash
-node plugins/nordrelay/scripts/nordrelay.mjs start
-node plugins/nordrelay/scripts/nordrelay.mjs status
-node plugins/nordrelay/scripts/nordrelay.mjs update
-node plugins/nordrelay/scripts/nordrelay.mjs restart
-node plugins/nordrelay/scripts/nordrelay.mjs stop
-node plugins/nordrelay/scripts/nordrelay.mjs foreground
-node plugins/nordrelay/scripts/nordrelay.mjs user list
-node plugins/nordrelay/scripts/nordrelay.mjs doctor
-node plugins/nordrelay/scripts/nordrelay.mjs web
-node plugins/nordrelay/scripts/nordrelay.mjs peer list
-```
-
-NPM shortcuts:
-
-```bash
-npm start
-npm run status
-npm stop
-npm run foreground
-```
-
-Runtime files:
-
-- PID file: `~/.nordrelay/nordrelay.pid`
-- State file: `~/.nordrelay/state.json`
-- Log file: `~/.nordrelay/nordrelay.log`
-- Home override: `NORDRELAY_HOME=/custom/path`
-- Local dashboard: `nordrelay web --host 127.0.0.1 --port 31878`
-- `nordrelay start` and `nordrelay status` print the configured WebUI URL.
-
-## WebUI Dashboard
-
-Start the local WebUI:
-
-```bash
+nordrelay doctor
 nordrelay web
+nordrelay restart
+nordrelay update
 ```
 
-If the connector is not already running, `nordrelay web` starts it automatically before binding the dashboard.
-
-Open:
-
-```text
-http://127.0.0.1:31878/
-```
-
-The dashboard is a second NordRelay client next to Telegram. It can:
-
-- Start a new Codex, Pi, Hermes, OpenClaw, or Claude Code session.
-- Start a new session from a modal with agent, workspace, model, reasoning/thinking, fast mode, and launch-profile choices.
-- Switch or attach existing sessions, and copy thread IDs from the session list.
-- Send prompts and receive streamed text/tool/plan updates through Server-Sent Events.
-- Upload images, documents, and audio files from the chat composer. Images are passed as image inputs, documents are staged for the agent, and audio is transcribed through the configured voice backend.
-- Keep a persistent per-thread WebUI chat history across page reloads.
-- Control the active session model, reasoning/thinking, fast mode, and launch profile directly from the chat view.
-- Abort turns, hand sessions back to the native CLI, and inspect the active session.
-- Manage queued prompts with pause/resume, run, cancel, reorder buttons, and drag-and-drop prioritization.
-- Inspect unified jobs across queued prompts, active turns, mirrored CLI work, agent updates, self-updates, and support-bundle exports.
-- Browse, preview, download, ZIP, and delete artifacts.
-- Inspect the activity timeline for WebUI and mirrored CLI turns.
-- Edit all supported runtime settings from tabbed Settings groups with option selects, validation feedback, and restart actions.
-- View filtered connector/update/agent-update logs, structured diagnostics, enabled channels, and agent adapters.
-- Inspect a per-agent capability matrix showing model, reasoning, launch, fast mode, attachments, activity, usage, auth, login/logout, and handback support.
-- Check NordRelay and agent CLI versions, then start Codex, Pi, Hermes, OpenClaw, or Claude Code updates from outdated rows or installs from not-installed rows with live output, cancel, delete-log, and stdin response controls.
-- Build dashboard CSS and client JavaScript from modular source assets through esbuild, then serve them as authenticated static assets instead of inline HTML.
-- Pair, test, enable/disable, and revoke NordRelay peers, then switch the dashboard target between the local instance and paired remote instances.
-
-Dashboard API endpoints are served under `/api/*`. Streaming uses `GET /api/events`.
-
-Dashboard auth:
-
-```dotenv
-NORDRELAY_DASHBOARD_HOST=127.0.0.1
-NORDRELAY_DASHBOARD_PORT=31878
-```
-
-The dashboard always requires NordRelay email/password login. Login cookies use `SameSite=Strict`, and every dashboard route, API endpoint, SSE stream, artifact download, and health endpoint requires an authenticated active user with the matching permission.
-
-Webhook mode:
-
-```dotenv
-TELEGRAM_TRANSPORT=webhook
-TELEGRAM_WEBHOOK_URL=https://relay.example
-TELEGRAM_WEBHOOK_HOST=127.0.0.1
-TELEGRAM_WEBHOOK_PORT=8080
-TELEGRAM_WEBHOOK_PATH=/telegram/webhook
-TELEGRAM_WEBHOOK_SECRET=replace-with-random-secret
-```
-
-Run NordRelay behind your reverse proxy so the public URL forwards to `http://127.0.0.1:8080/telegram/webhook`. Dashboard health checks are available to authenticated WebUI sessions through `/healthz` and `/api/health`.
-
-## Telegram Commands
-
-- `/start` shows welcome text and the selected launch profile.
-- `/help` shows the grouped command reference.
-- `/channels` shows available and planned messaging adapters.
-- `/agents` shows available and planned coding-agent adapters.
-- `/agent` selects the active agent for this Telegram context.
-- `/peers` shows configured NordRelay peer instances.
-- `/target local|<peer-id>` selects whether prompts for this chat run locally or on a paired peer.
-- `/link <code>` links the Telegram account to a NordRelay user.
-- `/whoami` shows the linked NordRelay user, groups, and permissions.
-- `/register_chat` enables the current Telegram group or forum chat for NordRelay when the linked user has user-management permission.
-- `/new` starts a new thread. If the selected agent knows multiple workspaces, Telegram shows a workspace picker.
-- `/session` shows current thread details.
-- `/sessions` opens a paginated recent-session picker.
-- `/sessions <query>` searches recent sessions.
-- `/sync` syncs the active session from local CLI state when supported.
-- `/pinned` opens a pinned-thread picker.
-- `/pin [thread-id]` pins a thread for this Telegram context; defaults to the active thread.
-- `/unpin [thread-id]` unpins a thread for this Telegram context; defaults to the active thread.
-- `/switch <session-id>` switches directly to a known session.
-- `/attach <session-id>` binds a known session to the current chat or forum topic.
-- `/handback` detaches the active session and prints the native CLI resume command.
-- `/retry` resends the last prompt for this Telegram context.
-- `/queue` shows queued prompts for this Telegram context with inline run/top/up/down/cancel buttons.
-- `/queue pause` pauses automatic queued prompt execution.
-- `/queue resume` resumes automatic queued prompt execution.
-- `/queue later <minutes> <prompt>` schedules a prompt for later execution.
-- `/queue inspect <queue-id>` shows one queued prompt with created time, schedule time, attempts, and last error.
-- `/queue move <queue-id> top|up|down` changes queued prompt priority.
-- `/queue run <queue-id>` resumes the queue and runs that prompt next when the session is idle.
-- Queued prompt replies include a cancel button while the prompt is still waiting.
-- `/cancel <queue-id>` removes one queued prompt; the queue id is the short code shown in messages such as `Queued prompt 332kmt`.
-- `/clearqueue` clears queued prompts for this Telegram context.
-- `/activity [all|tools|errors|user|agent|tasks] [limit] [since 1h] [export]` shows or exports rollout activity for the active thread.
-- `/audit [limit]` shows recent audit events. Requires `audit.read`.
-- `/lock` locks writes for this Telegram session to the current user.
-- `/unlock` releases the current session write lock.
-- `/locks` lists active write locks.
-- `/artifacts [latest|zip latest|turn-id|images|docs|search <text>|delete <turn-id>]` lists, filters, resends, zips, searches, or deletes generated artifacts for the current workspace.
-- `/workspaces` lists workspaces known to the selected agent and allowed by the workspace policy.
-- `/abort` cancels the current operation.
-- `/stop` is an alias for `/abort`.
-- `/launch_profiles` or `/launch` opens the launch profile picker.
-- `/fast [on|off]` toggles Codex fast mode. Without an argument it flips the current state.
-- `/model` opens the model picker.
-- `/reasoning` opens the selected agent's reasoning or thinking picker.
-- `/effort` is a backward-compatible alias for `/reasoning`.
-- `/mirror [off|status|final|full]` controls local CLI mirroring for this Telegram context.
-- `/notify [off|minimal|all]` controls Telegram notifications.
-- `/notify quiet HH-HH` sets quiet hours; `/notify quiet off` disables them.
-- `/auth` reports Codex authentication status, Pi provider environment health, Hermes API Server reachability, OpenClaw Gateway reachability, or Claude Code CLI auth for the selected agent.
-- `/login` starts Telegram-initiated CLI login for Codex, Hermes, or Claude Code when one of those agents is selected.
-- `/logout` signs out from CLI auth for Codex, Hermes, or Claude Code when one of those agents is selected; Codex logout is disabled while `CODEX_API_KEY` is active.
-- `/voice` reports voice transcription backends and current voice preferences.
-- `/voice backend auto|parakeet|faster-whisper|openai` selects backend preference.
-- `/voice language auto|<code>` selects transcription language.
-- `/voice transcribe_only on|off` controls whether voice is only transcribed or also sent to the selected agent.
-- `/tasks` or `/progress` reports the current turn and queue progress.
-- `/status` reports connector runtime status.
-- `/health` reports runtime health, auth, PIDs, Codex CLI, Pi CLI, Hermes CLI, OpenClaw CLI, Claude Code CLI, and state DB.
-- `/version` reports connector, Codex CLI, Pi CLI, Hermes CLI, OpenClaw CLI, and Claude Code CLI paths plus installed/latest NordRelay, Codex, Pi, Hermes, OpenClaw, and Claude Code versions with status icons.
-- `/logs [lines]` shows a redacted, timestamped connector log tail. Requires `logs.read`.
-- `/logs update [lines]` shows the self-update log. Requires `logs.read`.
-- `/logs agent [lines]` shows the aggregate agent updater log. Requires `logs.read`.
-- `/logs all [lines]` shows connector, self-update, and agent update logs together. Requires `logs.read`.
-- `/diagnostics` shows redacted connector diagnostics. Requires `diagnostics.read`.
-- `/support` exports a redacted diagnostics ZIP. Requires `diagnostics.read`.
-- `/restart` restarts the connector process. Requires `system.restart`.
-- `/update` updates through npm or git depending on the detected install type, then restarts only on success. Requires `updates.run`.
-- `/update agents`, `/update <agent>`, `/update install <agent>`, `/update jobs`, `/update log <id>`, `/update cancel <id>`, and `/update input <id> <text>` manage agent CLI update and install jobs. Requires `updates.run`.
-
-## Discord Commands
-
-Discord supports slash commands and `/command` text messages for the shared command set. The primary differences from Telegram are:
-
-- `/register_channel` replaces `/register_chat` for guild channels and threads.
-- `/prompt <text>` is available for slash-command-only deployments where regular message content is disabled.
-- `/link <code>` consumes Discord link codes created in the WebUI or with `nordrelay user discord-link-code`.
-- `/queue`, `/sessions`, `/agent`, `/model`, `/reasoning`, `/launch`, `/artifacts`, `/update`, and `/stop` use Discord buttons where component limits allow.
-- `/peers` and `/target local|<peer-id>` use the same paired-instance target selection as Telegram.
-- `/artifacts latest`, `/artifacts zip latest`, `/artifacts images`, `/artifacts docs`, `/artifacts search <text>`, and `/artifacts delete <turn-id>` are available in Discord.
-- Unsafe launch profiles require explicit confirmation with `/launch <profile-id> confirm`.
-- Discord does not support Telegram reactions or Telegram webhook transport; typing, message edits, attachments, files, DMs, guild channels, and threads are supported.
-
-## Slack Commands
-
-Slack supports the configured slash command and `/command` text messages for the shared command set. The primary differences from Telegram are:
-
-- `/register_channel` enables the current Slack channel or thread for NordRelay when the linked user has user-management permission.
-- `/prompt <text>` is available through the configured slash command when regular message content is disabled.
-- `/link <code>` consumes Slack link codes created in the WebUI or with `nordrelay user slack-link-code`.
-- `/queue`, `/sessions`, `/agent`, `/model`, `/reasoning`, `/launch`, `/artifacts`, `/update`, and `/stop` use Slack buttons where Block Kit limits allow.
-- `/peers` and `/target local|<peer-id>` use the same paired-instance target selection as Telegram and Discord.
-- `/artifacts latest`, `/artifacts zip latest`, `/artifacts images`, `/artifacts docs`, `/artifacts search <text>`, and `/artifacts delete <turn-id>` are available in Slack.
-- Unsafe launch profiles require explicit confirmation with `/launch <profile-id> confirm`.
-- Slack does not support Telegram reactions or Telegram webhook transport; typing/status, message edits, attachments, files, DMs, channels, and threads are supported.
-
-## Command Examples
-
-Switching to an existing thread:
+Chat adapters share the core command set:
 
 ```text
+/help
+/session
 /sessions
-```
-
-Tap a listed thread/session. The connector imports workspace, model, reasoning/thinking, and provider-specific metadata from the selected agent.
-
-Direct session switch:
-
-```text
-/switch 019e178a-f275-7d01-95d6-c244ff3e30ed
-```
-
-Attach an existing CLI session to the current Telegram topic:
-
-```text
-/attach 019e178a-f275-7d01-95d6-c244ff3e30ed
-```
-
-Hand a session back to the native CLI:
-
-```text
-/handback
-```
-
-The bot replies with a command like:
-
-```bash
-cd ~/projects/my-workspace && codex resume 019e178a-f275-7d01-95d6-c244ff3e30ed
-```
-
-For Pi sessions the command looks like:
-
-```bash
-cd ~/projects/my-workspace && pi --session ~/.pi/agent/sessions/.../session.jsonl
-```
-
-For Hermes sessions the command looks like:
-
-```bash
-cd ~/projects/my-workspace && hermes --resume 20260512_181422_ab12cd34
-```
-
-For OpenClaw sessions the command looks like:
-
-```bash
-cd ~/projects/my-workspace && openclaw agent --agent main --session-id nordrelay-openclaw-a1b2c3d4e5f6 --message '<your next message>'
-```
-
-For Claude Code sessions the command looks like:
-
-```bash
-cd ~/projects/my-workspace && claude --resume 019e178a-f275-7d01-95d6-c244ff3e30ed
-```
-
-Change model:
-
-```text
+/agent
 /model
-```
-
-Tap the model to use for new or reattached threads.
-
-Change reasoning effort:
-
-```text
 /reasoning
+/queue
+/artifacts
+/mirror
+/stop
+/diagnostics
 ```
 
-For Codex choose one of `minimal`, `low`, `medium`, `high`, or `xhigh`. For Pi choose one of `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`. For Hermes choose one of `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. For OpenClaw choose one of `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`. For Claude Code choose one of `off`, `low`, `medium`, `high`, or `xhigh`.
-
-Toggle fast mode:
-
-```text
-/fast
-/fast on
-/fast off
-```
-
-Fast mode maps to launch profiles: `on` selects an approval policy of `never`, while `off` selects an approval-requesting profile such as Review. If a thread is idle, `/fast` reattaches the current thread with the selected launch behavior immediately.
-
-Choose launch profile:
-
-```text
-/launch_profiles
-```
-
-Tap the profile. Unsafe profiles require confirmation before they become active.
-
-## File, Photo, Voice, and Artifact Workflow
-
-Text:
-
-- Any non-command text message becomes a prompt for the selected agent.
-- While the selected agent works, Telegram shows `typing`.
-- Replies stream back into the same chat or topic.
-
-Photos:
-
-- Send a photo with or without a caption.
-- The connector downloads it and passes it to the selected agent as local image input.
-- The caption becomes the text prompt when present.
-- Sending multiple photos as a Telegram album creates one combined agent prompt.
-
-Documents:
-
-- Send a document with or without a caption.
-- The connector downloads it, sanitizes the filename, enforces `MAX_FILE_SIZE`, and stages it under:
-
-```text
-<workspace>/.nordrelay/inbox/<turn-id>/
-```
-
-- The selected agent receives prompt instructions with the staged file paths.
-- The caption becomes the text prompt when present.
-- Document albums and mixed media groups are processed as one turn; oversized files are skipped and reported.
-
-Artifacts:
-
-- For generated files that should be returned to Telegram, tell the selected agent to write them to:
-
-```text
-<workspace>/.nordrelay/turns/<turn-id>/out/
-```
-
-- The connector stores files in that directory and keeps them available for `/artifacts`.
-- Automatic Telegram artifact delivery is off by default. Set `TELEGRAM_AUTO_SEND_ARTIFACTS=true` to collect and send files right after a turn.
-- When automatic delivery or explicit `/artifacts` sending is used, image outputs are sent with Telegram previews and other outputs are sent as documents.
-- When more than five artifacts are sent, the connector tries to send one ZIP bundle instead of many separate files.
-- Use `/artifacts` to list recent artifact turns with inline Send/ZIP/Delete actions.
-- Use `/artifacts latest`, `/artifacts zip latest`, or `/artifacts <turn-id>` from text commands.
-- Use `/artifacts images`, `/artifacts docs`, or `/artifacts search <text>` to narrow large artifact histories.
-- Use `/artifacts delete <turn-id>` to delete an artifact turn without opening the inline confirmation flow.
-- Telegram file delivery is capped at the configured `MAX_FILE_SIZE` per artifact or ZIP bundle.
-- Old turn and inbox directories are pruned automatically to keep workspace state compact.
-
-Voice and audio:
-
-- Send a Telegram voice note or audio file.
-- The connector transcribes it, then sends the transcript to the selected agent.
-- Local transcription is tried first with `parakeet-coreml` or `faster-whisper` when installed.
-- OpenAI Whisper is used when `OPENAI_API_KEY` is set.
-
-Voice prerequisites:
-
-```bash
-# macOS Apple Silicon
-brew install ffmpeg
-npm install parakeet-coreml
-```
-
-```bash
-# Debian/Ubuntu
-sudo apt-get install ffmpeg
-python3 -m venv .venv
-.venv/bin/python -m pip install --upgrade pip
-.venv/bin/python -m pip install faster-whisper
-```
-
-```dotenv
-FASTER_WHISPER_PYTHON=.venv/bin/python
-FASTER_WHISPER_MODEL=base
-FASTER_WHISPER_COMPUTE_TYPE=int8
-```
-
-Whisper fallback:
-
-```dotenv
-OPENAI_API_KEY=sk-...
-```
-
-Voice transcription uses `OPENAI_API_KEY`, not `CODEX_API_KEY`.
-
-## Environment Reference
-
-Telegram:
-
-- `TELEGRAM_ENABLED`: starts the Telegram adapter. Defaults to `true`.
-- `TELEGRAM_BOT_TOKEN`: BotFather token. Required for the Telegram adapter to start.
-- `TELEGRAM_RATE_LIMIT_MIN_INTERVAL_MS`: minimum interval for normal Telegram API sends. Defaults to `80`.
-- `TELEGRAM_EDIT_MIN_INTERVAL_MS`: minimum interval for Telegram message edits. Defaults to `1200`.
-- `TELEGRAM_TRANSPORT`: `polling` or `webhook`. Defaults to `polling`.
-- `TELEGRAM_WEBHOOK_URL`: public base URL for webhook mode, for example `https://relay.example`.
-- `TELEGRAM_WEBHOOK_HOST`: local bind host for webhook mode. Defaults to `127.0.0.1`.
-- `TELEGRAM_WEBHOOK_PORT`: local bind port for webhook mode. Defaults to `8080`.
-- `TELEGRAM_WEBHOOK_PATH`: webhook request path. Defaults to `/telegram/webhook`.
-- `TELEGRAM_WEBHOOK_SECRET`: optional Telegram webhook secret token.
-- `NORDRELAY_CLI_MIRROR_MODE`: default CLI mirror mode for chat adapters: `off`, `status`, `final`, or `full`. Defaults to `status`.
-- `NORDRELAY_CLI_MIRROR_MIN_UPDATE_MS`: default minimum interval for mirrored CLI status edits. Defaults to `4000`.
-- `NORDRELAY_NOTIFY_MODE`: default notification mode for chat adapters: `off`, `minimal`, or `all`. Defaults to `minimal`.
-- `NORDRELAY_QUIET_HOURS`: optional default quiet-hour range in `HH-HH` format, for example `22-7`; use `off` in a channel override to disable inherited quiet hours.
-- `NORDRELAY_AUTO_SEND_ARTIFACTS`: default automatic artifact summaries/uploads for chat adapters. Defaults to `false`.
-- `TELEGRAM_CLI_MIRROR_MODE`, `TELEGRAM_CLI_MIRROR_MIN_UPDATE_MS`, `TELEGRAM_NOTIFY_MODE`, `TELEGRAM_QUIET_HOURS`, and `TELEGRAM_AUTO_SEND_ARTIFACTS`: optional Telegram-specific overrides.
-- `TELEGRAM_REDACT_PATTERNS`: comma-separated regular expressions for additional Telegram/log redaction.
-
-Discord:
-
-- `DISCORD_ENABLED`: starts the Discord adapter. Defaults to `false`.
-- `DISCORD_BOT_TOKEN`: Discord bot token. Required for the Discord adapter to start.
-- `DISCORD_CLIENT_ID`: Discord application/client id used for slash-command registration.
-- `DISCORD_GUILD_IDS`: optional comma-separated guild ids for instant guild slash-command registration.
-- `DISCORD_ALLOWED_GUILD_IDS`: optional guild allow-list before user/group permissions are checked.
-- `DISCORD_ALLOWED_CHANNEL_IDS`: optional channel allow-list before user/group permissions are checked.
-- `DISCORD_MESSAGE_CONTENT_ENABLED`: reads regular Discord text messages as prompts. Defaults to `true`.
-- `DISCORD_COMMAND_MODE`: `slash`, `message`, or `both`. Defaults to `both`.
-- `DISCORD_AUTO_REGISTER_COMMANDS`: registers slash commands on startup when `DISCORD_CLIENT_ID` is set. Defaults to `true`.
-- `DISCORD_CLI_MIRROR_MODE`, `DISCORD_CLI_MIRROR_MIN_UPDATE_MS`, `DISCORD_NOTIFY_MODE`, `DISCORD_QUIET_HOURS`, and `DISCORD_AUTO_SEND_ARTIFACTS`: optional Discord-specific overrides for the channel-neutral defaults.
-
-Slack:
-
-- `SLACK_ENABLED`: starts the Slack adapter. Defaults to `false`.
-- `SLACK_BOT_TOKEN`: Slack bot token. Required for the Slack adapter to start.
-- `SLACK_APP_TOKEN`: Slack app-level token for Socket Mode. Required when `SLACK_SOCKET_MODE=true`.
-- `SLACK_SIGNING_SECRET`: Slack signing secret for HTTP Events mode. Required when `SLACK_SOCKET_MODE=false`.
-- `SLACK_SOCKET_MODE`: uses Slack Socket Mode instead of an HTTP Events receiver. Defaults to `true`.
-- `SLACK_PORT`: HTTP receiver port when Socket Mode is disabled. Defaults to `3000`.
-- `SLACK_ALLOWED_TEAM_IDS`: optional Slack workspace allow-list before user/group permissions are checked.
-- `SLACK_ALLOWED_CHANNEL_IDS`: optional channel allow-list before user/group permissions are checked.
-- `SLACK_MESSAGE_CONTENT_ENABLED`: reads regular Slack text messages as prompts. Defaults to `true`.
-- `SLACK_COMMAND`: slash command configured in Slack. Defaults to `/nordrelay`.
-- `SLACK_CLI_MIRROR_MODE`, `SLACK_CLI_MIRROR_MIN_UPDATE_MS`, `SLACK_NOTIFY_MODE`, `SLACK_QUIET_HOURS`, and `SLACK_AUTO_SEND_ARTIFACTS`: optional Slack-specific overrides for the channel-neutral defaults.
-
-User management:
-
-- Users, groups, Telegram identities, Telegram group-chat access, Discord identities, Discord channel access, Slack identities, Slack channel access, and web sessions are stored in `~/.nordrelay/users.json`.
-- Manage users in the WebUI Users page or with `nordrelay user list`, `create-admin`, `create`, `reset-password`, `link-telegram`, `link-discord`, `link-slack`, `link-code`, `discord-link-code`, and `slack-link-code`.
-- Built-in groups are `admin`, `user`, and `readonly`.
-- Group permissions include `inspect`, `sessions.read`, `sessions.write`, `prompt.send`, `prompt.abort`, `files.read`, `files.write`, `settings.read`, `settings.write`, `auth.manage`, `diagnostics.read`, `logs.read`, `logs.clear`, `queue.read`, `queue.write`, `updates.run`, `system.restart`, `users.read`, `users.write`, `audit.read`, `peers.read`, `peers.write`, and `peers.connect`.
-- Custom groups can also restrict access to specific agent ids, workspace roots, Telegram chat ids, Discord channel ids, and Slack channel ids.
-
-Peers:
-
-- `NORDRELAY_PEER_ENABLED`: starts the dedicated peer API. Defaults to `false`.
-- `NORDRELAY_PEER_NAME`: optional human-readable node name shown to paired instances.
-- `NORDRELAY_PEER_HOST`: peer API bind host. Defaults to `127.0.0.1`.
-- `NORDRELAY_PEER_PORT`: peer API port. Defaults to `31979`.
-- `NORDRELAY_PEER_PUBLIC_URL`: optional URL other instances should use to reach this node.
-- `NORDRELAY_PEER_TLS_ENABLED`: serves the peer API over HTTPS with an automatically generated local certificate. Defaults to `true`.
-- `NORDRELAY_PEER_REQUIRE_TLS`: refuses plaintext peer serving on non-loopback hosts. Defaults to `true`.
-- Peer identity, TLS certificate, peers, and invitations are stored under `~/.nordrelay/identity.json`, `~/.nordrelay/tls/`, and `~/.nordrelay/peers.json`.
-- Peer invitations expire after at most 24 hours even if a longer lifetime is requested.
-
-Agent selection:
-
-- `NORDRELAY_CODEX_ENABLED`: enables Codex contexts. Defaults to `true`.
-- `NORDRELAY_PI_ENABLED`: enables Pi contexts. Defaults to `false`.
-- `NORDRELAY_HERMES_ENABLED`: enables Hermes contexts through the Hermes API Server. Defaults to `false`.
-- `NORDRELAY_OPENCLAW_ENABLED`: enables OpenClaw contexts through the OpenClaw Gateway. Defaults to `false`.
-- `NORDRELAY_CLAUDE_CODE_ENABLED`: enables Claude Code contexts through the Claude Agent SDK. Defaults to `false`.
-- `NORDRELAY_DEFAULT_AGENT`: `codex`, `pi`, `hermes`, `openclaw`, or `claude-code`, used for new chat contexts. Defaults to the first enabled agent.
-- `NORDRELAY_STATE_BACKEND`: `json` or `sqlite`. JSON is the default; SQLite requires `better-sqlite3`.
-- `NORDRELAY_AUDIT_MAX_EVENTS`: maximum audit events retained. Defaults to `1000`.
-- `NORDRELAY_SESSION_LOCK_TTL_MS`: session write-lock TTL. Defaults to `1800000`.
-- `NORDRELAY_VERSION_CACHE_TTL_MS`: npm version freshness cache TTL. Defaults to `3600000`; set `0` to disable.
-- `NORDRELAY_CLI_VERSION_CACHE_TTL_MS`: installed agent CLI version cache TTL. Defaults to `60000`; set `0` to disable.
-
-Dashboard:
-
-- `NORDRELAY_DASHBOARD_HOST`: dashboard bind host. Defaults to `127.0.0.1`.
-- `NORDRELAY_DASHBOARD_PORT`: dashboard bind port. Defaults to `31878`.
-- `NORDRELAY_ENV_FILE`: optional explicit env-file path used by the wrapper and edited by the dashboard settings page. Defaults to `~/.nordrelay/nordrelay.env`.
-
-Codex:
-
-- `CODEX_API_KEY`: optional API key for Codex SDK auth.
-- `CODEX_CLI_PATH`: optional explicit path to the Codex CLI executable.
-- `CODEX_USE_BUNDLED_CLI`: set `true` to force the SDK-bundled Codex CLI instead of the host `codex` executable.
-- `CODEX_MODEL`: default model for new threads.
-- `CODEX_SYNC_INTERVAL_MS`: periodic local Codex-state sync interval for active chat sessions. Defaults to `10000`; set `0` to disable.
-- `CODEX_EXTERNAL_BUSY_CHECK_MS`: how often queued chat prompts re-check an active local Codex CLI task. Defaults to `5000`.
-- `CODEX_EXTERNAL_BUSY_STALE_MS`: maximum age for an unclosed rollout task before it is treated as stale instead of active. Defaults to `300000`.
-- `CODEX_SANDBOX_MODE`: default sandbox mode, one of `read-only`, `workspace-write`, `danger-full-access`.
-- `CODEX_APPROVAL_POLICY`: default approval policy, one of `never`, `on-request`, `on-failure`, `untrusted`.
-- `CODEX_LAUNCH_PROFILES_JSON`: JSON array of additional launch profiles.
-- `CODEX_DEFAULT_LAUNCH_PROFILE`: profile id used by default. Defaults to `default`.
-- `ENABLE_UNSAFE_LAUNCH_PROFILES`: set `true` to expose `danger-full-access` profiles.
-
-Pi:
-
-- `PI_CLI_PATH`: optional explicit path to the Pi CLI executable. Defaults to `pi` on `PATH`.
-- `PI_SESSION_DIR`: optional Pi session directory. Defaults to `~/.pi/agent/sessions/` or `PI_CODING_AGENT_SESSION_DIR`.
-- `PI_DEFAULT_MODEL`: optional default model pattern for new Pi sessions, for example `openai-codex/gpt-5.5`.
-- `PI_DEFAULT_THINKING`: default Pi thinking level: `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`. Defaults to `medium`.
-- `PI_DEFAULT_PROFILE`: default Pi launch profile: `default`, `readonly`, `no-tools`, `offline`, or `safe-offline`. Defaults to `default`.
-
-Hermes:
-
-- `HERMES_CLI_PATH`: optional explicit path to the Hermes CLI executable. Defaults to `hermes` on `PATH`.
-- `HERMES_HOME`: optional Hermes home directory. Defaults to `~/.hermes`.
-- `HERMES_STATE_DB_PATH`: optional explicit Hermes `state.db` path. Overrides `HERMES_HOME`.
-- `HERMES_API_BASE_URL`: Hermes API Server base URL. Defaults to `http://127.0.0.1:8642`.
-- `HERMES_API_KEY`: optional bearer token for the Hermes API Server.
-- `HERMES_DEFAULT_MODEL`: optional model label sent with new Hermes API runs.
-- `HERMES_DEFAULT_REASONING`: default Hermes reasoning effort: `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`.
-- `HERMES_DEFAULT_PROFILE`: default Hermes launch profile: `default`, `safe`, `readonly`, or `yolo`. Defaults to `default`.
-
-OpenClaw:
-
-- `OPENCLAW_CLI_PATH`: optional explicit path to the OpenClaw CLI executable. Defaults to `openclaw` on `PATH`.
-- `OPENCLAW_GATEWAY_URL`: OpenClaw Gateway WebSocket URL. Defaults to `ws://127.0.0.1:18789`.
-- `OPENCLAW_GATEWAY_TOKEN`: optional shared-secret token for the OpenClaw Gateway.
-- `OPENCLAW_GATEWAY_PASSWORD`: optional shared-secret password for the OpenClaw Gateway.
-- `OPENCLAW_AGENT_ID`: OpenClaw agent id used for runs and session discovery. Defaults to `main`.
-- `OPENCLAW_HOME`: optional OpenClaw home directory. Defaults to `~/.openclaw`.
-- `OPENCLAW_STATE_DIR`: optional explicit OpenClaw state directory. Overrides `OPENCLAW_HOME`.
-- `OPENCLAW_DEFAULT_MODEL`: optional model label sent with new OpenClaw Gateway runs.
-- `OPENCLAW_DEFAULT_THINKING`: default OpenClaw thinking level: `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`.
-- `OPENCLAW_DEFAULT_PROFILE`: default OpenClaw launch profile: `default`, `safe`, `readonly`, `local`, or `deliver`. Defaults to `default`.
-
-Claude Code:
-
-- `CLAUDE_CODE_CLI_PATH`: optional explicit path to the Claude Code CLI executable. Defaults to `claude` on `PATH`, then the SDK bundled runtime.
-- `CLAUDE_CONFIG_DIR`: optional Claude config directory. Defaults to `~/.claude`.
-- `CLAUDE_CODE_DEFAULT_MODEL`: optional default Claude Code model alias or model id.
-- `CLAUDE_CODE_DEFAULT_EFFORT`: default Claude Code effort: `off`, `low`, `medium`, `high`, or `xhigh`.
-- `CLAUDE_CODE_DEFAULT_PROFILE`: default Claude Code launch profile: `default`, `accept-edits`, `plan`, `readonly`, `no-tools`, or `bypass-permissions`. Defaults to `default`.
-- `CLAUDE_CODE_MAX_TURNS`: maximum agentic turns per Claude Code prompt. Defaults to `100`.
-
-Telegram output:
-
-- `CONNECTOR_LOG_FORMAT`: `text` or `json`. Defaults to `text`.
-- `TOOL_VERBOSITY`: `all`, `summary`, `errors-only`, or `none`.
-- `SHOW_TURN_TOKEN_USAGE`: appends per-turn token usage when `true`.
-- `ENABLE_TELEGRAM_REACTIONS`: enables Telegram reactions when `true`.
-- `MAX_FILE_SIZE`: maximum inbound Telegram document size in bytes. Defaults to 20 MB.
-- `ARTIFACT_RETENTION_DAYS`: artifact/inbox turn age before pruning. Defaults to `7`.
-- `ARTIFACT_MAX_TURNS`: maximum artifact turn directories to keep per workspace. Defaults to `30`.
-- `ARTIFACT_MAX_INBOX_DIRS`: maximum staged inbox directories to keep per workspace. Defaults to `30`.
-- `ARTIFACT_IGNORE_DIRS`: comma-separated extra directory names or relative paths ignored during workspace artifact scans.
-- `ARTIFACT_IGNORE_GLOBS`: comma-separated glob patterns ignored during workspace artifact scans.
-- `TELEGRAM_AUTO_SEND_ARTIFACTS`: automatically post generated artifact summaries/files after Telegram turns and mirrored CLI turns. Defaults to `false`.
-
-Workspace policy:
-
-- `WORKSPACE_ALLOWED_ROOTS`: comma-separated root directories allowed for session switching and workspace selection. Empty means unrestricted.
-- `WORKSPACE_WARN_ROOTS`: comma-separated broad roots that should be allowed but warned about in `/session` and `/workspaces`.
-
-Auth and voice:
-
-- `ENABLE_TELEGRAM_LOGIN`: enables `/login` and `/logout`. Defaults to `true`.
-- `FASTER_WHISPER_PYTHON`: Python executable for local Linux voice transcription. Example: `.venv/bin/python`.
-- `FASTER_WHISPER_MODEL`: faster-whisper model name. Defaults to `base`.
-- `FASTER_WHISPER_DEVICE`: faster-whisper device. Defaults to `cpu`.
-- `FASTER_WHISPER_COMPUTE_TYPE`: faster-whisper compute type. Defaults to `int8`.
-- `FASTER_WHISPER_LANGUAGE`: optional fixed transcription language.
-- `FASTER_WHISPER_TIMEOUT_MS`: local transcription timeout. Defaults to `600000`.
-- `OPENAI_API_KEY`: enables Whisper transcription fallback for voice/audio.
-- `VOICE_PREFERRED_BACKEND`: `auto`, `parakeet`, `faster-whisper`, or `openai`. Defaults to `auto`.
-- `VOICE_DEFAULT_LANGUAGE`: optional default language code, for example `de` or `en`.
-- `VOICE_TRANSCRIBE_ONLY`: when `true`, voice/audio messages are transcribed but not sent to the selected agent.
-
-NordRelay wrapper:
-
-- `NORDRELAY_HOME`: config/state/log directory override. Defaults to `~/.nordrelay`.
-- `NORDRELAY_SOURCE_ROOT`: runtime source root override. Useful when the plugin is launched from Codex cache.
-- `NORDRELAY_UPDATE_METHOD`: optional `auto`, `npm`, or `git` self-update method override used by `nordrelay update`, `/update`, and the WebUI update button. Auto uses git when the runtime root has a `.git` directory and npm otherwise.
-- Agent updates from the dashboard and Telegram use each agent's native updater where possible: `codex update`, `pi update pi`, `hermes update --yes`, `openclaw update --yes`, and `claude update`. Not-installed agents can be installed from the dashboard or with `/update install <agent>` using npm global installs.
-- `NORDRELAY_KEEP_PENDING_UPDATES`: set true to avoid dropping pending Telegram updates on start.
-- `NORDRELAY_FORWARD_TOOL_OUTPUT`: backward-compatible alias that sets `TOOL_VERBOSITY=all` when `TOOL_VERBOSITY` is unset.
-- `NORDRELAY_STATE_FILE`: internal state-file path passed by the wrapper.
-- `NORDRELAY_WRAPPER_PID`: internal wrapper PID passed to the runtime.
-- `NORDRELAY_DROP_PENDING_UPDATES`: internal polling startup flag.
-
-## Launch Profiles
-
-Built-in profiles:
-
-- `default`: uses `CODEX_SANDBOX_MODE` and `CODEX_APPROVAL_POLICY`.
-- `readonly`: `read-only` with `never`.
-- `review`: `workspace-write` with `on-request`.
-- `full-access`: `danger-full-access` with `never`, only when unsafe profiles are enabled.
-
-Custom profile example:
-
-```dotenv
-CODEX_LAUNCH_PROFILES_JSON=[{"id":"review-safe","label":"Review Safe","sandboxMode":"workspace-write","approvalPolicy":"on-request"}]
-CODEX_DEFAULT_LAUNCH_PROFILE=review-safe
-```
-
-Multiple profiles:
-
-```dotenv
-CODEX_LAUNCH_PROFILES_JSON=[{"id":"readonly-audit","label":"Readonly Audit","sandboxMode":"read-only","approvalPolicy":"never"},{"id":"interactive","label":"Interactive","sandboxMode":"workspace-write","approvalPolicy":"on-request"}]
-```
-
-Unsafe full-access profile:
-
-```dotenv
-ENABLE_UNSAFE_LAUNCH_PROFILES=true
-CODEX_LAUNCH_PROFILES_JSON=[{"id":"host-full","label":"Host Full Access","sandboxMode":"danger-full-access","approvalPolicy":"never"}]
-```
-
-Unsafe profiles are intentionally gated. Chat adapters ask for confirmation before applying them.
+See [Commands](docs/commands.md) for the complete Telegram, Discord, Slack, queue, artifact, mirror, update, and diagnostic command reference.
 
-## Security Notes
+## What NordRelay Provides
 
-- Create the first admin user during setup and keep that account protected with a strong password.
-- Link Telegram accounts only to active NordRelay users that should control agents remotely.
-- Enable Telegram group/forum chats only when the whole chat context is trusted for the permissions granted to linked users.
-- Review group permissions before granting `prompt.send`, `prompt.abort`, `files.write`, `settings.write`, `updates.run`, `system.restart`, or `users.write`.
-- Review peer scopes before granting `peers.write`, `peers.connect`, broad `prompt.send`, or unrestricted workspace roots to a paired instance.
-- Treat `danger-full-access` as equivalent to shell access on the host.
-- Treat uploaded files as untrusted input. They are staged inside the active workspace so the selected sandbox policy still matters.
-- Keep `CODEX_API_KEY`, `HERMES_API_KEY`, `OPENCLAW_GATEWAY_TOKEN`, `OPENCLAW_GATEWAY_PASSWORD`, and `OPENAI_API_KEY` in `~/.nordrelay/nordrelay.env` or host secret management.
-- In group chats, remember that any linked user with prompt permissions can prompt the selected agent in that chat context.
-- Use `TOOL_VERBOSITY=summary` or `errors-only` when command output may include sensitive data.
-- Review and unsafe launch profiles add a Telegram approve/deny gate before each turn starts.
-- Keep the peer API disabled unless needed. For internet use, expose it only through a firewall, VPN, or hardened reverse proxy; keep TLS enabled and revoke unused peers with `nordrelay peer revoke <peer-id>`.
+- Independent sessions per Telegram chat/topic, Discord DM/channel/thread, Slack DM/channel/thread, WebUI, and peer target.
+- Streaming replies, typing/status indicators, tool activity, queue handling, retry, abort/stop, and CLI handback.
+- File, photo, voice/audio, and generated artifact workflows.
+- Per-user and per-group access control for WebUI and chat adapters.
+- Optional peer federation for controlling agents on other trusted NordRelay hosts.
+- WebUI dashboard for chat, sessions, settings, logs, diagnostics, updates, artifacts, peers, metrics, and users.
+- Agent adapters for Codex, Pi, Hermes, OpenClaw, and Claude Code.
+- Chat adapters for Telegram, Discord, and Slack.
 
-## Troubleshooting
+## Documentation
 
-Polling conflict:
+| Topic | Link |
+| --- | --- |
+| Full feature list and adapter capabilities | [docs/features.md](docs/features.md) |
+| First-run setup, users, running modes, and WebUI | [docs/setup.md](docs/setup.md) |
+| Telegram, Discord, Slack, and WebUI commands | [docs/commands.md](docs/commands.md) |
+| Files, photos, voice, transcription, and artifacts | [docs/workflows.md](docs/workflows.md) |
+| Environment variables and launch profiles | [docs/configuration.md](docs/configuration.md) |
+| Security notes and troubleshooting | [docs/security-troubleshooting.md](docs/security-troubleshooting.md) |
+| Deployment with npm, foreground, Docker, launchd, and systemd | [docs/deployment.md](docs/deployment.md) |
+| Codebase architecture and module map | [docs/architecture.md](docs/architecture.md) |
+| Public security policy | [SECURITY.md](SECURITY.md) |
+| Contribution guide | [CONTRIBUTING.md](CONTRIBUTING.md) |
 
-- Symptom: Telegram reports conflict or only one connector receives messages.
-- Cause: the same bot token is being polled by another process.
-- Fix: stop the other process or run `npm stop`, then `npm start`.
+## Development
 
-Stale plugin cache:
-
-- Symptom: Codex uses old command or skill text after a repo update.
-- Fix: reinstall/update the local marketplace or copy the plugin directory into the Codex plugin cache.
-- Current local cache path: `~/.codex/plugins/cache/nordrelay-local/nordrelay/<version>/`.
-
-Missing dependencies:
-
-- Symptom: startup says runtime is missing.
-- Fix:
+From a source checkout:
 
 ```bash
 npm install
 npm run build
+npm run check
+npm test
+npm run test:e2e
 ```
 
-Auth failures:
-
-- Symptom: prompt execution says Codex is not authenticated.
-- Fix: run `codex login` on the host, use `/login`, or set `CODEX_API_KEY`.
-- Use `/auth` to check the current auth method.
-
-No sessions listed:
-
-- Symptom: `/sessions` says no recent threads found.
-- Cause for Codex: `~/.codex/state_*.sqlite` is missing, unreadable, or has no active threads.
-- Cause for Pi: `~/.pi/agent/sessions/` or `PI_SESSION_DIR` is missing, unreadable, or has no session JSONL files.
-- Cause for Hermes: `~/.hermes/state.db` or `HERMES_STATE_DB_PATH` is missing, unreadable, or has no session rows.
-- Cause for OpenClaw: `openclaw sessions --all-agents --json` returns no sessions, or `OPENCLAW_HOME`/`OPENCLAW_STATE_DIR` points at the wrong state location.
-- Cause for Claude Code: `~/.claude/projects/` or `CLAUDE_CONFIG_DIR/projects` is missing, unreadable, or has no session JSONL files.
-- Fix: run the selected agent locally once, resume or create a session, then try `/sessions` again.
-
-Wrong model, reasoning, or fast mode after switching:
-
-- The connector reads model, reasoning, workspace, sandbox, and approval metadata from supported local agent state on `/sessions`, `/switch`, `/attach`, and `/session`; Codex fast mode is read from `~/.codex/config.toml`.
-- For Pi, the connector reads model/thinking from Pi JSONL sessions and refreshes active RPC state when a session is running.
-- For Hermes, the connector reads model, reasoning, token usage, and message activity from Hermes `state.db`; `/model` and `/reasoning` values are sent with future API runs.
-- For OpenClaw, the connector reads model, thinking, token usage, and activity from OpenClaw session state; `/model` and `/reasoning` values are sent with future Gateway runs.
-- For Claude Code, the connector reads model, effort, token usage, and activity from Claude Code transcript JSONL files; `/model` and `/reasoning` values are sent with future SDK runs.
-- If values look stale, make sure the selected local CLI has finished writing session state.
-
-Pi not available:
-
-- Symptom: `/agent` cannot switch to Pi, or startup says Pi CLI is missing.
-- Fix: install Pi from https://pi.dev/, ensure `pi` is on `PATH`, or set `PI_CLI_PATH`.
-- Enable Pi with `NORDRELAY_PI_ENABLED=true`.
-
-Hermes not available:
-
-- Symptom: `/agent` cannot switch to Hermes, `/auth` fails, or prompt execution says the Hermes API request failed.
-- Fix: start the Hermes API Server, ensure `HERMES_API_BASE_URL` points to it, and set `HERMES_API_KEY` if the server requires a key.
-- Enable Hermes with `NORDRELAY_HERMES_ENABLED=true`.
-
-OpenClaw not available:
-
-- Symptom: `/agent` cannot switch to OpenClaw, `/auth` fails, or prompt execution says the OpenClaw Gateway request failed.
-- Fix: start the OpenClaw Gateway, ensure `OPENCLAW_GATEWAY_URL` points to it, and set `OPENCLAW_GATEWAY_TOKEN` or `OPENCLAW_GATEWAY_PASSWORD` if the Gateway requires shared-secret auth.
-- Enable OpenClaw with `NORDRELAY_OPENCLAW_ENABLED=true`.
-
-Claude Code not available:
-
-- Symptom: `/agent` cannot switch to Claude Code, `/auth` fails, or prompt execution says Claude Code auth is missing.
-- Fix: run `claude auth login` on the host, ensure `claude` is on `PATH`, or set `CLAUDE_CODE_CLI_PATH`.
-- Enable Claude Code with `NORDRELAY_CLAUDE_CODE_ENABLED=true`.
-
-Voice not working:
-
-- Run `/voice` to list available backends.
-- Install `ffmpeg` and `faster-whisper` on Linux, install `parakeet-coreml` on macOS Apple Silicon, or set `OPENAI_API_KEY`.
-- Check `~/.nordrelay/nordrelay.log` for transcription errors.
-
-Files not returned:
-
-- Ensure Codex writes generated files to `.nordrelay/turns/<turn-id>/out/`.
-- Files over 50 MB are skipped.
-- Hidden files, temp files, and directories are ignored.
-- Use `ARTIFACT_IGNORE_DIRS` and `ARTIFACT_IGNORE_GLOBS` to suppress project-specific build/cache output.
-- Automatic artifact sending stays off unless `TELEGRAM_AUTO_SEND_ARTIFACTS=true`; `/artifacts` can still list and resend indexed outputs.
-
-## Deployment
-
-Foreground debugging:
+Useful runtime scripts:
 
 ```bash
 npm run foreground
-```
-
-Background process:
-
-```bash
 npm start
 npm run status
 npm stop
 ```
 
-Docker Compose:
-
-```bash
-docker compose up -d --build
-docker compose logs -f
-docker compose down
-```
-
-The compose file mounts:
-
-- `${HOME}/.codex` into the container for Codex auth and thread state.
-- `./workspace` as `/workspace` for container workspaces.
-
-launchd helper:
-
-```bash
-NORDRELAY_SOURCE_ROOT=~/projects/nordrelay launchd/start.sh
-```
-
-Linux systemd example:
-
-```ini
-[Unit]
-Description=NordRelay
-After=network-online.target
-
-[Service]
-Type=simple
-WorkingDirectory=/opt/nordrelay
-Environment=NORDRELAY_SOURCE_ROOT=/opt/nordrelay
-ExecStart=/usr/bin/node dist/index.js
-Restart=on-failure
-RestartSec=5
-
-[Install]
-WantedBy=multi-user.target
-```
-
-Build before starting a service:
+## Security Defaults
 
-```bash
-npm install
-npm run build
-```
+- The dashboard requires login.
+- Chat adapter access requires linked NordRelay users and registered/allowed channels.
+- Peer serving is disabled by default and requires explicit pairing.
+- Unsafe launch profiles are hidden unless explicitly enabled.
+- Secrets belong in `~/.nordrelay/nordrelay.env` or host secret management, not in the repository.
 
-## Architecture
+## License
 
-- `plugins/nordrelay/`: Codex plugin bundle with manifest, skill, command, icon, and process wrapper.
-- `plugins/nordrelay/scripts/nordrelay.mjs`: process manager for `start`, `stop`, `restart`, `status`, and `foreground`.
-- `src/index.ts`: runtime entrypoint, config load, auth check, state-file writes, polling lifecycle, shutdown.
-- `src/bot.ts`: Telegram prompt/session runtime, streaming, file/photo/voice handling, artifacts, and error handling.
-- `src/telegram-general-commands.ts`, `src/telegram-agent-commands.ts`, `src/telegram-preference-commands.ts`, `src/telegram-access-commands.ts`, `src/telegram-diagnostics-command.ts`, `src/telegram-update-commands.ts`, `src/telegram-support-command.ts`, and `src/telegram-command-menu.ts`: focused Telegram command groups for start/help/adapters, agent/auth controls, per-chat preferences, access linking, diagnostics/log/version commands, update jobs, diagnostics bundle export, and command menu registration.
-- `src/channel-adapter.ts`, `src/channel-runtime.ts`, `src/channel-command-core.ts`, `src/channel-actions.ts`, and `src/adapter-conformance.ts`: channel descriptors, shared command dispatch/coverage, outbound delivery contracts, channel-neutral responses, and generated feature/command conformance matrices.
-- `src/discord-bot.ts` and `src/slack-bot.ts`: Discord and Slack bridge runtimes built on the shared channel command core, channel runtimes, rate limiters, access checks, streaming replies, attachments, mirrors, and queue controls.
-- `src/slack-diagnostics.ts`: Slack readiness probes for token/transport config, auth, registered channel visibility, file-upload readiness, and rate-limit reporting.
-- `src/user-management.ts`, `src/user-management-types.ts`, `src/user-management-normalize.ts`, and `src/user-management-crypto.ts`: user/group/session/channel-access store with separated DTOs, payload normalization, password/token helpers, and public snapshots.
-- `src/config-metadata.ts`: shared setting metadata used by the WebUI settings page and generated `.env.example`.
-- `src/support-bundle.ts` and `src/zip-writer.ts`: redacted diagnostics bundle creation with a dependency-free ZIP writer.
-- `src/relay-queue-service.ts`, `src/relay-artifact-service.ts`, and `src/relay-external-activity-monitor.ts`: Web runtime queue operations, artifact preview/export/persistence, and external CLI activity mirroring.
-- `src/relay-runtime-types.ts`: shared Runtime/WebUI DTO types used by runtime, API contracts, and dashboard code.
-- `src/web-dashboard-http.ts`, `src/web-dashboard-pages.ts`, and `src/web-dashboard-runtime-routes.ts`: dashboard HTTP helpers, HTML shell rendering, and operational runtime API routes.
-- `src/webui/`: focused WebUI source assets for core runtime state/API helpers, overview rendering, live events, chat/session workflows, admin pages, and CSS sections.
-- `src/bot-preferences.ts`: per-context mirror, notification, quiet-hour, and voice preference persistence.
-- `src/telegram-rate-limit.ts`: centralized Telegram API send/edit/document rate limiting and retry-after tracking.
-- `src/persistence.ts`: atomic JSON/text writes with backup recovery.
-- `src/redaction.ts`: common secret redaction and custom redaction pattern support.
-- `src/workspace-policy.ts`: workspace allow/warn root evaluation.
-- `src/access-control.ts`: user/group permission definitions and command/callback/WebUI permission mapping.
-- `src/codex-session.ts`: Codex SDK service for new/resumed threads, streaming events, abort, model, reasoning, launch profiles, and handback.
-- `src/pi-session.ts`: Pi RPC service for JSONL RPC sessions, streaming events, abort, model, thinking, launch profiles, and handback.
-- `src/hermes-session.ts`: Hermes API Server service for streamed runs, stop, model, reasoning, launch profiles, attachments, and handback.
-- `src/openclaw-session.ts`: OpenClaw Gateway service for streamed runs, cancel, model, thinking, launch profiles, attachments, and handback.
-- `src/claude-code-session.ts`: Claude Agent SDK service for streamed runs, abort, model, effort, launch profiles, attachments, and handback.
-- `src/session-registry.ts`: per-chat/topic session registry and persisted context metadata.
-- `test/agent-adapter-contract.test.ts`: shared adapter contract coverage for descriptors, capability flags, reasoning options, launch profiles, and `AgentSessionService` method parity.
-- `src/session-format.ts`: compact Telegram rendering for session details, token usage, and limits.
-- `src/codex-state.ts`: reader for Codex `~/.codex/state_*.sqlite` thread, workspace, model, reasoning, sandbox, and approval metadata.
-- `src/pi-state.ts`: reader for Pi session JSONL files, activity timelines, diagnostics, and external busy detection.
-- `src/hermes-state.ts`: reader for Hermes `state.db` sessions, messages, token usage, activity timelines, diagnostics, and external busy detection.
-- `src/hermes-api.ts`: Hermes API Server client for health, capabilities, models, runs, events, approvals, and stop.
-- `src/openclaw-state.ts`: reader for OpenClaw session metadata, token usage, activity timelines, diagnostics, and external busy detection.
-- `src/openclaw-gateway.ts`: OpenClaw Gateway WebSocket RPC client for health, models, runs, stream events, and cancel.
-- `src/claude-code-state.ts`: reader for Claude Code transcript JSONL files, token usage, activity timelines, diagnostics, and external busy detection.
-- `src/attachments.ts`: inbound file staging and artifact output path construction.
-- `src/artifacts.ts`: generated artifact discovery, ZIP bundling, retention, and Telegram delivery filtering.
-- `src/voice.ts`: audio decoding and transcription backend selection.
-- `src/format.ts`: Telegram-safe HTML formatting and markdown conversion.
-- `src/error-messages.ts`: user-facing error translation.
+MIT. See [LICENSE](LICENSE).