better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/raft.md

@@ -0,0 +1,70 @@
+---
+sidebar_position: 19
+title: "Raft"
+description: "Connect Hermes Agent to Raft as an external agent via wake-channel bridge"
+---
+
+# Raft Setup
+
+Hermes connects to [Raft](https://raft.build) as an external agent through a local wake-channel bridge. The adapter starts a loopback HTTP endpoint that receives content-free wake hints from the bridge, then injects them into the Hermes gateway session pipeline. The agent reads and sends messages through the Raft CLI — the adapter never touches message bodies or delivery cursors.
+
+:::info Division of Labor
+- **The bridge** owns: wake-hint consumption, dedup, backoff, reconnection, at-least-once delivery, and proof logging.
+- **The Hermes adapter** owns: a localhost wake endpoint and injecting a short notice into the agent's context.
+- **The agent** owns: pulling messages (`raft message check`), replying (`raft message send`), and all other Raft interactions via the CLI.
+
+The adapter holds no Raft credentials — only a per-session shared token for localhost auth between the bridge and the endpoint.
+:::
+
+---
+
+## Prerequisites
+
+- A **Raft workspace** where you can create an External Agent
+- The **Raft CLI** installed and logged in to that External Agent profile
+- **aiohttp** — Python package (included in Hermes `[all]` extras)
+
+In Raft, open the Agents menu, create an External Agent, and follow the setup card to install the Raft CLI and log in the agent profile. Once the agent is created, Raft shows a Hermes setup guide with the environment variables and configuration needed to start the gateway.
+
+---
+
+## Setup
+
+Add to `~/.hermes/.env`:
+
+```bash
+RAFT_PROFILE=your-agent-profile
+```
+
+That's it — the adapter auto-enables when `RAFT_PROFILE` is set. It generates a per-session bridge token, picks an ephemeral port, and spawns the bridge child process automatically when the gateway starts.
+
+---
+
+## How It Works
+
+```
+Raft Server → Bridge (wake-hints SSE) → POST /wake → Hermes Adapter → Agent context
+Agent → raft message check → Raft Server (message bodies)
+Agent → raft message send → Raft Server (replies)
+```
+
+1. The Raft server sends wake hints to the bridge process via SSE.
+2. The bridge forwards each hint as a `POST /wake` to the adapter's loopback endpoint.
+3. The adapter validates the bridge token, verifies the payload is content-free, and injects a wake notice into the Hermes session.
+4. The agent sees the wake notice and uses the Raft CLI to read messages and reply.
+
+Wake payloads are **content-free by contract** — they carry metadata (event ID, message ID, timestamps) but never message bodies, channel names, or sender identities. The adapter rejects any payload containing content-shaped fields (`text`, `body`, `content`, `messages`, etc.).
+
+---
+
+## Bridge
+
+The adapter automatically spawns `raft agent bridge` as a child process, passing the endpoint URL and token. The bridge connects to the Raft server using the configured profile and begins forwarding wake hints. It is terminated when the gateway shuts down.
+
+---
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `RAFT_PROFILE` | Raft agent profile slug — auto-enables the adapter when set | _(required)_ |

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/relay.md

@@ -0,0 +1,212 @@
+---
+sidebar_position: 30
+title: "Hermes Relay"
+description: "Connect Hermes to messaging platforms through a relay connector that owns the platform credentials — enrollment, capabilities, config, and troubleshooting"
+---
+
+# Hermes Relay (Connector)
+
+:::warning Experimental
+Relay is **experimental**. The wire contract, auth scheme, and configuration
+may change without a deprecation cycle while the system is being validated.
+:::
+
+Hermes Relay is not a chat platform itself — it is a **connector system** that
+lets your gateway front one or more real messaging platforms (Discord,
+Telegram, Slack, WhatsApp, …) **without holding any platform credentials**. A
+separate service, the *connector*, owns the platform bot tokens and sockets.
+Your gateway dials **out** to the connector over a single authenticated
+WebSocket, receives a capability descriptor at handshake, and then exchanges
+normalized message events (inbound) and actions (outbound) over that socket.
+
+Key properties:
+
+- **Outbound-only networking.** The gateway never opens an inbound port.
+  Inbound messages ride back down the same WebSocket the gateway dialed, so
+  relay works behind NAT and on hosts with no public IP.
+- **No platform secrets on the gateway.** Bot tokens live on the connector.
+  Auth-gated platform media URLs are re-hosted connector-side, so platform
+  credentials never cross the wire.
+- **Platform-agnostic.** The gateway learns what the fronted platform can do
+  (message length limits, markdown dialect, edit/thread/streaming support, and
+  the exact set of supported operations) from the handshake descriptor, not
+  from hardcoded platform logic.
+
+The formal gateway ⇄ connector interface lives in the repository at
+`docs/relay-connector-contract.md`.
+
+## When to use Relay
+
+Relay is for deployments where a hosted or shared connector service manages
+the platform side — for example multi-tenant hosting where one shared bot
+fronts many users' agents, or setups where you don't want bot tokens on the
+gateway machine. If you run your own bots directly, use the native platform
+adapters ([Telegram](/user-guide/messaging/telegram),
+[Discord](/user-guide/messaging/discord), etc.) instead.
+
+## Enrollment
+
+A self-hosted gateway authenticates to the connector with a per-gateway
+secret. `hermes gateway enroll` redeems a **single-use enrollment token**
+(minted by the connector when your tenant's route is provisioned and delivered
+with your gateway config) for that secret:
+
+```bash
+hermes gateway enroll \
+  --token <enrollment-token> \
+  --connector-url wss://connector.example.com/relay
+```
+
+What it does:
+
+1. Resolves a fresh Nous Portal access token from your existing login
+   (`~/.hermes/auth.json`) — this proves which Nous org (tenant) you own. If
+   `gateway.idp.token_url` is configured, your own IdP is used instead (the
+   air-gapped / self-hosted-IdP path, no Nous Portal involved): with
+   `client_id`/`client_secret` configured it performs a generic OAuth2
+   client-credentials grant; with neither configured the URL is treated as an
+   ambient token endpoint (plain GET whose response body is the token — the
+   metadata-server pattern, e.g. Domino's `$DOMINO_API_PROXY/access-token`).
+   Configuring only one of the two credentials is an error.
+2. POSTs the enrollment token and a gateway id to the connector's
+   `/relay/enroll` endpoint over TLS.
+3. The connector verifies the token (signature, single-use, tenant match),
+   mints a per-gateway secret plus a per-tenant delivery key, and returns them
+   once.
+4. Persists the credentials into `~/.hermes/.env`:
+   `GATEWAY_RELAY_ID`, `GATEWAY_RELAY_SECRET`, `GATEWAY_RELAY_DELIVERY_KEY`
+   (plus `GATEWAY_RELAY_URL` / `GATEWAY_RELAY_WAKE_URL` when supplied).
+
+Restart the gateway afterwards to pick up the new environment.
+
+Flags:
+
+| Flag | Description |
+|------|-------------|
+| `--token` | The single-use enrollment token. Also settable via `GATEWAY_RELAY_ENROLL_TOKEN`. |
+| `--connector-url` | Connector base or relay URL (`wss://…/relay` or `https://…`). Also settable via `GATEWAY_RELAY_URL` or `gateway.relay_url` in `config.yaml`. |
+| `--gateway-id` | Stable id for this gateway instance (used for kill-switch granularity). Defaults to `gw-<hostname>`. |
+| `--wake-url` | Optional reachable URL the connector pokes (payload-free GET) to wake this gateway when buffered work arrives while it is idle. Persisted as `GATEWAY_RELAY_WAKE_URL`. Without it the gateway still drains buffered messages whenever it next reconnects. |
+
+:::note Managed installs
+`hermes gateway enroll` refuses to run in managed/hosted installs — there the
+hosting platform provisions the relay secret directly into the container
+environment.
+:::
+
+## Configuration
+
+Relay activates when a connector relay URL is configured. To keep a profile off
+the relay even when the deployment injects a URL, disable the platform in
+`config.yaml`:
+
+```yaml
+platforms:
+  relay:
+    enabled: false
+```
+
+- **Explicit disable wins.** With `enabled: false` the gateway does not resolve
+  an identity token, provision or rewrite `GATEWAY_RELAY_*` credentials, register
+  the relay adapter or send the relevance policy — even with `gateway.relay_url`
+  or `GATEWAY_RELAY_URL` set. Native messaging adapters connect as if no relay
+  URL were present, and cron delivery treats no platform as relay-fronted.
+- **Omitting `enabled` keeps URL-based activation.** `enabled: true` still needs
+  a connector URL. A `gateway.json` `enabled: false` is advisory, as for every
+  other platform; put the opt-out in `config.yaml` (user or managed).
+
+The verdict comes from the same files and merge the gateway loader uses (top-level
+or `gateway.platforms` block, managed overlay) and is applied at activation time.
+Restart the gateway after changing it; an open relay socket is not torn down.
+`hermes gateway enroll` remains available while runtime relay is disabled.
+
+| Setting | Where | Meaning |
+|---------|-------|---------|
+| `GATEWAY_RELAY_URL` | env (`~/.hermes/.env`) | Connector relay WebSocket URL. Enables relay unless explicitly disabled in platform configuration. |
+| `gateway.relay_url` | `config.yaml` | Same as above, config-file form (env takes precedence). |
+| `GATEWAY_RELAY_ID` | env | This gateway instance's id (written by `enroll`). |
+| `GATEWAY_RELAY_SECRET` | env | Per-gateway secret authenticating the WebSocket upgrade (written by `enroll`). |
+| `GATEWAY_RELAY_DELIVERY_KEY` | env | Per-tenant delivery key (written by `enroll`; retained for forward-compat). |
+| `GATEWAY_RELAY_WAKE_URL` / `gateway.relay_wake_url` | env / `config.yaml` | Optional wake-poke target for idle/suspended gateways. |
+| `GATEWAY_RELAY_PLATFORMS` | env | Comma-separated list of platforms this gateway fronts over one connection (e.g. `discord,telegram`). Usually stamped by the deployment/orchestrator. |
+| `GATEWAY_RELAY_BOT_IDS` | env | JSON map of per-platform bot identities, e.g. `{"discord": {"botId": "…"}}`. Paired with `GATEWAY_RELAY_PLATFORMS`. |
+| `gateway.idp.token_url` | `config.yaml` | When set, enrollment/provisioning authenticates against your own IdP instead of Nous Portal: OAuth2 client-credentials when `gateway.idp.client_id`/`client_secret` are also set; otherwise an ambient token endpoint (plain GET returning the token, raw or `{"access_token": …}`). |
+
+## Supported capabilities
+
+What actually works over a relay connection is negotiated at handshake: the
+connector advertises a `supported_ops` list, and the gateway only uses an
+operation the connector explicitly advertises (older connectors fall back to a
+legacy `send`/`edit`/`typing`/`follow_up` set). Per-platform capability flags
+(edit-based streaming, threads, draft streaming, markdown dialect, message
+length limit) also come from the handshake descriptor. Subject to that
+negotiation, the relay supports:
+
+- **Text messages and streaming** — sends, replies, and progressive
+  edit-based streaming when the fronted platform supports message editing;
+  otherwise output degrades to one message per segment.
+- **Media, both directions** — outbound images, voice, audio, video, and
+  documents are uploaded to the connector (or referenced by public URL) and
+  delivered through each platform's native upload lane, with captions.
+  Inbound attachments are localized to files for the agent; auth-gated
+  platform URLs are re-hosted connector-side so platform credentials never
+  reach the gateway. Media re-hosts are capped at 25 MB and expire (~1 hour).
+- **Native interactive prompts** — exec approvals, confirmations, and clarify
+  questions render with **native platform controls** (Discord buttons,
+  Telegram inline keyboards, Slack Block Kit actions, WhatsApp button/list
+  messages) instead of numbered-text fallbacks. Button presses come back as
+  authenticated prompt responses from the actual clicking user, so the
+  gateway's authorization gates apply exactly as to a typed reply. Prompt
+  expiry is enforced gateway-side.
+- **Reaction ack lifecycle** — the bot's processing-status reactions
+  (👀 while working, ✅/❌ on completion) work over the relay. Reactions are
+  best-effort: a failed reaction never fails a turn.
+- **Thread lifecycle** — creating handoff threads and renaming threads
+  (including LLM-titled semantic renames) through platform-abstract
+  `thread_create` / `thread_rename` operations, with a no-clobber guard so a
+  human's manual rename wins. Availability depends on the platform (e.g.
+  Slack threads can't be renamed; WhatsApp has no threads).
+- **Typing indicators** — the gateway egresses typing (and stop-typing) through
+  the connector while processing.
+- **Chat metadata** — `get_chat_info` lookups are proxied to the connector
+  when advertised.
+- **Buffered delivery and wake** — when the gateway goes idle or disconnects,
+  the connector buffers inbound messages durably and replays them in order on
+  reconnect (ack-gated, no loss or duplication). If a wake URL is registered,
+  the connector pokes it when buffered work arrives for a sleeping gateway.
+
+Multi-platform fronting is supported: one gateway can front several platforms
+(e.g. Discord *and* Telegram) over a single relay connection, with each
+outbound message tagged for the platform it targets.
+
+## Troubleshooting
+
+**Enrollment fails with 401** — the connector could not verify your identity
+token. Re-login with `hermes auth add nous` (or `hermes setup`) and retry.
+
+**Enrollment fails with 403** — the enrollment token is invalid, expired,
+already used, or belongs to a different tenant. Enrollment tokens are
+single-use; request a fresh one from whoever provisioned your tenant route.
+
+**"Could not reach the connector"** — check the connector URL. You can paste
+either the `wss://…/relay` dial URL or the `https://…` base URL; the CLI maps
+between them automatically.
+
+**`enroll` refuses to run** — you are in a managed/hosted install, where the
+relay secret is provisioned by the hosting platform. Self-enrollment is only
+for self-hosted gateways.
+
+**Relay platform shows as disabled after it previously worked** — a WebSocket
+close with code 4401 *after* a successful handshake means the gateway's secret
+was revoked (e.g. the instance was deprovisioned). The gateway deliberately
+stops reconnecting and reports relay as disabled rather than retrying. A 4401
+*before* any successful handshake is treated as a transient
+not-yet-provisioned race and retried normally.
+
+**Nothing changed after enrolling** — the gateway reads `GATEWAY_RELAY_*` at
+startup. Restart it (`hermes gateway restart`).
+
+**A feature (buttons, media, threads…) silently degrades to plain text** — the
+connector for your platform did not advertise that operation in its handshake
+`supported_ops`. The gateway intentionally falls back to the text behavior
+rather than sending an op the connector can't handle.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/messaging/signal.md

@@ -0,0 +1,262 @@
+---
+sidebar_position: 6
+title: "Signal"
+description: "Set up Hermes Agent as a Signal messenger bot via signal-cli daemon"
+---
+
+# Signal Setup
+
+Hermes connects to Signal through the [signal-cli](https://github.com/AsamK/signal-cli) daemon running in HTTP mode. The adapter streams messages in real-time via SSE (Server-Sent Events) and sends responses via JSON-RPC.
+
+Signal is the most privacy-focused mainstream messenger — end-to-end encrypted by default, open-source protocol, minimal metadata collection. This makes it ideal for security-sensitive agent workflows.
+
+:::info No New Python Dependencies
+The Signal adapter uses `httpx` (already a core Hermes dependency) for all communication. No additional Python packages are required. You just need signal-cli installed externally.
+:::
+
+---
+
+## Prerequisites
+
+- **signal-cli** — Java-based Signal client ([GitHub](https://github.com/AsamK/signal-cli))
+- **Java 17+** runtime — required by signal-cli
+- **A phone number** with Signal installed (for linking as a secondary device)
+
+### Installing signal-cli
+
+```bash
+# macOS
+brew install signal-cli
+
+# Linux (download latest release)
+VERSION=$(curl -Ls -o /dev/null -w %{url_effective} \
+  https://github.com/AsamK/signal-cli/releases/latest | sed 's/^.*\/v//')
+curl -L -O "https://github.com/AsamK/signal-cli/releases/download/v${VERSION}/signal-cli-${VERSION}.tar.gz"
+sudo tar xf "signal-cli-${VERSION}.tar.gz" -C /opt
+sudo ln -sf "/opt/signal-cli-${VERSION}/bin/signal-cli" /usr/local/bin/
+```
+
+:::caution
+signal-cli is **not** in apt or snap repositories. The Linux install above downloads directly from [GitHub releases](https://github.com/AsamK/signal-cli/releases).
+:::
+
+---
+
+## Step 1: Link Your Signal Account
+
+Signal-cli works as a **linked device** — like WhatsApp Web, but for Signal. Your phone stays the primary device.
+
+```bash
+# Generate a linking URI (displays a QR code or link)
+signal-cli link -n "HermesAgent"
+```
+
+1. Open **Signal** on your phone
+2. Go to **Settings → Linked Devices**
+3. Tap **Link New Device**
+4. Scan the QR code or enter the URI
+
+---
+
+## Step 2: Start the signal-cli Daemon
+
+```bash
+# Replace +1234567890 with your Signal phone number (E.164 format)
+signal-cli --account +1234567890 daemon --http 127.0.0.1:8080
+```
+
+:::tip
+Keep this running in the background. You can use `systemd`, `tmux`, `screen`, or run it as a service.
+:::
+
+Verify it's running:
+
+```bash
+curl http://127.0.0.1:8080/api/v1/check
+# Should return: {"versions":{"signal-cli":...}}
+```
+
+---
+
+## Step 3: Configure Hermes
+
+The easiest way:
+
+```bash
+hermes gateway setup
+```
+
+Select **Signal** from the platform menu. The wizard will:
+
+1. Check if signal-cli is installed
+2. Prompt for the HTTP URL (default: `http://127.0.0.1:8080`)
+3. Test connectivity to the daemon
+4. Ask for your account phone number
+5. Configure allowed users and access policies
+
+### Manual Configuration
+
+Add to `~/.hermes/.env`:
+
+```bash
+# Required
+SIGNAL_HTTP_URL=http://127.0.0.1:8080
+SIGNAL_ACCOUNT=+1234567890
+
+# Security (recommended)
+SIGNAL_ALLOWED_USERS=+1234567890,+0987654321    # Comma-separated E.164 numbers or UUIDs
+
+# Optional
+SIGNAL_GROUP_ALLOWED_USERS=groupId1,groupId2     # Enable groups (omit to disable, * for all)
+SIGNAL_HOME_CHANNEL=+1234567890                  # Default delivery target for cron jobs
+```
+
+Then start the gateway:
+
+```bash
+hermes gateway              # Foreground
+hermes gateway install      # Install as a user service
+sudo hermes gateway install --system   # Linux only: boot-time system service
+```
+
+---
+
+## Access Control
+
+### DM Access
+
+DM access follows the same pattern as all other Hermes platforms:
+
+1. **`SIGNAL_ALLOWED_USERS` set** → only those users can message
+2. **No allowlist set** → unknown users get a DM pairing code (approve via `hermes pairing approve signal CODE`)
+3. **`SIGNAL_ALLOW_ALL_USERS=true`** → anyone can message (use with caution)
+
+### Group Access
+
+Group access is controlled by the `SIGNAL_GROUP_ALLOWED_USERS` env var:
+
+| Configuration | Behavior |
+|---------------|----------|
+| Not set (default) | All group messages are ignored. The bot only responds to DMs. |
+| Set with group IDs | Only listed groups are monitored (e.g., `groupId1,groupId2`). |
+| Set to `*` | The bot responds in any group it's a member of. |
+
+---
+
+## Features
+
+### Attachments
+
+The adapter supports sending and receiving media in both directions.
+
+**Incoming** (user → agent):
+
+- **Images** — PNG, JPEG, GIF, WebP (auto-detected via magic bytes)
+- **Audio** — MP3, OGG, WAV, M4A (voice messages transcribed if Whisper is configured)
+- **Documents** — PDF, ZIP, and other file types
+
+**Outgoing** (agent → user):
+
+The agent can send media files via `MEDIA:` tags in responses. The following delivery methods are supported:
+
+- **Images** — `send_multiple_images` and `send_image_file` send PNG, JPEG, GIF, WebP as native Signal attachments
+- **Voice** — `send_voice` sends audio files (OGG, MP3, WAV, M4A, AAC) as attachments
+- **Video** — `send_video` sends MP4 video files
+- **Documents** — `send_document` sends any file type (PDF, ZIP, etc.)
+
+All outgoing media goes through Signal's standard attachment API. Unlike some platforms, Signal does not distinguish between voice messages and file attachments at the protocol level.
+
+Attachment size limit: **100 MB** (both directions).
+:::warning
+**Signal servers will rate-limit attachment uploads**, the adapter uses a scheduler for multiple image sending that batches images in groups of 32 and throttles uploads to match the Signal server policy.
+:::
+
+### Native Formatting, Reply Quotes, and Reactions
+
+Signal messages render with **native formatting** instead of literal markdown characters. The adapter converts markdown (`**bold**`, `*italic*`, `` `code` ``, `~~strike~~`, `||spoiler||`, headings) into Signal `bodyRanges` so the text shows up with real styling on the recipient's client rather than as visible `**` / `` ` `` characters.
+
+**Reply quotes.** When Hermes replies to a specific message, it now posts a native reply that quotes the original — same UI affordance Signal users see when they use "Reply" themselves. This is automatic for replies generated in response to an inbound message.
+
+**Reactions.** The agent can react to messages via the standard reaction API; reactions surface in Signal as emoji reactions on the referenced message rather than as extra text.
+
+None of this requires additional config — it ships on by default in recent signal-cli builds. If your `signal-cli` version is too old, Hermes falls back to plaintext delivery and logs a one-time warning.
+
+### Long Messages
+
+Signal caps a single message at **8,000 characters**. Hermes splits longer responses into numbered chunks (`(1/3)`, `(2/3)`, …) automatically instead of truncating them. This applies to every delivery path — live conversation replies, cron job deliveries, `hermes send`, and MCP `send_message` calls — and native formatting (bold, italic, code, spoilers) is preserved across chunk boundaries.
+
+### Typing Indicators
+
+The bot sends typing indicators while processing messages, refreshing every 8 seconds.
+
+### Tool Progress Display
+
+Signal does not support editing already-sent messages. Hermes therefore suppresses gateway tool-progress bubbles on Signal, even when `/verbose` is enabled and saves a non-`off` mode for the platform.
+
+You can still see tool activity in the CLI, and final Signal replies can include normal assistant output. If you need live per-tool progress in chat, use a messaging platform with message editing support.
+
+### Phone Number Redaction
+
+All phone numbers are automatically redacted in logs:
+- `+15551234567` → `+155****4567`
+- This applies to both Hermes gateway logs and the global redaction system
+
+### Note to Self (Single-Number Setup)
+
+If you run signal-cli as a **linked secondary device** on your own phone number (rather than a separate bot number), you can interact with Hermes through Signal's "Note to Self" feature.
+
+Just send a message to yourself from your phone — signal-cli picks it up and Hermes responds in the same conversation.
+
+**How it works:**
+- "Note to Self" messages arrive as `syncMessage.sentMessage` envelopes
+- The adapter detects when these are addressed to the bot's own account and processes them as regular inbound messages
+- Echo-back protection (sent-timestamp tracking) prevents infinite loops — the bot's own replies are filtered out automatically
+
+**No extra configuration needed.** This works automatically as long as `SIGNAL_ACCOUNT` matches your phone number.
+
+### Health Monitoring
+
+The adapter monitors the SSE connection and automatically reconnects if:
+- The connection drops (with exponential backoff: 2s → 60s)
+- No activity is detected for 120 seconds (pings signal-cli to verify)
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| **"Cannot reach signal-cli"** during setup | Ensure signal-cli daemon is running: `signal-cli --account +YOUR_NUMBER daemon --http 127.0.0.1:8080` |
+| **Messages not received** | Check that `SIGNAL_ALLOWED_USERS` includes the sender's number in E.164 format (with `+` prefix) |
+| **"signal-cli not found on PATH"** | Install signal-cli and ensure it's in your PATH, or use Docker |
+| **Connection keeps dropping** | Check signal-cli logs for errors. Ensure Java 17+ is installed. |
+| **Group messages ignored** | Configure `SIGNAL_GROUP_ALLOWED_USERS` with specific group IDs, or `*` to allow all groups. |
+| **Bot responds to no one** | Configure `SIGNAL_ALLOWED_USERS`, use DM pairing, or explicitly allow all users through gateway policy if you want broader access. |
+| **Duplicate messages** | Ensure only one signal-cli instance is listening on your phone number |
+
+---
+
+## Security
+
+:::warning
+**Always configure access controls.** The bot has terminal access by default. Without `SIGNAL_ALLOWED_USERS` or DM pairing, the gateway denies all incoming messages as a safety measure.
+:::
+
+- Phone numbers are redacted in all log output
+- Use DM pairing or explicit allowlists for safe onboarding of new users
+- Keep groups disabled unless you specifically need group support, or allowlist only the groups you trust
+- Signal's end-to-end encryption protects message content in transit
+- The signal-cli session data in `~/.local/share/signal-cli/` contains account credentials — protect it like a password
+
+---
+
+## Environment Variables Reference
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SIGNAL_HTTP_URL` | Yes | — | signal-cli HTTP endpoint |
+| `SIGNAL_ACCOUNT` | Yes | — | Bot phone number (E.164) |
+| `SIGNAL_ALLOWED_USERS` | No | — | Comma-separated phone numbers/UUIDs |
+| `SIGNAL_GROUP_ALLOWED_USERS` | No | — | Group IDs to monitor, or `*` for all (omit to disable groups) |
+| `SIGNAL_ALLOW_ALL_USERS` | No | `false` | Allow any user to interact (skip allowlist) |
+| `SIGNAL_HOME_CHANNEL` | No | — | Default delivery target for cron jobs |