From 57e1362344ad8707fa5049230b6b45eee34b77be Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 1 Jan 2026 15:37:45 +0000
Subject: [PATCH] docs(signal): explain bot-number setup

---
 CHANGELOG.md   |  1 +
 docs/signal.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 50 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6a460df6a..3bd32a12d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,7 @@
 - Docs/agent tools: clarify that browser `wait` should be avoided by default and used only in exceptional cases.
 - Browser tools: `upload` supports auto-click refs, direct `inputRef`/`element` file inputs, and emits input/change after `setFiles` so JS-heavy sites pick up attachments.
 - Signal: fix daemon startup race (wait for `/api/v1/check`) and normalize JSON-RPC `version` probe parsing.
+- Docs/Signal: clarify bot-number vs personal-account setup (self-chat loop protection) and add a quickstart config snippet.
 - macOS: Voice Wake now fully tears down the Speech pipeline when disabled (cancel pending restarts, drop stale callbacks) to avoid high CPU in the background.
 - macOS menu: add a Talk Mode action alongside the Open Dashboard/Chat/Canvas entries.
 - macOS Debug: hide “Restart Gateway” when the app won’t start a local gateway (remote mode / attach-only).
diff --git a/docs/signal.md b/docs/signal.md
index 243881667..cc6898dbe 100644
--- a/docs/signal.md
+++ b/docs/signal.md
@@ -1,3 +1,9 @@
+---
+summary: "Signal support via signal-cli (JSON-RPC + SSE), setup, and number model"
+read_when:
+  - Setting up Signal support
+  - Debugging Signal send/receive
+---
 # Signal (signal-cli)
 
 Status: external CLI integration only. No libsignal embedding.
@@ -6,11 +12,49 @@ Status: external CLI integration only. No libsignal embedding.
 - Signal OSS stack is GPL/AGPL; not compatible with Clawdis MIT if bundled.
 - signal-cli is unofficial; must stay up to date (Signal server churn).
 
+## The “number model” (important)
+- Clawdis is a **device** connected via `signal-cli`.
+- If you run `signal-cli` on **your personal Signal account**, Clawdis will **not** respond to messages sent from that same account (loop protection: ignore sender==account).
+  - Result: you **cannot** “text yourself” to chat with the AI.
+- For “I text her, she texts me back” you want a **separate Signal account/number for the bot**:
+  - Bot number runs `signal-cli` (linked device)
+  - Your personal number is in `signal.allowFrom`
+  - You DM the bot number; Clawdis replies back to you
+
+You can still run Clawdis on your own Signal account if your goal is “respond to other people as me”, but not for self-chat.
+
 ## Model
 - Run `signal-cli` as separate process (user-installed).
 - Prefer `daemon --http=127.0.0.1:PORT` for JSON-RPC + SSE.
 - Alternative: `jsonRpc` mode over stdin/stdout.
 
+## Quickstart (bot number)
+1) Install `signal-cli` (keep Java installed).
+2) Link the bot account as a device:
+   - Run: `signal-cli link -n "Clawdis"`
+   - Scan QR in Signal: Settings → Linked Devices → Link New Device
+   - Verify: `signal-cli listAccounts` includes the bot E.164
+3) Configure `~/.clawdis/clawdis.json`:
+```json5
+{
+  signal: {
+    enabled: true,
+    account: "+15551234567", // bot number (recommended)
+    cliPath: "signal-cli",
+    autoStart: true,
+    httpHost: "127.0.0.1",
+    httpPort: 8080,
+
+    // Who is allowed to talk to the bot
+    allowFrom: ["+15557654321"] // your personal number (or "*")
+  }
+}
+```
+4) Run gateway; sanity probe:
+   - `clawdis gateway call providers.status --params '{"probe":true}'`
+   - Expect `signal.probe.ok=true` and `signal.probe.version`.
+5) DM the bot number from your phone; Clawdis replies.
+
 ## Endpoints (daemon --http)
 - `POST /api/v1/rpc` JSON-RPC request (single or batch).
 - `GET /api/v1/events` SSE stream of `receive` notifications.
@@ -27,6 +71,11 @@ Status: external CLI integration only. No libsignal embedding.
 - `subscribeReceive` / `unsubscribeReceive` (if manual receive).
 - `startLink` / `finishLink` (optional device link flow).
 
+## Addressing (send targets)
+- Direct: `signal:+15551234567` (or plain `+15551234567`)
+- Groups: `group:<groupId>`
+- Usernames: `username:<name>` / `u:<name>`
+
 ## Process plan (Clawdis adapter)
 1) Detect `signal-cli` binary; refuse if missing.
 2) Launch daemon (HTTP preferred), store PID.