fix: document WhatsApp read receipts toggle (#882) (thanks @chrisrodz)

- Move CronPayload enum to top level (was incorrectly nested)
- Fix all tabs to spaces
- Align case statements consistently

.detect-secrets.cfg

@@ -0,0 +1,26 @@
+# detect-secrets exclusion patterns (regex)
+#
+# Note: detect-secrets does not read this file by default. If you want these
+# applied, wire them into your scan command (e.g. translate to --exclude-files
+# / --exclude-lines) or into a baseline's filters_used.
+
+[exclude-files]
+# pnpm lockfiles contain lots of high-entropy package integrity blobs.
+pattern = (^|/)pnpm-lock\.yaml$
+
+[exclude-lines]
+# Fastlane checks for private key marker; not a real key.
+pattern = key_content\.include\?\("BEGIN PRIVATE KEY"\)
+# UI label string for Anthropic auth mode.
+pattern = case \.apiKeyEnv: "API key \(env var\)"
+# CodingKeys mapping uses apiKey literal.
+pattern = case apikey = "apiKey"
+# Schema labels referencing password fields (not actual secrets).
+pattern = "gateway\.remote\.password"
+pattern = "gateway\.auth\.password"
+# Schema label for talk API key (label text only).
+pattern = "talk\.apiKey"
+# checking for typeof is not something we care about.
+pattern = === "string"
+# specific optional-chaining password check that didn't match the line above.
+pattern = typeof remote\?\.password === "string"

.github/workflows/ci.yml

@@ -74,9 +74,9 @@ jobs:
           - runtime: node
             task: protocol
             command: pnpm protocol:check
-          - runtime: bun
-            task: lint
-            command: bunx biome check src
+          - runtime: node
+            task: format
+            command: pnpm format
           - runtime: bun
             task: test
             command: bunx vitest run
@@ -141,6 +141,31 @@ jobs:
       - name: Run ${{ matrix.task }} (${{ matrix.runtime }})
         run: ${{ matrix.command }}
 
+  secrets:
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install detect-secrets
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install detect-secrets==1.5.0
+
+      - name: Detect secrets
+        run: |
+          if ! detect-secrets scan --baseline .secrets.baseline; then
+            echo "::error::Secret scanning failed. See docs/gateway/security.md#secret-scanning-detect-secrets"
+            exit 1
+          fi
+
   checks-windows:
     runs-on: blacksmith-4vcpu-windows-2025
     defaults:

.github/workflows/install-smoke.yml

@@ -29,4 +29,5 @@ jobs:
           CLAWDBOT_INSTALL_CLI_URL: https://clawd.bot/install-cli.sh
           CLAWDBOT_NO_ONBOARD: "1"
           CLAWDBOT_INSTALL_SMOKE_SKIP_CLI: "1"
+          CLAWDBOT_INSTALL_SMOKE_PREVIOUS: "2026.1.11-4"
         run: pnpm test:install:smoke

.oxfmtrc.jsonc

@@ -0,0 +1,5 @@
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "indentWidth": 2,
+  "printWidth": 100
+}

.oxlintrc.jsonc

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://json.schemastore.org/oxlintrc",
+  "extends": ["recommended"]
+}

.secrets.baseline

@@ -0,0 +1,518 @@
+{
+  "version": "1.5.0",
+  "plugins_used": [
+    {
+      "name": "ArtifactoryDetector"
+    },
+    {
+      "name": "AWSKeyDetector"
+    },
+    {
+      "name": "AzureStorageKeyDetector"
+    },
+    {
+      "name": "Base64HighEntropyString",
+      "limit": 4.5
+    },
+    {
+      "name": "BasicAuthDetector"
+    },
+    {
+      "name": "CloudantDetector"
+    },
+    {
+      "name": "DiscordBotTokenDetector"
+    },
+    {
+      "name": "GitHubTokenDetector"
+    },
+    {
+      "name": "GitLabTokenDetector"
+    },
+    {
+      "name": "HexHighEntropyString",
+      "limit": 3.0
+    },
+    {
+      "name": "IbmCloudIamDetector"
+    },
+    {
+      "name": "IbmCosHmacDetector"
+    },
+    {
+      "name": "IPPublicDetector"
+    },
+    {
+      "name": "JwtTokenDetector"
+    },
+    {
+      "name": "KeywordDetector",
+      "keyword_exclude": ""
+    },
+    {
+      "name": "MailchimpDetector"
+    },
+    {
+      "name": "NpmDetector"
+    },
+    {
+      "name": "OpenAIDetector"
+    },
+    {
+      "name": "PrivateKeyDetector"
+    },
+    {
+      "name": "PypiTokenDetector"
+    },
+    {
+      "name": "SendGridDetector"
+    },
+    {
+      "name": "SlackDetector"
+    },
+    {
+      "name": "SoftlayerDetector"
+    },
+    {
+      "name": "SquareOAuthDetector"
+    },
+    {
+      "name": "StripeDetector"
+    },
+    {
+      "name": "TelegramBotTokenDetector"
+    },
+    {
+      "name": "TwilioKeyDetector"
+    }
+  ],
+  "filters_used": [
+    {
+      "path": "detect_secrets.filters.allowlist.is_line_allowlisted"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_baseline_file",
+      "filename": ".secrets.baseline"
+    },
+    {
+      "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
+      "min_level": 2
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_indirect_reference"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_likely_id_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_lock_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_not_alphanumeric_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_potential_uuid"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_prefixed_with_dollar_sign"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_sequential_string"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_swagger_file"
+    },
+    {
+      "path": "detect_secrets.filters.heuristic.is_templated_secret"
+    },
+    {
+      "path": "detect_secrets.filters.regex.should_exclude_file",
+      "pattern": [
+        "(^|/)pnpm-lock\\.yaml$"
+      ]
+    },
+    {
+      "path": "detect_secrets.filters.regex.should_exclude_line",
+      "pattern": [
+        "key_content\\.include\\?\\(\"BEGIN PRIVATE KEY\"\\)",
+        "case \\.apiKeyEnv: \"API key \\(env var\\)\"",
+        "case apikey = \"apiKey\"",
+        "\"gateway\\.remote\\.password\"",
+        "\"gateway\\.auth\\.password\"",
+        "\"talk\\.apiKey\"",
+        "=== \"string\"",
+        "typeof remote\\?\\.password === \"string\""
+      ]
+    }
+  ],
+  "results": {
+    ".env.example": [
+      {
+        "type": "Twilio API Key",
+        "filename": ".env.example",
+        "hashed_secret": "3c7206eff845bc69cf12d904d0f95f9aec15535e",
+        "is_verified": false,
+        "line_number": 2
+      }
+    ],
+    "appcast.xml": [
+      {
+        "type": "Base64 High Entropy String",
+        "filename": "appcast.xml",
+        "hashed_secret": "1b1c2b73eca84e441a823c37a06c71c9fadcfe24",
+        "is_verified": false,
+        "line_number": 19
+      },
+      {
+        "type": "Base64 High Entropy String",
+        "filename": "appcast.xml",
+        "hashed_secret": "5c47736fee5151b26b3bb61bb38955da0e8937c6",
+        "is_verified": false,
+        "line_number": 35
+      },
+      {
+        "type": "Base64 High Entropy String",
+        "filename": "appcast.xml",
+        "hashed_secret": "bbbca47179268f154c63affa0ca441c6e49e650f",
+        "is_verified": false,
+        "line_number": 52
+      }
+    ],
+    "apps/macos/Tests/ClawdbotIPCTests/AnthropicAuthResolverTests.swift": [
+      {
+        "type": "Secret Keyword",
+        "filename": "apps/macos/Tests/ClawdbotIPCTests/AnthropicAuthResolverTests.swift",
+        "hashed_secret": "e761624445731fcb8b15da94343c6b92e507d190",
+        "is_verified": false,
+        "line_number": 26
+      },
+      {
+        "type": "Secret Keyword",
+        "filename": "apps/macos/Tests/ClawdbotIPCTests/AnthropicAuthResolverTests.swift",
+        "hashed_secret": "a23c8630c8a5fbaa21f095e0269c135c20d21689",
+        "is_verified": false,
+        "line_number": 42
+      }
+    ],
+    "apps/macos/Tests/ClawdbotIPCTests/ConnectionsSettingsSmokeTests.swift": [
+      {
+        "type": "Secret Keyword",
+        "filename": "apps/macos/Tests/ClawdbotIPCTests/ConnectionsSettingsSmokeTests.swift",
+        "hashed_secret": "e5e9fa1ba31ecd1ae84f75caaa474f3a663f05f4",
+        "is_verified": false,
+        "line_number": 83
+      }
+    ],
+    "apps/macos/Tests/ClawdbotIPCTests/TailscaleIntegrationSectionTests.swift": [
+      {
+        "type": "Secret Keyword",
+        "filename": "apps/macos/Tests/ClawdbotIPCTests/TailscaleIntegrationSectionTests.swift",
+        "hashed_secret": "e5e9fa1ba31ecd1ae84f75caaa474f3a663f05f4",
+        "is_verified": false,
+        "line_number": 27
+      }
+    ],
+    "docs/configuration.md": [
+      {
+        "type": "Secret Keyword",
+        "filename": "docs/configuration.md",
+        "hashed_secret": "e5e9fa1ba31ecd1ae84f75caaa474f3a663f05f4",
+        "is_verified": false,
+        "line_number": 268
+      },
+      {
+        "type": "Secret Keyword",
+        "filename": "docs/configuration.md",
+        "hashed_secret": "1188d5a8ed7edcff5144a9472af960243eacf12e",
+        "is_verified": false,
+        "line_number": 465
+      },
+      {
+        "type": "Secret Keyword",
+        "filename": "docs/configuration.md",
+        "hashed_secret": "22af290a1a3d5e941193a41a3d3a9e4ca8da5e27",
+        "is_verified": false,
+        "line_number": 718
+      },
+      {
+        "type": "Secret Keyword",
+        "filename": "docs/configuration.md",
+        "hashed_secret": "16c249e04e2be318050cb883c40137361c0c7209",
+        "is_verified": false,
+        "line_number": 760
+      },
+      {
+        "type": "Secret Keyword",
+        "filename": "docs/configuration.md",
+        "hashed_secret": "c1e6ee547fd492df1441ac492e8bb294974712bd",
+        "is_verified": false,
+        "line_number": 859
+      },
+      {
+        "type": "Secret Keyword",
+        "filename": "docs/configuration.md",
+        "hashed_secret": "45d676e7c6ab44cf4b8fa366ef2d8fccd3e6d6e6",
+        "is_verified": false,
+        "line_number": 982
+      }
+    ],
+    "docs/faq.md": [
+      {
+        "type": "Secret Keyword",
+        "filename": "docs/faq.md",
+        "hashed_secret": "a219d7693c25cd2d93313512e200ff3eb374d281",
+        "is_verified": false,
+        "line_number": 593
+      },
+      {
+        "type": "Secret Keyword",
+        "filename": "docs/faq.md",
+        "hashed_secret": "ec3810e10fb78db55ce38b9c18d1c3eb1db739e0",
+        "is_verified": false,
+        "line_number": 650
+      }
+    ],
+    "docs/skills-config.md": [
+      {
+        "type": "Secret Keyword",
+        "filename": "docs/skills-config.md",
+        "hashed_secret": "c1e6ee547fd492df1441ac492e8bb294974712bd",
+        "is_verified": false,
+        "line_number": 28
+      }
+    ],
+    "docs/skills.md": [
+      {
+        "type": "Secret Keyword",
+        "filename": "docs/skills.md",
+        "hashed_secret": "c1e6ee547fd492df1441ac492e8bb294974712bd",
+        "is_verified": false,
+        "line_number": 97
+      }
+    ],
+    "docs/tailscale.md": [
+      {
+        "type": "Secret Keyword",
+        "filename": "docs/tailscale.md",
+        "hashed_secret": "9cb0dc5383312aa15b9dc6745645bde18ff5ade9",
+        "is_verified": false,
+        "line_number": 52
+      }
+    ],
+    "docs/talk.md": [
+      {
+        "type": "Secret Keyword",
+        "filename": "docs/talk.md",
+        "hashed_secret": "1188d5a8ed7edcff5144a9472af960243eacf12e",
+        "is_verified": false,
+        "line_number": 50
+      }
+    ],
+    "docs/telegram.md": [
+      {
+        "type": "Secret Keyword",
+        "filename": "docs/telegram.md",
+        "hashed_secret": "e9fe51f94eadabf54dbf2fbbd57188b9abee436e",
+        "is_verified": false,
+        "line_number": 57
+      }
+    ],
+    "skills/local-places/SERVER_README.md": [
+      {
+        "type": "Secret Keyword",
+        "filename": "skills/local-places/SERVER_README.md",
+        "hashed_secret": "6d9c68c603e465077bdd49c62347fe54717f83a3",
+        "is_verified": false,
+        "line_number": 28
+      }
+    ],
+    "skills/openai-whisper-api/SKILL.md": [
+      {
+        "type": "Secret Keyword",
+        "filename": "skills/openai-whisper-api/SKILL.md",
+        "hashed_secret": "1077361f94d70e1ddcc7c6dc581a489532a81d03",
+        "is_verified": false,
+        "line_number": 39
+      }
+    ],
+    "skills/trello/SKILL.md": [
+      {
+        "type": "Secret Keyword",
+        "filename": "skills/trello/SKILL.md",
+        "hashed_secret": "11fa7c37d697f30e6aee828b4426a10f83ab2380",
+        "is_verified": false,
+        "line_number": 18
+      }
+    ],
+    "src/agents/models-config.test.ts": [
+      {
+        "type": "Secret Keyword",
+        "filename": "src/agents/models-config.test.ts",
+        "hashed_secret": "7cf31e8b6cda49f70c31f1f25af05d46f924142d",
+        "is_verified": false,
+        "line_number": 25
+      },
+      {
+        "type": "Secret Keyword",
+        "filename": "src/agents/models-config.test.ts",
+        "hashed_secret": "3a81eb091f80c845232225be5663d270e90dacb7",
+        "is_verified": false,
+        "line_number": 90
+      }
+    ],
+    "src/agents/skills.test.ts": [
+      {
+        "type": "Secret Keyword",
+        "filename": "src/agents/skills.test.ts",
+        "hashed_secret": "3acfb2c2b433c0ea7ff107e33df91b18e52f960f",
+        "is_verified": false,
+        "line_number": 158
+      },
+      {
+        "type": "Secret Keyword",
+        "filename": "src/agents/skills.test.ts",
+        "hashed_secret": "7a85f4764bbd6daf1c3545efbbf0f279a6dc0beb",
+        "is_verified": false,
+        "line_number": 265
+      },
+      {
+        "type": "Secret Keyword",
+        "filename": "src/agents/skills.test.ts",
+        "hashed_secret": "5df3a673d724e8a1eb673a8baf623e183940804d",
+        "is_verified": false,
+        "line_number": 462
+      },
+      {
+        "type": "Secret Keyword",
+        "filename": "src/agents/skills.test.ts",
+        "hashed_secret": "8921daaa546693e52bc1f9c40bdcf15e816e0448",
+        "is_verified": false,
+        "line_number": 490
+      }
+    ],
+    "src/browser/target-id.test.ts": [
+      {
+        "type": "Hex High Entropy String",
+        "filename": "src/browser/target-id.test.ts",
+        "hashed_secret": "4e126c049580d66ca1549fa534d95a7263f27f46",
+        "is_verified": false,
+        "line_number": 16
+      }
+    ],
+    "src/commands/antigravity-oauth.ts": [
+      {
+        "type": "Base64 High Entropy String",
+        "filename": "src/commands/antigravity-oauth.ts",
+        "hashed_secret": "709d0f232b6ac4f8d24dec3e4fabfdb14257174f",
+        "is_verified": false,
+        "line_number": 17
+      },
+      {
+        "type": "Base64 High Entropy String",
+        "filename": "src/commands/antigravity-oauth.ts",
+        "hashed_secret": "3848603b8e866f62d07c206ff622279b9dcb0238",
+        "is_verified": false,
+        "line_number": 20
+      }
+    ],
+    "src/commands/onboard-auth.ts": [
+      {
+        "type": "Secret Keyword",
+        "filename": "src/commands/onboard-auth.ts",
+        "hashed_secret": "16c249e04e2be318050cb883c40137361c0c7209",
+        "is_verified": false,
+        "line_number": 50
+      }
+    ],
+    "src/config/config.test.ts": [
+      {
+        "type": "Secret Keyword",
+        "filename": "src/config/config.test.ts",
+        "hashed_secret": "bea2f7b64fab8d1d414d0449530b1e088d36d5b1",
+        "is_verified": false,
+        "line_number": 520
+      }
+    ],
+    "src/gateway/server.auth.test.ts": [
+      {
+        "type": "Secret Keyword",
+        "filename": "src/gateway/server.auth.test.ts",
+        "hashed_secret": "e5e9fa1ba31ecd1ae84f75caaa474f3a663f05f4",
+        "is_verified": false,
+        "line_number": 89
+      },
+      {
+        "type": "Secret Keyword",
+        "filename": "src/gateway/server.auth.test.ts",
+        "hashed_secret": "a4b48a81cdab1e1a5dd37907d6c85ca1c61ddc7c",
+        "is_verified": false,
+        "line_number": 109
+      }
+    ],
+    "src/infra/env.test.ts": [
+      {
+        "type": "Secret Keyword",
+        "filename": "src/infra/env.test.ts",
+        "hashed_secret": "df98a117ddabf85991b9fe0e268214dc0e1254dc",
+        "is_verified": false,
+        "line_number": 10
+      },
+      {
+        "type": "Secret Keyword",
+        "filename": "src/infra/env.test.ts",
+        "hashed_secret": "6d811dc1f59a55ca1a3d38b5042a062b9f79e8ec",
+        "is_verified": false,
+        "line_number": 25
+      }
+    ],
+    "src/infra/shell-env.test.ts": [
+      {
+        "type": "Secret Keyword",
+        "filename": "src/infra/shell-env.test.ts",
+        "hashed_secret": "65c10dc3549fe07424148a8a4790a3341ecbc253",
+        "is_verified": false,
+        "line_number": 35
+      },
+      {
+        "type": "Base64 High Entropy String",
+        "filename": "src/infra/shell-env.test.ts",
+        "hashed_secret": "64db6bf7f0e5a0491df4419f0eb1bbcc402989e8",
+        "is_verified": false,
+        "line_number": 56
+      },
+      {
+        "type": "Secret Keyword",
+        "filename": "src/infra/shell-env.test.ts",
+        "hashed_secret": "e013ffda590d2178607c16d11b1ea42f75ceb0e7",
+        "is_verified": false,
+        "line_number": 73
+      },
+      {
+        "type": "Base64 High Entropy String",
+        "filename": "src/infra/shell-env.test.ts",
+        "hashed_secret": "be6ee9a6bf9f2dad84a5a67d6c0576a5bacc391e",
+        "is_verified": false,
+        "line_number": 75
+      }
+    ],
+    "src/web/qr-image.test.ts": [
+      {
+        "type": "Hex High Entropy String",
+        "filename": "src/web/qr-image.test.ts",
+        "hashed_secret": "564666dc1ca6e7318b2d5feeb1ce7b5bf717411e",
+        "is_verified": false,
+        "line_number": 12
+      }
+    ],
+    "vendor/a2ui/README.md": [
+      {
+        "type": "Secret Keyword",
+        "filename": "vendor/a2ui/README.md",
+        "hashed_secret": "2619a5397a5d054dab3fe24e6a8da1fbd76ec3a6",
+        "is_verified": false,
+        "line_number": 123
+      }
+    ]
+  },
+  "generated_at": "2026-01-05T13:01:00Z"
+}

AGENTS.md

@@ -25,12 +25,12 @@
 - Run CLI in dev: `pnpm clawdbot ...` (bun) or `pnpm dev`.
 - Node remains supported for running built output (`dist/*`) and production installs.
 - Type-check/build: `pnpm build` (tsc)
-- Lint/format: `pnpm lint` (biome check), `pnpm format` (biome format)
+- Lint/format: `pnpm lint` (oxlint), `pnpm format` (oxfmt)
 - Tests: `pnpm test` (vitest); coverage: `pnpm test:coverage`
 
 ## Coding Style & Naming Conventions
 - Language: TypeScript (ESM). Prefer strict typing; avoid `any`.
-- Formatting/linting via Biome; run `pnpm lint` before commits.
+- Formatting/linting via Oxlint and Oxfmt; run `pnpm lint` before commits.
 - Add brief code comments for tricky or non-obvious logic.
 - Keep files concise; extract helpers instead of “V2” copies. Use existing patterns for CLI options and dependency injection via `createDefaultDeps`.
 - Aim to keep files under ~700 LOC; guideline only (not a hard guardrail). Split/refactor when it improves clarity or testability.
@@ -70,12 +70,13 @@
 - Never commit or publish real phone numbers, videos, or live configuration values. Use obviously fake placeholders in docs, tests, and examples.
 
 ## Troubleshooting
-- Rebrand/migration issues (Clawdis → Clawdbot) or legacy config/service warnings: run `clawdbot doctor` (see `docs/gateway/doctor.md`).
+- Rebrand/migration issues or legacy config/service warnings: run `clawdbot doctor` (see `docs/gateway/doctor.md`).
 
 ## Agent-Specific Notes
 - Vocabulary: "makeup" = "mac app".
 - When answering questions, respond with high-confidence answers only: verify in code; do not guess.
 - Never update the Carbon dependency.
+- Any dependency with `pnpm.patchedDependencies` must use an exact version (no `^`/`~`).
 - CLI progress: use `src/cli/progress.ts` (`osc-progress` + `@clack/prompts` spinner); don’t hand-roll spinners/bars.
 - Status output: keep tables + ANSI-safe wrapping (`src/terminal/table.ts`); `status --all` = read-only/pasteable, `status --deep` = probes.
 - Gateway currently runs only as the menubar app; there is no separate LaunchAgent/helper label installed. Restart via the Clawdbot Mac app or `scripts/restart-mac.sh`; to verify/kill use `launchctl print gui/$UID | grep clawdbot` rather than assuming a fixed label. **When debugging on macOS, start/stop the gateway via the app, not ad-hoc tmux sessions; kill any temporary tunnels before handoff.**

CHANGELOG.md

@@ -1,43 +1,142 @@
 # Changelog
 
-## 2025.1.12 (Unreleased)
+## 2026.1.14 (unreleased)
 
-### Highlights
-- Memory: add vector search for agent memories (Markdown-only) with SQLite index, chunking, lazy sync + file watch, and per-agent enablement/fallback.
-- Plugins: restore full voice-call plugin parity (Telnyx/Twilio, streaming, inbound policies, tools/CLI).
-- Models: add Synthetic provider plus Moonshot Kimi K2 0905 + turbo/thinking variants (with docs).
-- Cron: one-shot schedules accept ISO timestamps (UTC) with optional delete-after-run; cron jobs can target a specific agent (CLI + macOS/Control UI).
-- Agents: add compaction mode config with optional safeguard summarization and per-agent model fallbacks.
-
-### New & Improved
-- Memory: add custom OpenAI-compatible embedding endpoints; support OpenAI/local `node-llama-cpp` embeddings with per-agent overrides and provider metadata in tools/CLI.
-- Memory: new `clawdbot memory` CLI plus `memory_search`/`memory_get` tools with snippets + line ranges; index stored under `~/.clawdbot/memory/{agentId}.sqlite` with watch-on-by-default.
-- Agents: strengthen memory recall guidance; make workspace bootstrap truncation configurable (default 20k) with warnings; add default sub-agent model config.
-- Tools/Sandbox: add tool profiles + group shorthands; support tool-policy groups in `tools.sandbox.tools`; drop legacy `memory` shorthand; allow Docker bind mounts via `docker.binds`.
-- Tools: add browser `scrollintoview` action; allow Claude/Gemini tool param aliases; allow thinking `xhigh` for GPT-5.2/Codex with safe downgrades.
-- Gateway/CLI: add Tailscale binary discovery, custom bind mode, and probe auth retry; add `clawdbot dashboard` auto-open flow; default native slash commands to `"auto"` with per-provider overrides.
-- Auth/Onboarding: add Chutes OAuth (PKCE + refresh + onboarding choice); normalize API key inputs; default TUI onboarding to `deliver: false`.
-- Providers: add `discord.allowBots`; trim legacy MiniMax M2 from default catalogs; route MiniMax vision to the Coding Plan VLM endpoint (also accepts `@/path/to/file.png` inputs).
-- Gateway: allow Tailscale Serve identity headers to satisfy token auth; rebuild Control UI assets when protocol schema is newer.
-- Heartbeat: default `ackMaxChars` to 300 so short `HEARTBEAT_OK` replies stay internal.
+### Changes
+- Docs: clarify per-agent auth stores, sandboxed skill binaries, and elevated semantics.
+- Daemon: support profile-aware service names for multi-gateway setups. (#671) — thanks @bjesuiter.
+- Docs: add FAQ entries for missing provider auth after adding agents and Gemini thinking signature errors.
+- Agents: add optional auth-profile copy prompt on `agents add` and improve auth error messaging.
+- Security: expand `clawdbot security audit` checks (model hygiene, config includes, plugin allowlists, exposure matrix) and extend `--fix` to tighten more sensitive state paths.
+- Security: add `SECURITY.md` reporting policy.
+- Plugins: add Zalo channel plugin with gateway HTTP hooks and onboarding install prompt. (#854) — thanks @longmaba.
+- Onboarding: add a security checkpoint prompt (docs link + sandboxing hint); require `--accept-risk` for `--non-interactive`.
+- Docs: expand gateway security hardening guidance and incident response checklist.
+- Docs: document DM history limits for channel DMs. (#883) — thanks @pkrmf.
+- Security: add detect-secrets CI scan and baseline guidance. (#227) — thanks @Hyaxia.
+- Tools: add `web_search`/`web_fetch` (Brave API), auto-enable `web_fetch` for sandboxed sessions, and remove the `brave-search` skill.
+- CLI/Docs: add a web tools configure section for storing Brave API keys and update onboarding tips.
+- Tools: return a setup hint (docs link) when web_search runs without a Brave API key.
+- Config/Doctor: remove legacy Clawdis env fallbacks and config/service migrations (Clawdbot-only).
+- Browser: add Chrome extension relay takeover mode (toolbar button), plus `clawdbot browser extension install/path` and remote browser control via `clawdbot browser serve` + `browser.controlToken`.
+- CLI/Docs: add per-command CLI doc pages and link them from `clawdbot <command> --help`.
+- Browser: copy the installed Chrome extension path to clipboard after `clawdbot browser extension install/path`.
+- WhatsApp: add `channels.whatsapp.sendReadReceipts` to disable auto read receipts. (#882) — thanks @chrisrodz.
 
 ### Fixes
-- Models/Providers: treat credential validation failures as auth errors to trigger fallback; normalize `${ENV_VAR}` apiKey values and auto-fill missing provider keys; preserve explicit GitHub Copilot provider config + agent-dir auth profiles.
-- Gemini: normalize Gemini 3 ids to preview variants; strip Gemini CLI tool call/response ids; downgrade missing `thought_signature`; strip Claude `msg_*` thought_signature fields to avoid base64 decode errors.
-- MiniMax: strip malformed tool invocation XML; include `MiniMax-VL-01` in implicit provider for image pairing.
-- Anthropic: merge consecutive user turns (preserve newest metadata) before validation to avoid incorrect role errors.
-- Messaging: enforce context isolation for message tool sends; keep typing indicators alive during tool execution.
-- Auto-reply: `/status` allowlist behavior, reasoning-tag enforcement on fallback, and system-event enqueueing for elevated/reasoning toggles.
-- Auto-reply: explain how to enable `/bash` when it’s disabled; add security notes + FAQ. (#722) — thanks @vrknetha.
+- Browser: add tests for snapshot labels/efficient query params and labeled image responses.
+- macOS: ensure launchd log directory exists with a test-only override. (#909) — thanks @roshanasingh4.
+- Packaging: run `pnpm build` on `prepack` so npm publishes include fresh `dist/` output.
+- Telegram: register dock native commands with underscores to avoid `BOT_COMMAND_INVALID` (#929, fixes #901) — thanks @grp06.
+- Google: downgrade unsigned thinking blocks before send to avoid missing signature errors.
+- Agents: make user time zone and 24-hour time explicit in the system prompt. (#859) — thanks @CashWilliams.
+- Agents: strip downgraded tool call text without eating adjacent replies and filter thinking-tag leaks. (#905) — thanks @erikpr1994.
+- Agents: cap tool call IDs for OpenAI/OpenRouter to avoid request rejections. (#875) — thanks @j1philli.
+- Doctor: avoid re-adding WhatsApp config when only legacy ack reactions are set. (#927, fixes #900) — thanks @grp06.
+- Agents: scrub tuple `items` schemas for Gemini tool calls. (#926, fixes #746) — thanks @grp06.
+- Agents: stabilize sub-agent announce status from runtime outcomes and normalize Result/Notes. (#835) — thanks @roshanasingh4.
+- Embedded runner: suppress raw API error payloads from replies. (#924) — thanks @grp06.
+- Auth: normalize Claude Code CLI profile mode to oauth and auto-migrate config. (#855) — thanks @sebslight.
+- Daemon: clear persisted launchd disabled state before bootstrap (fixes `daemon install` after uninstall). (#849) — thanks @ndraiman.
+- Logging: tolerate `EIO` from console writes to avoid gateway crashes. (#925, fixes #878) — thanks @grp06.
+- Sandbox: restore `docker.binds` config validation for custom bind mounts. (#873) — thanks @akonyer.
+- Sandbox: preserve configured PATH for `docker exec` so custom tools remain available. (#873) — thanks @akonyer.
+- Slack: respect `channels.slack.requireMention` default when resolving channel mention gating. (#850) — thanks @evalexpr.
+- Telegram: aggregate split inbound messages into one prompt (reduces “one reply per fragment”).
+- Auto-reply: treat trailing `NO_REPLY` tokens as silent replies.
+- Config: prevent partial config writes from clobbering unrelated settings (base hash guard + merge patch for connection saves).
+
+## 2026.1.14
+
+### Changes
+- Usage: add MiniMax coding plan usage tracking.
+- Auth: label Claude Code CLI auth options. (#915) — thanks @SeanZoR.
+- Docs: standardize Claude Code CLI naming across docs and prompts. (follow-up to #915)
+- Telegram: add message delete action in the message tool. (#903) — thanks @sleontenko.
+- Config: add `channels.<provider>.configWrites` gating for channel-initiated config writes; migrate Slack channel IDs.
+
+### Fixes
+ - Mac: pass auth token/password to dashboard URL for authenticated access. (#918) — thanks @rahthakor.
+ - UI: use application-defined WebSocket close code (browser compatibility). (#918) — thanks @rahthakor.
+- TUI: render picker overlays via the overlay stack so /models and /settings display. (#921) — thanks @grizzdank.
+- TUI: add a bright spinner + elapsed time in the status line for send/stream/run states.
+- Gateway/Dev: ensure `pnpm gateway:dev` always uses the dev profile config + state (`~/.clawdbot-dev`).
+- macOS: fix cron preview/testing payload to use `channel` key. (#867) — thanks @wes-davis.
+- Telegram: honor `channels.telegram.timeoutSeconds` for grammY API requests. (#863) — thanks @Snaver.
+- Telegram: split long captions into media + follow-up text messages. (#907) - thanks @jalehman.
+- Telegram: migrate group config when supergroups change chat IDs. (#906) — thanks @sleontenko.
+- Messaging: unify markdown formatting + format-first chunking for Slack/Telegram/Signal. (#920) — thanks @TheSethRose.
+- Slack: drop Socket Mode events with mismatched `api_app_id`/`team_id`. (#889) — thanks @roshanasingh4.
+- Discord: isolate autoThread thread context. (#856) — thanks @davidguttman.
+- WhatsApp: fix context isolation using wrong ID (was bot's number, now conversation ID). (#911) — thanks @tristanmanchester.
+- WhatsApp: normalize user JIDs with device suffix for allowlist checks in groups. (#838) — thanks @peschee.
+
+## 2026.1.13
+
+### Fixes
+- Postinstall: treat already-applied pnpm patches as no-ops to avoid npm/bun install failures.
+- Packaging: pin `@mariozechner/pi-ai` to 0.45.7 and refresh patched dependency to match npm resolution.
+
+## 2026.1.12-2
+
+### Fixes
+- Packaging: include `dist/memory/**` in the npm tarball (fixes `ERR_MODULE_NOT_FOUND` for `dist/memory/index.js`).
+- Agents: persist sub-agent registry across gateway restarts and resume announce flow safely. (#831) — thanks @roshanasingh4.
+
+## 2026.1.12-1
+
+### Fixes
+- Packaging: include `dist/channels/**` in the npm tarball (fixes `ERR_MODULE_NOT_FOUND` for `dist/channels/registry.js`).
+
+## 2026.1.12
+
+### Highlights
+- **BREAKING:** rename chat “providers” (Slack/Telegram/WhatsApp/…) to **channels** across CLI/RPC/config; legacy config keys auto-migrate on load (and are written back as `channels.*`).
+- Memory: add vector search for agent memories (Markdown-only) with SQLite index, chunking, lazy sync + file watch, and per-agent enablement/fallback.
+- Plugins: restore full voice-call plugin parity (Telnyx/Twilio, streaming, inbound policies, tools/CLI).
+- Models: add Synthetic provider plus Moonshot Kimi K2 0905 + turbo/thinking variants (with docs). (#811) — thanks @siraht; (#818) — thanks @mickahouan.
+- Cron: one-shot schedules accept ISO timestamps (UTC) with optional delete-after-run; cron jobs can target a specific agent (CLI + macOS/Control UI).
+- Agents: add compaction mode config with optional safeguard summarization and per-agent model fallbacks. (#700) — thanks @thewilloftheshadow; (#583) — thanks @mitschabaude-bot.
+
+### New & Improved
+- Memory: add custom OpenAI-compatible embedding endpoints; support OpenAI/local `node-llama-cpp` embeddings with per-agent overrides and provider metadata in tools/CLI. (#819) — thanks @mukhtharcm.
+- Memory: new `clawdbot memory` CLI plus `memory_search`/`memory_get` tools with snippets + line ranges; index stored under `~/.clawdbot/memory/{agentId}.sqlite` with watch-on-by-default.
+- Agents: strengthen memory recall guidance; make workspace bootstrap truncation configurable (default 20k) with warnings; add default sub-agent model config.
+- Tools/Sandbox: add tool profiles + group shorthands; support tool-policy groups in `tools.sandbox.tools`; drop legacy `memory` shorthand; allow Docker bind mounts via `docker.binds`. (#790) — thanks @akonyer.
+- Tools: add provider/model-specific tool policy overrides (`tools.byProvider`) to trim tool exposure per provider.
+- Tools: add browser `scrollintoview` action; allow Claude/Gemini tool param aliases; allow thinking `xhigh` for GPT-5.2/Codex with safe downgrades. (#793) — thanks @hsrvc; (#444) — thanks @grp06.
+- Gateway/CLI: add Tailscale binary discovery, custom bind mode, and probe auth retry; add `clawdbot dashboard` auto-open flow; default native slash commands to `"auto"` with per-provider overrides. (#740) — thanks @jeffersonwarrior.
+- Auth/Onboarding: add Chutes OAuth (PKCE + refresh + onboarding choice); normalize API key inputs; default TUI onboarding to `deliver: false`. (#726) — thanks @FrieSei; (#791) — thanks @roshanasingh4.
+- Providers: add `discord.allowBots`; trim legacy MiniMax M2 from default catalogs; route MiniMax vision to the Coding Plan VLM endpoint (also accepts `@/path/to/file.png` inputs). (#802) — thanks @zknicker.
+- Gateway: allow Tailscale Serve identity headers to satisfy token auth; rebuild Control UI assets when protocol schema is newer. (#823) — thanks @roshanasingh4; (#786) — thanks @meaningfool.
+- Heartbeat: default `ackMaxChars` to 300 so short `HEARTBEAT_OK` replies stay internal.
+
+### Installer
+- Install: run `clawdbot doctor --non-interactive` after git installs/updates and nudge daemon restarts when detected.
+
+### Fixes
+- Doctor: warn on pnpm workspace mismatches, missing Control UI assets, and missing tsx binaries; offer UI rebuilds.
+- Tools: apply global tool allow/deny even when agent-specific tool policy is set.
+- Models/Providers: treat credential validation failures as auth errors to trigger fallback; normalize `${ENV_VAR}` apiKey values and auto-fill missing provider keys; preserve explicit GitHub Copilot provider config + agent-dir auth profiles. (#822) — thanks @sebslight; (#705) — thanks @TAGOOZ.
+- Auth: drop invalid auth profiles from ordering so environment keys can still be used for providers like MiniMax.
+- Gemini: normalize Gemini 3 ids to preview variants; strip Gemini CLI tool call/response ids; downgrade missing `thought_signature`; strip Claude `msg_*` thought_signature fields to avoid base64 decode errors. (#795) — thanks @thewilloftheshadow; (#783) — thanks @ananth-vardhan-cn; (#793) — thanks @hsrvc; (#805) — thanks @marcmarg.
+- Agents: auto-recover from compaction context overflow by resetting the session and retrying; propagate overflow details from embedded runs so callers can recover.
+- MiniMax: strip malformed tool invocation XML; include `MiniMax-VL-01` in implicit provider for image pairing. (#809) — thanks @latitudeki5223.
+- Onboarding/Auth: honor `CLAWDBOT_AGENT_DIR` / `PI_CODING_AGENT_DIR` when writing auth profiles (MiniMax). (#829) — thanks @roshanasingh4.
+- Anthropic: handle `overloaded_error` with a friendly message and failover classification. (#832) — thanks @danielz1z.
+- Anthropic: merge consecutive user turns (preserve newest metadata) before validation to avoid incorrect role errors. (#804) — thanks @ThomsenDrake.
+- Messaging: enforce context isolation for message tool sends; keep typing indicators alive during tool execution. (#793) — thanks @hsrvc; (#450, #447) — thanks @thewilloftheshadow.
+- Auto-reply: `/status` allowlist behavior, reasoning-tag enforcement on fallback, and system-event enqueueing for elevated/reasoning toggles. (#810) — thanks @mcinteerj.
+- System events: include local timestamps when events are injected into prompts. (#245) — thanks @thewilloftheshadow.
 - Auto-reply: resolve ambiguous `/model` matches; fix streaming block reply media handling; keep >300 char heartbeat replies instead of dropping.
-- Discord/Slack: centralize reply-thread planning; fix autoThread routing + add per-channel autoThread; avoid duplicate listeners; keep reasoning italics intact; allow clearing channel parents via message tool.
-- Telegram: preserve forum topic thread ids, persist polling offsets, respect account bindings in webhook mode, and show typing indicator in General topics.
-- Slack: accept slash commands with or without leading `/` for custom command configs.
-- Cron: persist disabled jobs correctly; accept `jobId` aliases for update/run/remove params.
-- Gateway/CLI: honor `CLAWDBOT_LAUNCHD_LABEL` / `CLAWDBOT_SYSTEMD_UNIT` overrides; `agents.list` respects explicit config; reduce noisy loopback WS logs during tests; run `clawdbot doctor --non-interactive` during updates.
-- Onboarding/Control UI: refuse invalid configs (run doctor first); quote Windows browser URLs for OAuth; keep chat scroll position unless the user is near the bottom.
-- Tools/UI: harden tool input schemas for strict providers; drop null-only union variants for Gemini schema cleanup; treat `maxChars: 0` as unlimited; keep TUI last streamed response instead of "(no output)".
-- Connections UI: polish multi-account account cards.
+- Discord/Slack: centralize reply-thread planning; fix autoThread routing + add per-channel autoThread; avoid duplicate listeners; keep reasoning italics intact; allow clearing channel parents via message tool. (#800, #807) — thanks @davidguttman; (#744) — thanks @thewilloftheshadow.
+- Telegram: preserve forum topic thread ids, persist polling offsets, respect account bindings in webhook mode, and show typing indicator in General topics. (#727, #739) — thanks @thewilloftheshadow; (#821) — thanks @gumadeiras; (#779) — thanks @azade-c.
+- Slack: accept slash commands with or without leading `/` for custom command configs. (#798) — thanks @thewilloftheshadow.
+- Cron: persist disabled jobs correctly; accept `jobId` aliases for update/run/remove params. (#205, #252) — thanks @thewilloftheshadow.
+- Gateway/CLI: honor `CLAWDBOT_LAUNCHD_LABEL` / `CLAWDBOT_SYSTEMD_UNIT` overrides; `agents.list` respects explicit config; reduce noisy loopback WS logs during tests; run `clawdbot doctor --non-interactive` during updates. (#781) — thanks @ronyrus.
+- Onboarding/Control UI: refuse invalid configs (run doctor first); quote Windows browser URLs for OAuth; keep chat scroll position unless the user is near the bottom. (#764) — thanks @mukhtharcm; (#794) — thanks @roshanasingh4; (#217) — thanks @thewilloftheshadow.
+- Tools/UI: harden tool input schemas for strict providers; drop null-only union variants for Gemini schema cleanup; treat `maxChars: 0` as unlimited; keep TUI last streamed response instead of "(no output)". (#782) — thanks @AbhisekBasu1; (#796) — thanks @gabriel-trigo; (#747) — thanks @thewilloftheshadow.
+- Connections UI: polish multi-account account cards. (#816) — thanks @steipete.
 
 ### Maintenance
 - Dependencies: bump Pi packages to 0.45.3 and refresh patched pi-ai.
@@ -283,7 +382,7 @@
 - Dependencies: Pi 0.40.0 bump (#543) — thanks @mcinteerj.
 - Build: Docker build cache layer (#605) — thanks @zknicker.
 
-- Auth: enable OAuth token refresh for Claude CLI credentials (`anthropic:claude-cli`) with bidirectional sync back to Claude Code storage (file on Linux/Windows, Keychain on macOS). This allows long-running agents to operate autonomously without manual re-authentication (#654 — thanks @radek-paclt).
+- Auth: enable OAuth token refresh for Claude Code CLI credentials (`anthropic:claude-cli`) with bidirectional sync back to Claude Code storage (file on Linux/Windows, Keychain on macOS). This allows long-running agents to operate autonomously without manual re-authentication (#654 — thanks @radek-paclt).
 
 ## 2026.1.8
 

CONTRIBUTING.md

@@ -13,7 +13,7 @@ Welcome to the lobster tank! 🦞
   - GitHub: [@steipete](https://github.com/steipete) · X: [@steipete](https://x.com/steipete)
 
 - **Shadow** - Discord + Slack subsystem
-  - GitHub: [@4shadowed](https://github.com/4shadowed) · X: [@4shad0wed](https://x.com/4shad0wed)
+  - GitHub: [@thewilloftheshadow](https://github.com/thewilloftheshadow) · X: [@4shad0wed](https://x.com/4shad0wed)
 
 - **Jos** - Telegram, API, Nix mode
   - GitHub: [@joshp123](https://github.com/joshp123) · X: [@jjpcodes](https://x.com/jjpcodes)

README.md

@@ -16,13 +16,13 @@
 </p>
 
 **Clawdbot** is a *personal AI assistant* you run on your own devices.
-It answers you on the providers you already use (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Microsoft Teams, WebChat), can speak and listen on macOS/iOS/Android, and can render a live Canvas you control. The Gateway is just the control plane — the product is the assistant.
+It answers you on the channels you already use (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Microsoft Teams, WebChat), can speak and listen on macOS/iOS/Android, and can render a live Canvas you control. The Gateway is just the control plane — the product is the assistant.
 
 If you want a personal, single-user assistant that feels local, fast, and always-on, this is it.
 
 [Website](https://clawdbot.com) · [Docs](https://docs.clawd.bot) · [Getting Started](https://docs.clawd.bot/start/getting-started) · [Updating](https://docs.clawd.bot/install/updating) · [Showcase](https://docs.clawd.bot/start/showcase) · [FAQ](https://docs.clawd.bot/start/faq) · [Wizard](https://docs.clawd.bot/start/wizard) · [Nix](https://github.com/clawdbot/nix-clawdbot) · [Docker](https://docs.clawd.bot/install/docker) · [Discord](https://discord.gg/clawd)
 
-Preferred setup: run the onboarding wizard (`clawdbot onboard`). It walks through gateway, workspace, providers, and skills. The CLI wizard is the recommended path and works on **macOS, Linux, and Windows (via WSL2; strongly recommended)**.
+Preferred setup: run the onboarding wizard (`clawdbot onboard`). It walks through gateway, workspace, channels, and skills. The CLI wizard is the recommended path and works on **macOS, Linux, and Windows (via WSL2; strongly recommended)**.
 Works with npm, pnpm, or bun.
 New install? Start here: [Getting started](https://docs.clawd.bot/start/getting-started)
 
@@ -54,7 +54,7 @@ The wizard installs the Gateway daemon (launchd/systemd user service) so it stay
 
 Runtime: **Node ≥22**.
 
-Full beginner guide (auth, pairing, providers): [Getting started](https://docs.clawd.bot/start/getting-started)
+Full beginner guide (auth, pairing, channels): [Getting started](https://docs.clawd.bot/start/getting-started)
 
 ```bash
 clawdbot onboard --install-daemon
@@ -97,17 +97,17 @@ Clawdbot connects to real messaging surfaces. Treat inbound DMs as **untrusted i
 Full security guide: [Security](https://docs.clawd.bot/gateway/security)
 
 Default behavior on Telegram/WhatsApp/Signal/iMessage/Microsoft Teams/Discord/Slack:
-- **DM pairing** (`dmPolicy="pairing"` / `discord.dm.policy="pairing"` / `slack.dm.policy="pairing"`): unknown senders receive a short pairing code and the bot does not process their message.
-- Approve with: `clawdbot pairing approve <provider> <code>` (then the sender is added to a local allowlist store).
-- Public inbound DMs require an explicit opt-in: set `dmPolicy="open"` and include `"*"` in the provider allowlist (`allowFrom` / `discord.dm.allowFrom` / `slack.dm.allowFrom`).
+- **DM pairing** (`dmPolicy="pairing"` / `channels.discord.dm.policy="pairing"` / `channels.slack.dm.policy="pairing"`): unknown senders receive a short pairing code and the bot does not process their message.
+- Approve with: `clawdbot pairing approve <channel> <code>` (then the sender is added to a local allowlist store).
+- Public inbound DMs require an explicit opt-in: set `dmPolicy="open"` and include `"*"` in the channel allowlist (`allowFrom` / `channels.discord.dm.allowFrom` / `channels.slack.dm.allowFrom`).
 
 Run `clawdbot doctor` to surface risky/misconfigured DM policies.
 
 ## Highlights
 
-- **[Local-first Gateway](https://docs.clawd.bot/gateway)** — single control plane for sessions, providers, tools, and events.
-- **[Multi-provider inbox](https://docs.clawd.bot/providers)** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Microsoft Teams, WebChat, macOS, iOS/Android.
-- **[Multi-agent routing](https://docs.clawd.bot/gateway/configuration)** — route inbound providers/accounts/peers to isolated agents (workspaces + per-agent sessions).
+- **[Local-first Gateway](https://docs.clawd.bot/gateway)** — single control plane for sessions, channels, tools, and events.
+- **[Multi-channel inbox](https://docs.clawd.bot/channels)** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Microsoft Teams, WebChat, macOS, iOS/Android.
+- **[Multi-agent routing](https://docs.clawd.bot/gateway/configuration)** — route inbound channels/accounts/peers to isolated agents (workspaces + per-agent sessions).
 - **[Voice Wake](https://docs.clawd.bot/nodes/voicewake) + [Talk Mode](https://docs.clawd.bot/nodes/talk)** — always-on speech for macOS/iOS/Android with ElevenLabs.
 - **[Live Canvas](https://docs.clawd.bot/platforms/mac/canvas)** — agent-driven visual workspace with [A2UI](https://docs.clawd.bot/platforms/mac/canvas#canvas-a2ui).
 - **[First-class tools](https://docs.clawd.bot/tools)** — browser, canvas, nodes, cron, sessions, and Discord/Slack actions.
@@ -127,9 +127,9 @@ Run `clawdbot doctor` to surface risky/misconfigured DM policies.
 - [Session model](https://docs.clawd.bot/concepts/session): `main` for direct chats, group isolation, activation modes, queue modes, reply-back. Group rules: [Groups](https://docs.clawd.bot/concepts/groups).
 - [Media pipeline](https://docs.clawd.bot/nodes/images): images/audio/video, transcription hooks, size caps, temp file lifecycle. Audio details: [Audio](https://docs.clawd.bot/nodes/audio).
 
-### Providers
-- [Providers](https://docs.clawd.bot/providers): [WhatsApp](https://docs.clawd.bot/providers/whatsapp) (Baileys), [Telegram](https://docs.clawd.bot/providers/telegram) (grammY), [Slack](https://docs.clawd.bot/providers/slack) (Bolt), [Discord](https://docs.clawd.bot/providers/discord) (discord.js), [Signal](https://docs.clawd.bot/providers/signal) (signal-cli), [iMessage](https://docs.clawd.bot/providers/imessage) (imsg), [Microsoft Teams](https://docs.clawd.bot/providers/msteams) (Bot Framework), [WebChat](https://docs.clawd.bot/web/webchat).
-- [Group routing](https://docs.clawd.bot/concepts/group-messages): mention gating, reply tags, per-provider chunking and routing. Provider rules: [Providers](https://docs.clawd.bot/providers).
+### Channels
+- [Channels](https://docs.clawd.bot/channels): [WhatsApp](https://docs.clawd.bot/channels/whatsapp) (Baileys), [Telegram](https://docs.clawd.bot/channels/telegram) (grammY), [Slack](https://docs.clawd.bot/channels/slack) (Bolt), [Discord](https://docs.clawd.bot/channels/discord) (discord.js), [Signal](https://docs.clawd.bot/channels/signal) (signal-cli), [iMessage](https://docs.clawd.bot/channels/imessage) (imsg), [Microsoft Teams](https://docs.clawd.bot/channels/msteams) (Bot Framework), [WebChat](https://docs.clawd.bot/web/webchat).
+- [Group routing](https://docs.clawd.bot/concepts/group-messages): mention gating, reply tags, per-channel chunking and routing. Channel rules: [Channels](https://docs.clawd.bot/channels).
 
 ### Apps + nodes
 - [macOS app](https://docs.clawd.bot/platforms/macos): menu bar control plane, [Voice Wake](https://docs.clawd.bot/nodes/voicewake)/PTT, [Talk Mode](https://docs.clawd.bot/nodes/talk) overlay, [WebChat](https://docs.clawd.bot/web/webchat), debug tools, [remote gateway](https://docs.clawd.bot/gateway/remote) control.
@@ -145,10 +145,10 @@ Run `clawdbot doctor` to surface risky/misconfigured DM policies.
 - [Skills platform](https://docs.clawd.bot/tools/skills): bundled, managed, and workspace skills with install gating + UI.
 
 ### Runtime + safety
-- [Provider routing](https://docs.clawd.bot/concepts/provider-routing), [retry policy](https://docs.clawd.bot/concepts/retry), and [streaming/chunking](https://docs.clawd.bot/concepts/streaming).
+- [Channel routing](https://docs.clawd.bot/concepts/channel-routing), [retry policy](https://docs.clawd.bot/concepts/retry), and [streaming/chunking](https://docs.clawd.bot/concepts/streaming).
 - [Presence](https://docs.clawd.bot/concepts/presence), [typing indicators](https://docs.clawd.bot/concepts/typing-indicators), and [usage tracking](https://docs.clawd.bot/concepts/usage-tracking).
 - [Models](https://docs.clawd.bot/concepts/models), [model failover](https://docs.clawd.bot/concepts/model-failover), and [session pruning](https://docs.clawd.bot/concepts/session-pruning).
-- [Security](https://docs.clawd.bot/gateway/security) and [troubleshooting](https://docs.clawd.bot/providers/troubleshooting).
+- [Security](https://docs.clawd.bot/gateway/security) and [troubleshooting](https://docs.clawd.bot/channels/troubleshooting).
 
 ### Ops + packaging
 - [Control UI](https://docs.clawd.bot/web) + [WebChat](https://docs.clawd.bot/web/webchat) served directly from the Gateway.
@@ -204,7 +204,7 @@ Details: [Tailscale guide](https://docs.clawd.bot/gateway/tailscale) · [Web sur
 
 It’s perfectly fine to run the Gateway on a small Linux instance. Clients (macOS app, CLI, WebChat) can connect over **Tailscale Serve/Funnel** or **SSH tunnels**, and you can still pair device nodes (macOS/iOS/Android) to execute device‑local actions when needed.
 
-- **Gateway host** runs the exec tool and provider connections by default.
+- **Gateway host** runs the exec tool and channel connections by default.
 - **Device nodes** run device‑local actions (`system.run`, camera, screen recording, notifications) via `node.invoke`.
 In short: exec runs where the Gateway lives; device actions run where the device lives.
 
@@ -315,52 +315,56 @@ Minimal `~/.clawdbot/clawdbot.json` (model + defaults):
 
 Details: [Security guide](https://docs.clawd.bot/gateway/security) · [Docker + sandboxing](https://docs.clawd.bot/install/docker) · [Sandbox config](https://docs.clawd.bot/gateway/configuration)
 
-### [WhatsApp](https://docs.clawd.bot/providers/whatsapp)
+### [WhatsApp](https://docs.clawd.bot/channels/whatsapp)
 
-- Link the device: `pnpm clawdbot providers login` (stores creds in `~/.clawdbot/credentials`).
-- Allowlist who can talk to the assistant via `whatsapp.allowFrom`.
-- If `whatsapp.groups` is set, it becomes a group allowlist; include `"*"` to allow all.
+- Link the device: `pnpm clawdbot channels login` (stores creds in `~/.clawdbot/credentials`).
+- Allowlist who can talk to the assistant via `channels.whatsapp.allowFrom`.
+- If `channels.whatsapp.groups` is set, it becomes a group allowlist; include `"*"` to allow all.
 
-### [Telegram](https://docs.clawd.bot/providers/telegram)
+### [Telegram](https://docs.clawd.bot/channels/telegram)
 
-- Set `TELEGRAM_BOT_TOKEN` or `telegram.botToken` (env wins).
-- Optional: set `telegram.groups` (with `telegram.groups."*".requireMention`); when set, it is a group allowlist (include `"*"` to allow all). Also `telegram.allowFrom` or `telegram.webhookUrl` as needed.
+- Set `TELEGRAM_BOT_TOKEN` or `channels.telegram.botToken` (env wins).
+- Optional: set `channels.telegram.groups` (with `channels.telegram.groups."*".requireMention`); when set, it is a group allowlist (include `"*"` to allow all). Also `channels.telegram.allowFrom` or `channels.telegram.webhookUrl` as needed.
 
 ```json5
 {
-  telegram: {
-    botToken: "123456:ABCDEF"
+  channels: {
+    telegram: {
+      botToken: "123456:ABCDEF"
+    }
   }
 }
 ```
 
-### [Slack](https://docs.clawd.bot/providers/slack)
+### [Slack](https://docs.clawd.bot/channels/slack)
 
-- Set `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` (or `slack.botToken` + `slack.appToken`).
+- Set `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` (or `channels.slack.botToken` + `channels.slack.appToken`).
 
-### [Discord](https://docs.clawd.bot/providers/discord)
+### [Discord](https://docs.clawd.bot/channels/discord)
 
-- Set `DISCORD_BOT_TOKEN` or `discord.token` (env wins).
-- Optional: set `commands.native`, `commands.text`, or `commands.useAccessGroups`, plus `discord.dm.allowFrom`, `discord.guilds`, or `discord.mediaMaxMb` as needed.
+- Set `DISCORD_BOT_TOKEN` or `channels.discord.token` (env wins).
+- Optional: set `commands.native`, `commands.text`, or `commands.useAccessGroups`, plus `channels.discord.dm.allowFrom`, `channels.discord.guilds`, or `channels.discord.mediaMaxMb` as needed.
 
 ```json5
 {
-  discord: {
-    token: "1234abcd"
+  channels: {
+    discord: {
+      token: "1234abcd"
+    }
   }
 }
 ```
 
-### [Signal](https://docs.clawd.bot/providers/signal)
+### [Signal](https://docs.clawd.bot/channels/signal)
 
-- Requires `signal-cli` and a `signal` config section.
+- Requires `signal-cli` and a `channels.signal` config section.
 
-### [iMessage](https://docs.clawd.bot/providers/imessage)
+### [iMessage](https://docs.clawd.bot/channels/imessage)
 
 - macOS only; Messages must be signed in.
-- If `imessage.groups` is set, it becomes a group allowlist; include `"*"` to allow all.
+- If `channels.imessage.groups` is set, it becomes a group allowlist; include `"*"` to allow all.
 
-### [Microsoft Teams](https://docs.clawd.bot/providers/msteams)
+### [Microsoft Teams](https://docs.clawd.bot/channels/msteams)
 
 - Configure a Teams app + Bot Framework, then add a `msteams` config section.
 - Allowlist who can talk via `msteams.allowFrom`; group access via `msteams.groupAllowFrom` or `msteams.groupPolicy: "open"`.
@@ -395,7 +399,7 @@ Use these when you’re past the onboarding flow and want the deeper reference.
 - [Set up Gmail Pub/Sub triggers.](https://docs.clawd.bot/automation/gmail-pubsub)
 - [Learn the macOS menu bar companion details.](https://docs.clawd.bot/platforms/mac/menu-bar)
 - [Platform guides: Windows (WSL2)](https://docs.clawd.bot/platforms/windows), [Linux](https://docs.clawd.bot/platforms/linux), [macOS](https://docs.clawd.bot/platforms/macos), [iOS](https://docs.clawd.bot/platforms/ios), [Android](https://docs.clawd.bot/platforms/android)
-- [Debug common failures with the troubleshooting guide.](https://docs.clawd.bot/providers/troubleshooting)
+- [Debug common failures with the troubleshooting guide.](https://docs.clawd.bot/channels/troubleshooting)
 - [Review security guidance before exposing anything.](https://docs.clawd.bot/gateway/security)
 
 ## Advanced docs (discovery + control)
@@ -464,24 +468,28 @@ AI/vibe-coded PRs welcome! 🤖
 
 Special thanks to @andrewting19 for the Anthropic OAuth tool-name fix.
 
+Core contributors:
+- @cpojer — Telegram onboarding UX + docs
+
 Thanks to all clawtributors:
 
 <p align="left">
   <a href="https://github.com/steipete"><img src="https://avatars.githubusercontent.com/u/58493?v=4&s=48" width="48" height="48" alt="steipete" title="steipete"/></a> <a href="https://github.com/joaohlisboa"><img src="https://avatars.githubusercontent.com/u/8200873?v=4&s=48" width="48" height="48" alt="joaohlisboa" title="joaohlisboa"/></a> <a href="https://github.com/mneves75"><img src="https://avatars.githubusercontent.com/u/2423436?v=4&s=48" width="48" height="48" alt="mneves75" title="mneves75"/></a> <a href="https://github.com/rahthakor"><img src="https://avatars.githubusercontent.com/u/8470553?v=4&s=48" width="48" height="48" alt="rahthakor" title="rahthakor"/></a> <a href="https://github.com/joshp123"><img src="https://avatars.githubusercontent.com/u/1497361?v=4&s=48" width="48" height="48" alt="joshp123" title="joshp123"/></a> <a href="https://github.com/mukhtharcm"><img src="https://avatars.githubusercontent.com/u/56378562?v=4&s=48" width="48" height="48" alt="mukhtharcm" title="mukhtharcm"/></a> <a href="https://github.com/maxsumrall"><img src="https://avatars.githubusercontent.com/u/628843?v=4&s=48" width="48" height="48" alt="maxsumrall" title="maxsumrall"/></a> <a href="https://github.com/xadenryan"><img src="https://avatars.githubusercontent.com/u/165437834?v=4&s=48" width="48" height="48" alt="xadenryan" title="xadenryan"/></a> <a href="https://github.com/tobiasbischoff"><img src="https://avatars.githubusercontent.com/u/711564?v=4&s=48" width="48" height="48" alt="Tobias Bischoff" title="Tobias Bischoff"/></a> <a href="https://github.com/hsrvc"><img src="https://avatars.githubusercontent.com/u/129702169?v=4&s=48" width="48" height="48" alt="hsrvc" title="hsrvc"/></a>
-  <a href="https://github.com/magimetal"><img src="https://avatars.githubusercontent.com/u/36491250?v=4&s=48" width="48" height="48" alt="magimetal" title="magimetal"/></a> <a href="https://github.com/NicholasSpisak"><img src="https://avatars.githubusercontent.com/u/129075147?v=4&s=48" width="48" height="48" alt="NicholasSpisak" title="NicholasSpisak"/></a> <a href="https://github.com/AbhisekBasu1"><img src="https://avatars.githubusercontent.com/u/40645221?v=4&s=48" width="48" height="48" alt="abhisekbasu1" title="abhisekbasu1"/></a> <a href="https://github.com/claude"><img src="https://avatars.githubusercontent.com/u/81847?v=4&s=48" width="48" height="48" alt="claude" title="claude"/></a> <a href="https://github.com/jamesgroat"><img src="https://avatars.githubusercontent.com/u/2634024?v=4&s=48" width="48" height="48" alt="jamesgroat" title="jamesgroat"/></a> <a href="https://github.com/dantelex"><img src="https://avatars.githubusercontent.com/u/631543?v=4&s=48" width="48" height="48" alt="dantelex" title="dantelex"/></a> <a href="https://github.com/daveonkels"><img src="https://avatars.githubusercontent.com/u/533642?v=4&s=48" width="48" height="48" alt="daveonkels" title="daveonkels"/></a> <a href="https://github.com/radek-paclt"><img src="https://avatars.githubusercontent.com/u/50451445?v=4&s=48" width="48" height="48" alt="radek-paclt" title="radek-paclt"/></a> <a href="https://github.com/jeffersonwarrior"><img src="https://avatars.githubusercontent.com/u/89030989?v=4&s=48" width="48" height="48" alt="jeffersonwarrior" title="jeffersonwarrior"/></a> <a href="https://github.com/mteam88"><img src="https://avatars.githubusercontent.com/u/84196639?v=4&s=48" width="48" height="48" alt="mteam88" title="mteam88"/></a>
-  <a href="https://github.com/omniwired"><img src="https://avatars.githubusercontent.com/u/322761?v=4&s=48" width="48" height="48" alt="Eng. Juan Combetto" title="Eng. Juan Combetto"/></a> <a href="https://github.com/dbhurley"><img src="https://avatars.githubusercontent.com/u/5251425?v=4&s=48" width="48" height="48" alt="dbhurley" title="dbhurley"/></a> <a href="https://github.com/mbelinky"><img src="https://avatars.githubusercontent.com/u/132747814?v=4&s=48" width="48" height="48" alt="Mariano Belinky" title="Mariano Belinky"/></a> <a href="https://github.com/julianengel"><img src="https://avatars.githubusercontent.com/u/10634231?v=4&s=48" width="48" height="48" alt="julianengel" title="julianengel"/></a> <a href="https://github.com/benithors"><img src="https://avatars.githubusercontent.com/u/20652882?v=4&s=48" width="48" height="48" alt="benithors" title="benithors"/></a> <a href="https://github.com/sreekaransrinath"><img src="https://avatars.githubusercontent.com/u/50989977?v=4&s=48" width="48" height="48" alt="sreekaransrinath" title="sreekaransrinath"/></a> <a href="https://github.com/gupsammy"><img src="https://avatars.githubusercontent.com/u/20296019?v=4&s=48" width="48" height="48" alt="gupsammy" title="gupsammy"/></a> <a href="https://github.com/cristip73"><img src="https://avatars.githubusercontent.com/u/24499421?v=4&s=48" width="48" height="48" alt="cristip73" title="cristip73"/></a> <a href="https://github.com/nachoiacovino"><img src="https://avatars.githubusercontent.com/u/50103937?v=4&s=48" width="48" height="48" alt="nachoiacovino" title="nachoiacovino"/></a> <a href="https://github.com/vsabavat"><img src="https://avatars.githubusercontent.com/u/50385532?v=4&s=48" width="48" height="48" alt="Vasanth Rao Naik Sabavat" title="Vasanth Rao Naik Sabavat"/></a>
-  <a href="https://github.com/lc0rp"><img src="https://avatars.githubusercontent.com/u/2609441?v=4&s=48" width="48" height="48" alt="lc0rp" title="lc0rp"/></a> <a href="https://github.com/scald"><img src="https://avatars.githubusercontent.com/u/1215913?v=4&s=48" width="48" height="48" alt="scald" title="scald"/></a> <a href="https://github.com/andranik-sahakyan"><img src="https://avatars.githubusercontent.com/u/8908029?v=4&s=48" width="48" height="48" alt="andranik-sahakyan" title="andranik-sahakyan"/></a> <a href="https://github.com/Nachx639"><img src="https://avatars.githubusercontent.com/u/71144023?v=4&s=48" width="48" height="48" alt="nachx639" title="nachx639"/></a> <a href="https://github.com/davidguttman"><img src="https://avatars.githubusercontent.com/u/431696?v=4&s=48" width="48" height="48" alt="davidguttman" title="davidguttman"/></a> <a href="https://github.com/sircrumpet"><img src="https://avatars.githubusercontent.com/u/4436535?v=4&s=48" width="48" height="48" alt="sircrumpet" title="sircrumpet"/></a> <a href="https://github.com/peschee"><img src="https://avatars.githubusercontent.com/u/63866?v=4&s=48" width="48" height="48" alt="peschee" title="peschee"/></a> <a href="https://github.com/rafaelreis-r"><img src="https://avatars.githubusercontent.com/u/57492577?v=4&s=48" width="48" height="48" alt="rafaelreis-r" title="rafaelreis-r"/></a> <a href="https://github.com/meaningfool"><img src="https://avatars.githubusercontent.com/u/2862331?v=4&s=48" width="48" height="48" alt="meaningfool" title="meaningfool"/></a> <a href="https://github.com/ratulsarna"><img src="https://avatars.githubusercontent.com/u/105903728?v=4&s=48" width="48" height="48" alt="ratulsarna" title="ratulsarna"/></a>
-  <a href="https://github.com/lutr0"><img src="https://avatars.githubusercontent.com/u/76906369?v=4&s=48" width="48" height="48" alt="lutr0" title="lutr0"/></a> <a href="https://github.com/thewilloftheshadow"><img src="https://avatars.githubusercontent.com/u/35580099?v=4&s=48" width="48" height="48" alt="thewilloftheshadow" title="thewilloftheshadow"/></a> <a href="https://github.com/emanuelst"><img src="https://avatars.githubusercontent.com/u/9994339?v=4&s=48" width="48" height="48" alt="emanuelst" title="emanuelst"/></a> <a href="https://github.com/KristijanJovanovski"><img src="https://avatars.githubusercontent.com/u/8942284?v=4&s=48" width="48" height="48" alt="KristijanJovanovski" title="KristijanJovanovski"/></a> <a href="https://github.com/osolmaz"><img src="https://avatars.githubusercontent.com/u/2453968?v=4&s=48" width="48" height="48" alt="osolmaz" title="osolmaz"/></a> <a href="https://github.com/kiranjd"><img src="https://avatars.githubusercontent.com/u/25822851?v=4&s=48" width="48" height="48" alt="kiranjd" title="kiranjd"/></a> <a href="https://github.com/sebslight"><img src="https://avatars.githubusercontent.com/u/19554889?v=4&s=48" width="48" height="48" alt="Sebastian Barrios" title="Sebastian Barrios"/></a> <a href="https://github.com/search?q=sheeek"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="sheeek" title="sheeek"/></a> <a href="https://github.com/onutc"><img src="https://avatars.githubusercontent.com/u/152018508?v=4&s=48" width="48" height="48" alt="onutc" title="onutc"/></a> <a href="https://github.com/CashWilliams"><img src="https://avatars.githubusercontent.com/u/613573?v=4&s=48" width="48" height="48" alt="CashWilliams" title="CashWilliams"/></a>
-  <a href="https://github.com/ManuelHettich"><img src="https://avatars.githubusercontent.com/u/17690367?v=4&s=48" width="48" height="48" alt="manuelhettich" title="manuelhettich"/></a> <a href="https://github.com/minghinmatthewlam"><img src="https://avatars.githubusercontent.com/u/14224566?v=4&s=48" width="48" height="48" alt="minghinmatthewlam" title="minghinmatthewlam"/></a> <a href="https://github.com/myfunc"><img src="https://avatars.githubusercontent.com/u/19294627?v=4&s=48" width="48" height="48" alt="myfunc" title="myfunc"/></a> <a href="https://github.com/buddyh"><img src="https://avatars.githubusercontent.com/u/31752869?v=4&s=48" width="48" height="48" alt="buddyh" title="buddyh"/></a> <a href="https://github.com/mcinteerj"><img src="https://avatars.githubusercontent.com/u/3613653?v=4&s=48" width="48" height="48" alt="mcinteerj" title="mcinteerj"/></a> <a href="https://github.com/timkrase"><img src="https://avatars.githubusercontent.com/u/38947626?v=4&s=48" width="48" height="48" alt="timkrase" title="timkrase"/></a> <a href="https://github.com/obviyus"><img src="https://avatars.githubusercontent.com/u/22031114?v=4&s=48" width="48" height="48" alt="obviyus" title="obviyus"/></a> <a href="https://github.com/azade-c"><img src="https://avatars.githubusercontent.com/u/252790079?v=4&s=48" width="48" height="48" alt="azade-c" title="azade-c"/></a> <a href="https://github.com/bjesuiter"><img src="https://avatars.githubusercontent.com/u/2365676?v=4&s=48" width="48" height="48" alt="bjesuiter" title="bjesuiter"/></a> <a href="https://github.com/superman32432432"><img src="https://avatars.githubusercontent.com/u/7228420?v=4&s=48" width="48" height="48" alt="superman32432432" title="superman32432432"/></a>
-  <a href="https://github.com/search?q=Yurii%20Chukhlib"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Yurii Chukhlib" title="Yurii Chukhlib"/></a> <a href="https://github.com/antons"><img src="https://avatars.githubusercontent.com/u/129705?v=4&s=48" width="48" height="48" alt="antons" title="antons"/></a> <a href="https://github.com/austinm911"><img src="https://avatars.githubusercontent.com/u/31991302?v=4&s=48" width="48" height="48" alt="austinm911" title="austinm911"/></a> <a href="https://github.com/apps/blacksmith-sh"><img src="https://avatars.githubusercontent.com/in/807020?v=4&s=48" width="48" height="48" alt="blacksmith-sh[bot]" title="blacksmith-sh[bot]"/></a> <a href="https://github.com/imfing"><img src="https://avatars.githubusercontent.com/u/5097752?v=4&s=48" width="48" height="48" alt="imfing" title="imfing"/></a> <a href="https://github.com/jarvis-medmatic"><img src="https://avatars.githubusercontent.com/u/252428873?v=4&s=48" width="48" height="48" alt="jarvis-medmatic" title="jarvis-medmatic"/></a> <a href="https://github.com/mahmoudashraf93"><img src="https://avatars.githubusercontent.com/u/9130129?v=4&s=48" width="48" height="48" alt="mahmoudashraf93" title="mahmoudashraf93"/></a> <a href="https://github.com/petter-b"><img src="https://avatars.githubusercontent.com/u/62076402?v=4&s=48" width="48" height="48" alt="petter-b" title="petter-b"/></a> <a href="https://github.com/pkrmf"><img src="https://avatars.githubusercontent.com/u/1714267?v=4&s=48" width="48" height="48" alt="pkrmf" title="pkrmf"/></a> <a href="https://github.com/RandyVentures"><img src="https://avatars.githubusercontent.com/u/149904821?v=4&s=48" width="48" height="48" alt="RandyVentures" title="RandyVentures"/></a>
-  <a href="https://github.com/dan-dr"><img src="https://avatars.githubusercontent.com/u/6669808?v=4&s=48" width="48" height="48" alt="dan-dr" title="dan-dr"/></a> <a href="https://github.com/HeimdallStrategy"><img src="https://avatars.githubusercontent.com/u/223014405?v=4&s=48" width="48" height="48" alt="HeimdallStrategy" title="HeimdallStrategy"/></a> <a href="https://github.com/jalehman"><img src="https://avatars.githubusercontent.com/u/550978?v=4&s=48" width="48" height="48" alt="jalehman" title="jalehman"/></a> <a href="https://github.com/jonasjancarik"><img src="https://avatars.githubusercontent.com/u/2459191?v=4&s=48" width="48" height="48" alt="jonasjancarik" title="jonasjancarik"/></a> <a href="https://github.com/search?q=Keith%20the%20Silly%20Goose"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Keith the Silly Goose" title="Keith the Silly Goose"/></a> <a href="https://github.com/search?q=L36%20Server"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="L36 Server" title="L36 Server"/></a> <a href="https://github.com/neist"><img src="https://avatars.githubusercontent.com/u/1029724?v=4&s=48" width="48" height="48" alt="neist" title="neist"/></a> <a href="https://github.com/gabriel-trigo"><img src="https://avatars.githubusercontent.com/u/38991125?v=4&s=48" width="48" height="48" alt="gabriel-trigo" title="gabriel-trigo"/></a> <a href="https://github.com/Iamadig"><img src="https://avatars.githubusercontent.com/u/102129234?v=4&s=48" width="48" height="48" alt="iamadig" title="iamadig"/></a> <a href="https://github.com/search?q=Kit"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Kit" title="Kit"/></a>
-  <a href="https://github.com/koala73"><img src="https://avatars.githubusercontent.com/u/996596?v=4&s=48" width="48" height="48" alt="koala73" title="koala73"/></a> <a href="https://github.com/manmal"><img src="https://avatars.githubusercontent.com/u/142797?v=4&s=48" width="48" height="48" alt="manmal" title="manmal"/></a> <a href="https://github.com/ogulcancelik"><img src="https://avatars.githubusercontent.com/u/7064011?v=4&s=48" width="48" height="48" alt="ogulcancelik" title="ogulcancelik"/></a> <a href="https://github.com/pasogott"><img src="https://avatars.githubusercontent.com/u/23458152?v=4&s=48" width="48" height="48" alt="pasogott" title="pasogott"/></a> <a href="https://github.com/petradonka"><img src="https://avatars.githubusercontent.com/u/7353770?v=4&s=48" width="48" height="48" alt="petradonka" title="petradonka"/></a> <a href="https://github.com/VACInc"><img src="https://avatars.githubusercontent.com/u/3279061?v=4&s=48" width="48" height="48" alt="VACInc" title="VACInc"/></a> <a href="https://github.com/zats"><img src="https://avatars.githubusercontent.com/u/2688806?v=4&s=48" width="48" height="48" alt="zats" title="zats"/></a> <a href="https://github.com/search?q=Chris%20Taylor"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Chris Taylor" title="Chris Taylor"/></a> <a href="https://github.com/djangonavarro220"><img src="https://avatars.githubusercontent.com/u/251162586?v=4&s=48" width="48" height="48" alt="Django Navarro" title="Django Navarro"/></a> <a href="https://github.com/ngutman"><img src="https://avatars.githubusercontent.com/u/1540134?v=4&s=48" width="48" height="48" alt="ngutman" title="ngutman"/></a>
-  <a href="https://github.com/pcty-nextgen-service-account"><img src="https://avatars.githubusercontent.com/u/112553441?v=4&s=48" width="48" height="48" alt="pcty-nextgen-service-account" title="pcty-nextgen-service-account"/></a> <a href="https://github.com/rubyrunsstuff"><img src="https://avatars.githubusercontent.com/u/246602379?v=4&s=48" width="48" height="48" alt="rubyrunsstuff" title="rubyrunsstuff"/></a> <a href="https://github.com/Syhids"><img src="https://avatars.githubusercontent.com/u/671202?v=4&s=48" width="48" height="48" alt="Syhids" title="Syhids"/></a> <a href="https://github.com/search?q=Aaron%20Konyer"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Aaron Konyer" title="Aaron Konyer"/></a> <a href="https://github.com/danielz1z"><img src="https://avatars.githubusercontent.com/u/235270390?v=4&s=48" width="48" height="48" alt="danielz1z" title="danielz1z"/></a> <a href="https://github.com/erik-agens"><img src="https://avatars.githubusercontent.com/u/80908960?v=4&s=48" width="48" height="48" alt="erik-agens" title="erik-agens"/></a> <a href="https://github.com/erikpr1994"><img src="https://avatars.githubusercontent.com/u/6299331?v=4&s=48" width="48" height="48" alt="erikpr1994" title="erikpr1994"/></a> <a href="https://github.com/fcatuhe"><img src="https://avatars.githubusercontent.com/u/17382215?v=4&s=48" width="48" height="48" alt="fcatuhe" title="fcatuhe"/></a> <a href="https://github.com/henrino3"><img src="https://avatars.githubusercontent.com/u/4260288?v=4&s=48" width="48" height="48" alt="henrino3" title="henrino3"/></a> <a href="https://github.com/jayhickey"><img src="https://avatars.githubusercontent.com/u/1676460?v=4&s=48" width="48" height="48" alt="jayhickey" title="jayhickey"/></a>
-  <a href="https://github.com/jdrhyne"><img src="https://avatars.githubusercontent.com/u/7828464?v=4&s=48" width="48" height="48" alt="Jonathan D. Rhyne (DJ-D)" title="Jonathan D. Rhyne (DJ-D)"/></a> <a href="https://github.com/juanpablodlc"><img src="https://avatars.githubusercontent.com/u/92012363?v=4&s=48" width="48" height="48" alt="juanpablodlc" title="juanpablodlc"/></a> <a href="https://github.com/jverdi"><img src="https://avatars.githubusercontent.com/u/345050?v=4&s=48" width="48" height="48" alt="jverdi" title="jverdi"/></a> <a href="https://github.com/mickahouan"><img src="https://avatars.githubusercontent.com/u/31423109?v=4&s=48" width="48" height="48" alt="mickahouan" title="mickahouan"/></a> <a href="https://github.com/mitschabaude-bot"><img src="https://avatars.githubusercontent.com/u/247582884?v=4&s=48" width="48" height="48" alt="mitschabaude-bot" title="mitschabaude-bot"/></a> <a href="https://github.com/mjrussell"><img src="https://avatars.githubusercontent.com/u/1641895?v=4&s=48" width="48" height="48" alt="mjrussell" title="mjrussell"/></a> <a href="https://github.com/oswalpalash"><img src="https://avatars.githubusercontent.com/u/6431196?v=4&s=48" width="48" height="48" alt="oswalpalash" title="oswalpalash"/></a> <a href="https://github.com/p6l-richard"><img src="https://avatars.githubusercontent.com/u/18185649?v=4&s=48" width="48" height="48" alt="p6l-richard" title="p6l-richard"/></a> <a href="https://github.com/philipp-spiess"><img src="https://avatars.githubusercontent.com/u/458591?v=4&s=48" width="48" height="48" alt="philipp-spiess" title="philipp-spiess"/></a> <a href="https://github.com/roshanasingh4"><img src="https://avatars.githubusercontent.com/u/88576930?v=4&s=48" width="48" height="48" alt="roshanasingh4" title="roshanasingh4"/></a>
+  <a href="https://github.com/magimetal"><img src="https://avatars.githubusercontent.com/u/36491250?v=4&s=48" width="48" height="48" alt="magimetal" title="magimetal"/></a> <a href="https://github.com/meaningfool"><img src="https://avatars.githubusercontent.com/u/2862331?v=4&s=48" width="48" height="48" alt="meaningfool" title="meaningfool"/></a> <a href="https://github.com/NicholasSpisak"><img src="https://avatars.githubusercontent.com/u/129075147?v=4&s=48" width="48" height="48" alt="NicholasSpisak" title="NicholasSpisak"/></a> <a href="https://github.com/AbhisekBasu1"><img src="https://avatars.githubusercontent.com/u/40645221?v=4&s=48" width="48" height="48" alt="abhisekbasu1" title="abhisekbasu1"/></a> <a href="https://github.com/claude"><img src="https://avatars.githubusercontent.com/u/81847?v=4&s=48" width="48" height="48" alt="claude" title="claude"/></a> <a href="https://github.com/jamesgroat"><img src="https://avatars.githubusercontent.com/u/2634024?v=4&s=48" width="48" height="48" alt="jamesgroat" title="jamesgroat"/></a> <a href="https://github.com/Hyaxia"><img src="https://avatars.githubusercontent.com/u/36747317?v=4&s=48" width="48" height="48" alt="Hyaxia" title="Hyaxia"/></a> <a href="https://github.com/dantelex"><img src="https://avatars.githubusercontent.com/u/631543?v=4&s=48" width="48" height="48" alt="dantelex" title="dantelex"/></a> <a href="https://github.com/daveonkels"><img src="https://avatars.githubusercontent.com/u/533642?v=4&s=48" width="48" height="48" alt="daveonkels" title="daveonkels"/></a> <a href="https://github.com/vrknetha"><img src="https://avatars.githubusercontent.com/u/20596261?v=4&s=48" width="48" height="48" alt="vrknetha" title="vrknetha"/></a>
+  <a href="https://github.com/radek-paclt"><img src="https://avatars.githubusercontent.com/u/50451445?v=4&s=48" width="48" height="48" alt="radek-paclt" title="radek-paclt"/></a> <a href="https://github.com/mteam88"><img src="https://avatars.githubusercontent.com/u/84196639?v=4&s=48" width="48" height="48" alt="mteam88" title="mteam88"/></a> <a href="https://github.com/omniwired"><img src="https://avatars.githubusercontent.com/u/322761?v=4&s=48" width="48" height="48" alt="Eng. Juan Combetto" title="Eng. Juan Combetto"/></a> <a href="https://github.com/dbhurley"><img src="https://avatars.githubusercontent.com/u/5251425?v=4&s=48" width="48" height="48" alt="dbhurley" title="dbhurley"/></a> <a href="https://github.com/mbelinky"><img src="https://avatars.githubusercontent.com/u/132747814?v=4&s=48" width="48" height="48" alt="Mariano Belinky" title="Mariano Belinky"/></a> <a href="https://github.com/julianengel"><img src="https://avatars.githubusercontent.com/u/10634231?v=4&s=48" width="48" height="48" alt="julianengel" title="julianengel"/></a> <a href="https://github.com/benithors"><img src="https://avatars.githubusercontent.com/u/20652882?v=4&s=48" width="48" height="48" alt="benithors" title="benithors"/></a> <a href="https://github.com/sreekaransrinath"><img src="https://avatars.githubusercontent.com/u/50989977?v=4&s=48" width="48" height="48" alt="sreekaransrinath" title="sreekaransrinath"/></a> <a href="https://github.com/gupsammy"><img src="https://avatars.githubusercontent.com/u/20296019?v=4&s=48" width="48" height="48" alt="gupsammy" title="gupsammy"/></a> <a href="https://github.com/cristip73"><img src="https://avatars.githubusercontent.com/u/24499421?v=4&s=48" width="48" height="48" alt="cristip73" title="cristip73"/></a>
+  <a href="https://github.com/nachoiacovino"><img src="https://avatars.githubusercontent.com/u/50103937?v=4&s=48" width="48" height="48" alt="nachoiacovino" title="nachoiacovino"/></a> <a href="https://github.com/vsabavat"><img src="https://avatars.githubusercontent.com/u/50385532?v=4&s=48" width="48" height="48" alt="Vasanth Rao Naik Sabavat" title="Vasanth Rao Naik Sabavat"/></a> <a href="https://github.com/lc0rp"><img src="https://avatars.githubusercontent.com/u/2609441?v=4&s=48" width="48" height="48" alt="lc0rp" title="lc0rp"/></a> <a href="https://github.com/scald"><img src="https://avatars.githubusercontent.com/u/1215913?v=4&s=48" width="48" height="48" alt="scald" title="scald"/></a> <a href="https://github.com/andranik-sahakyan"><img src="https://avatars.githubusercontent.com/u/8908029?v=4&s=48" width="48" height="48" alt="andranik-sahakyan" title="andranik-sahakyan"/></a> <a href="https://github.com/Nachx639"><img src="https://avatars.githubusercontent.com/u/71144023?v=4&s=48" width="48" height="48" alt="nachx639" title="nachx639"/></a> <a href="https://github.com/davidguttman"><img src="https://avatars.githubusercontent.com/u/431696?v=4&s=48" width="48" height="48" alt="davidguttman" title="davidguttman"/></a> <a href="https://github.com/sleontenko"><img src="https://avatars.githubusercontent.com/u/7135949?v=4&s=48" width="48" height="48" alt="sleontenko" title="sleontenko"/></a> <a href="https://github.com/sircrumpet"><img src="https://avatars.githubusercontent.com/u/4436535?v=4&s=48" width="48" height="48" alt="sircrumpet" title="sircrumpet"/></a> <a href="https://github.com/peschee"><img src="https://avatars.githubusercontent.com/u/63866?v=4&s=48" width="48" height="48" alt="peschee" title="peschee"/></a>
+  <a href="https://github.com/rafaelreis-r"><img src="https://avatars.githubusercontent.com/u/57492577?v=4&s=48" width="48" height="48" alt="rafaelreis-r" title="rafaelreis-r"/></a> <a href="https://github.com/ratulsarna"><img src="https://avatars.githubusercontent.com/u/105903728?v=4&s=48" width="48" height="48" alt="ratulsarna" title="ratulsarna"/></a> <a href="https://github.com/lutr0"><img src="https://avatars.githubusercontent.com/u/76906369?v=4&s=48" width="48" height="48" alt="lutr0" title="lutr0"/></a> <a href="https://github.com/thewilloftheshadow"><img src="https://avatars.githubusercontent.com/u/35580099?v=4&s=48" width="48" height="48" alt="thewilloftheshadow" title="thewilloftheshadow"/></a> <a href="https://github.com/emanuelst"><img src="https://avatars.githubusercontent.com/u/9994339?v=4&s=48" width="48" height="48" alt="emanuelst" title="emanuelst"/></a> <a href="https://github.com/KristijanJovanovski"><img src="https://avatars.githubusercontent.com/u/8942284?v=4&s=48" width="48" height="48" alt="KristijanJovanovski" title="KristijanJovanovski"/></a> <a href="https://github.com/CashWilliams"><img src="https://avatars.githubusercontent.com/u/613573?v=4&s=48" width="48" height="48" alt="CashWilliams" title="CashWilliams"/></a> <a href="https://github.com/osolmaz"><img src="https://avatars.githubusercontent.com/u/2453968?v=4&s=48" width="48" height="48" alt="osolmaz" title="osolmaz"/></a> <a href="https://github.com/kiranjd"><img src="https://avatars.githubusercontent.com/u/25822851?v=4&s=48" width="48" height="48" alt="kiranjd" title="kiranjd"/></a> <a href="https://github.com/sebslight"><img src="https://avatars.githubusercontent.com/u/19554889?v=4&s=48" width="48" height="48" alt="sebslight" title="sebslight"/></a>
+  <a href="https://github.com/search?q=sheeek"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="sheeek" title="sheeek"/></a> <a href="https://github.com/onutc"><img src="https://avatars.githubusercontent.com/u/152018508?v=4&s=48" width="48" height="48" alt="onutc" title="onutc"/></a> <a href="https://github.com/ManuelHettich"><img src="https://avatars.githubusercontent.com/u/17690367?v=4&s=48" width="48" height="48" alt="manuelhettich" title="manuelhettich"/></a> <a href="https://github.com/minghinmatthewlam"><img src="https://avatars.githubusercontent.com/u/14224566?v=4&s=48" width="48" height="48" alt="minghinmatthewlam" title="minghinmatthewlam"/></a> <a href="https://github.com/myfunc"><img src="https://avatars.githubusercontent.com/u/19294627?v=4&s=48" width="48" height="48" alt="myfunc" title="myfunc"/></a> <a href="https://github.com/buddyh"><img src="https://avatars.githubusercontent.com/u/31752869?v=4&s=48" width="48" height="48" alt="buddyh" title="buddyh"/></a> <a href="https://github.com/mcinteerj"><img src="https://avatars.githubusercontent.com/u/3613653?v=4&s=48" width="48" height="48" alt="mcinteerj" title="mcinteerj"/></a> <a href="https://github.com/timkrase"><img src="https://avatars.githubusercontent.com/u/38947626?v=4&s=48" width="48" height="48" alt="timkrase" title="timkrase"/></a> <a href="https://github.com/obviyus"><img src="https://avatars.githubusercontent.com/u/22031114?v=4&s=48" width="48" height="48" alt="obviyus" title="obviyus"/></a> <a href="https://github.com/azade-c"><img src="https://avatars.githubusercontent.com/u/252790079?v=4&s=48" width="48" height="48" alt="azade-c" title="azade-c"/></a>
+  <a href="https://github.com/danielz1z"><img src="https://avatars.githubusercontent.com/u/235270390?v=4&s=48" width="48" height="48" alt="danielz1z" title="danielz1z"/></a> <a href="https://github.com/j1philli"><img src="https://avatars.githubusercontent.com/u/3744255?v=4&s=48" width="48" height="48" alt="Josh Phillips" title="Josh Phillips"/></a> <a href="https://github.com/bjesuiter"><img src="https://avatars.githubusercontent.com/u/2365676?v=4&s=48" width="48" height="48" alt="bjesuiter" title="bjesuiter"/></a> <a href="https://github.com/superman32432432"><img src="https://avatars.githubusercontent.com/u/7228420?v=4&s=48" width="48" height="48" alt="superman32432432" title="superman32432432"/></a> <a href="https://github.com/search?q=Yurii%20Chukhlib"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Yurii Chukhlib" title="Yurii Chukhlib"/></a> <a href="https://github.com/roshanasingh4"><img src="https://avatars.githubusercontent.com/u/88576930?v=4&s=48" width="48" height="48" alt="roshanasingh4" title="roshanasingh4"/></a> <a href="https://github.com/antons"><img src="https://avatars.githubusercontent.com/u/129705?v=4&s=48" width="48" height="48" alt="antons" title="antons"/></a> <a href="https://github.com/austinm911"><img src="https://avatars.githubusercontent.com/u/31991302?v=4&s=48" width="48" height="48" alt="austinm911" title="austinm911"/></a> <a href="https://github.com/apps/blacksmith-sh"><img src="https://avatars.githubusercontent.com/in/807020?v=4&s=48" width="48" height="48" alt="blacksmith-sh[bot]" title="blacksmith-sh[bot]"/></a> <a href="https://github.com/grp06"><img src="https://avatars.githubusercontent.com/u/1573959?v=4&s=48" width="48" height="48" alt="grp06" title="grp06"/></a>
+  <a href="https://github.com/HeimdallStrategy"><img src="https://avatars.githubusercontent.com/u/223014405?v=4&s=48" width="48" height="48" alt="HeimdallStrategy" title="HeimdallStrategy"/></a> <a href="https://github.com/imfing"><img src="https://avatars.githubusercontent.com/u/5097752?v=4&s=48" width="48" height="48" alt="imfing" title="imfing"/></a> <a href="https://github.com/jarvis-medmatic"><img src="https://avatars.githubusercontent.com/u/252428873?v=4&s=48" width="48" height="48" alt="jarvis-medmatic" title="jarvis-medmatic"/></a> <a href="https://github.com/mahmoudashraf93"><img src="https://avatars.githubusercontent.com/u/9130129?v=4&s=48" width="48" height="48" alt="mahmoudashraf93" title="mahmoudashraf93"/></a> <a href="https://github.com/petter-b"><img src="https://avatars.githubusercontent.com/u/62076402?v=4&s=48" width="48" height="48" alt="petter-b" title="petter-b"/></a> <a href="https://github.com/pkrmf"><img src="https://avatars.githubusercontent.com/u/1714267?v=4&s=48" width="48" height="48" alt="pkrmf" title="pkrmf"/></a> <a href="https://github.com/RandyVentures"><img src="https://avatars.githubusercontent.com/u/149904821?v=4&s=48" width="48" height="48" alt="RandyVentures" title="RandyVentures"/></a> <a href="https://github.com/dan-dr"><img src="https://avatars.githubusercontent.com/u/6669808?v=4&s=48" width="48" height="48" alt="dan-dr" title="dan-dr"/></a> <a href="https://github.com/erikpr1994"><img src="https://avatars.githubusercontent.com/u/6299331?v=4&s=48" width="48" height="48" alt="erikpr1994" title="erikpr1994"/></a> <a href="https://github.com/jalehman"><img src="https://avatars.githubusercontent.com/u/550978?v=4&s=48" width="48" height="48" alt="jalehman" title="jalehman"/></a>
+  <a href="https://github.com/jonasjancarik"><img src="https://avatars.githubusercontent.com/u/2459191?v=4&s=48" width="48" height="48" alt="jonasjancarik" title="jonasjancarik"/></a> <a href="https://github.com/search?q=Keith%20the%20Silly%20Goose"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Keith the Silly Goose" title="Keith the Silly Goose"/></a> <a href="https://github.com/search?q=L36%20Server"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="L36 Server" title="L36 Server"/></a> <a href="https://github.com/mitschabaude-bot"><img src="https://avatars.githubusercontent.com/u/247582884?v=4&s=48" width="48" height="48" alt="mitschabaude-bot" title="mitschabaude-bot"/></a> <a href="https://github.com/neist"><img src="https://avatars.githubusercontent.com/u/1029724?v=4&s=48" width="48" height="48" alt="neist" title="neist"/></a> <a href="https://github.com/search?q=Friederike%20Seiler"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Friederike Seiler" title="Friederike Seiler"/></a> <a href="https://github.com/gabriel-trigo"><img src="https://avatars.githubusercontent.com/u/38991125?v=4&s=48" width="48" height="48" alt="gabriel-trigo" title="gabriel-trigo"/></a> <a href="https://github.com/Iamadig"><img src="https://avatars.githubusercontent.com/u/102129234?v=4&s=48" width="48" height="48" alt="iamadig" title="iamadig"/></a> <a href="https://github.com/search?q=Kit"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Kit" title="Kit"/></a> <a href="https://github.com/koala73"><img src="https://avatars.githubusercontent.com/u/996596?v=4&s=48" width="48" height="48" alt="koala73" title="koala73"/></a>
+  <a href="https://github.com/manmal"><img src="https://avatars.githubusercontent.com/u/142797?v=4&s=48" width="48" height="48" alt="manmal" title="manmal"/></a> <a href="https://github.com/ngutman"><img src="https://avatars.githubusercontent.com/u/1540134?v=4&s=48" width="48" height="48" alt="ngutman" title="ngutman"/></a> <a href="https://github.com/ogulcancelik"><img src="https://avatars.githubusercontent.com/u/7064011?v=4&s=48" width="48" height="48" alt="ogulcancelik" title="ogulcancelik"/></a> <a href="https://github.com/pasogott"><img src="https://avatars.githubusercontent.com/u/23458152?v=4&s=48" width="48" height="48" alt="pasogott" title="pasogott"/></a> <a href="https://github.com/petradonka"><img src="https://avatars.githubusercontent.com/u/7353770?v=4&s=48" width="48" height="48" alt="petradonka" title="petradonka"/></a> <a href="https://github.com/VACInc"><img src="https://avatars.githubusercontent.com/u/3279061?v=4&s=48" width="48" height="48" alt="VACInc" title="VACInc"/></a> <a href="https://github.com/zats"><img src="https://avatars.githubusercontent.com/u/2688806?v=4&s=48" width="48" height="48" alt="zats" title="zats"/></a> <a href="https://github.com/search?q=Chris%20Taylor"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Chris Taylor" title="Chris Taylor"/></a> <a href="https://github.com/djangonavarro220"><img src="https://avatars.githubusercontent.com/u/251162586?v=4&s=48" width="48" height="48" alt="Django Navarro" title="Django Navarro"/></a> <a href="https://github.com/pcty-nextgen-service-account"><img src="https://avatars.githubusercontent.com/u/112553441?v=4&s=48" width="48" height="48" alt="pcty-nextgen-service-account" title="pcty-nextgen-service-account"/></a>
+  <a href="https://github.com/rubyrunsstuff"><img src="https://avatars.githubusercontent.com/u/246602379?v=4&s=48" width="48" height="48" alt="rubyrunsstuff" title="rubyrunsstuff"/></a> <a href="https://github.com/Syhids"><img src="https://avatars.githubusercontent.com/u/671202?v=4&s=48" width="48" height="48" alt="Syhids" title="Syhids"/></a> <a href="https://github.com/search?q=Aaron%20Konyer"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Aaron Konyer" title="Aaron Konyer"/></a> <a href="https://github.com/erik-agens"><img src="https://avatars.githubusercontent.com/u/80908960?v=4&s=48" width="48" height="48" alt="erik-agens" title="erik-agens"/></a> <a href="https://github.com/evalexpr"><img src="https://avatars.githubusercontent.com/u/23485511?v=4&s=48" width="48" height="48" alt="evalexpr" title="evalexpr"/></a> <a href="https://github.com/fcatuhe"><img src="https://avatars.githubusercontent.com/u/17382215?v=4&s=48" width="48" height="48" alt="fcatuhe" title="fcatuhe"/></a> <a href="https://github.com/gumadeiras"><img src="https://avatars.githubusercontent.com/u/5599352?v=4&s=48" width="48" height="48" alt="gumadeiras" title="gumadeiras"/></a> <a href="https://github.com/henrino3"><img src="https://avatars.githubusercontent.com/u/4260288?v=4&s=48" width="48" height="48" alt="henrino3" title="henrino3"/></a> <a href="https://github.com/jayhickey"><img src="https://avatars.githubusercontent.com/u/1676460?v=4&s=48" width="48" height="48" alt="jayhickey" title="jayhickey"/></a> <a href="https://github.com/jeffersonwarrior"><img src="https://avatars.githubusercontent.com/u/89030989?v=4&s=48" width="48" height="48" alt="jeffersonwarrior" title="jeffersonwarrior"/></a>
+  <a href="https://github.com/search?q=jeffersonwarrior"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="jeffersonwarrior" title="jeffersonwarrior"/></a> <a href="https://github.com/jdrhyne"><img src="https://avatars.githubusercontent.com/u/7828464?v=4&s=48" width="48" height="48" alt="Jonathan D. Rhyne (DJ-D)" title="Jonathan D. Rhyne (DJ-D)"/></a> <a href="https://github.com/juanpablodlc"><img src="https://avatars.githubusercontent.com/u/92012363?v=4&s=48" width="48" height="48" alt="juanpablodlc" title="juanpablodlc"/></a> <a href="https://github.com/jverdi"><img src="https://avatars.githubusercontent.com/u/345050?v=4&s=48" width="48" height="48" alt="jverdi" title="jverdi"/></a> <a href="https://github.com/mickahouan"><img src="https://avatars.githubusercontent.com/u/31423109?v=4&s=48" width="48" height="48" alt="mickahouan" title="mickahouan"/></a> <a href="https://github.com/mjrussell"><img src="https://avatars.githubusercontent.com/u/1641895?v=4&s=48" width="48" height="48" alt="mjrussell" title="mjrussell"/></a> <a href="https://github.com/oswalpalash"><img src="https://avatars.githubusercontent.com/u/6431196?v=4&s=48" width="48" height="48" alt="oswalpalash" title="oswalpalash"/></a> <a href="https://github.com/p6l-richard"><img src="https://avatars.githubusercontent.com/u/18185649?v=4&s=48" width="48" height="48" alt="p6l-richard" title="p6l-richard"/></a> <a href="https://github.com/philipp-spiess"><img src="https://avatars.githubusercontent.com/u/458591?v=4&s=48" width="48" height="48" alt="philipp-spiess" title="philipp-spiess"/></a> <a href="https://github.com/robaxelsen"><img src="https://avatars.githubusercontent.com/u/13132899?v=4&s=48" width="48" height="48" alt="robaxelsen" title="robaxelsen"/></a>
   <a href="https://github.com/search?q=Sash%20Catanzarite"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Sash Catanzarite" title="Sash Catanzarite"/></a> <a href="https://github.com/search?q=VAC"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="VAC" title="VAC"/></a> <a href="https://github.com/zknicker"><img src="https://avatars.githubusercontent.com/u/1164085?v=4&s=48" width="48" height="48" alt="zknicker" title="zknicker"/></a> <a href="https://github.com/adam91holt"><img src="https://avatars.githubusercontent.com/u/9592417?v=4&s=48" width="48" height="48" alt="adam91holt" title="adam91holt"/></a> <a href="https://github.com/search?q=alejandro%20maza"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="alejandro maza" title="alejandro maza"/></a> <a href="https://github.com/andrewting19"><img src="https://avatars.githubusercontent.com/u/10536704?v=4&s=48" width="48" height="48" alt="andrewting19" title="andrewting19"/></a> <a href="https://github.com/Asleep123"><img src="https://avatars.githubusercontent.com/u/122379135?v=4&s=48" width="48" height="48" alt="Asleep123" title="Asleep123"/></a> <a href="https://github.com/bolismauro"><img src="https://avatars.githubusercontent.com/u/771999?v=4&s=48" width="48" height="48" alt="bolismauro" title="bolismauro"/></a> <a href="https://github.com/cash-echo-bot"><img src="https://avatars.githubusercontent.com/u/252747386?v=4&s=48" width="48" height="48" alt="cash-echo-bot" title="cash-echo-bot"/></a> <a href="https://github.com/search?q=Clawd"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Clawd" title="Clawd"/></a>
-  <a href="https://github.com/conhecendocontato"><img src="https://avatars.githubusercontent.com/u/82890727?v=4&s=48" width="48" height="48" alt="conhecendocontato" title="conhecendocontato"/></a> <a href="https://github.com/search?q=Drake%20Thomsen"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Drake Thomsen" title="Drake Thomsen"/></a> <a href="https://github.com/evalexpr"><img src="https://avatars.githubusercontent.com/u/23485511?v=4&s=48" width="48" height="48" alt="evalexpr" title="evalexpr"/></a> <a href="https://github.com/gtsifrikas"><img src="https://avatars.githubusercontent.com/u/8904378?v=4&s=48" width="48" height="48" alt="gtsifrikas" title="gtsifrikas"/></a> <a href="https://github.com/HazAT"><img src="https://avatars.githubusercontent.com/u/363802?v=4&s=48" width="48" height="48" alt="HazAT" title="HazAT"/></a> <a href="https://github.com/hrdwdmrbl"><img src="https://avatars.githubusercontent.com/u/554881?v=4&s=48" width="48" height="48" alt="hrdwdmrbl" title="hrdwdmrbl"/></a> <a href="https://github.com/hugobarauna"><img src="https://avatars.githubusercontent.com/u/2719?v=4&s=48" width="48" height="48" alt="hugobarauna" title="hugobarauna"/></a> <a href="https://github.com/search?q=Jarvis"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jarvis" title="Jarvis"/></a> <a href="https://github.com/kitze"><img src="https://avatars.githubusercontent.com/u/1160594?v=4&s=48" width="48" height="48" alt="kitze" title="kitze"/></a> <a href="https://github.com/kkarimi"><img src="https://avatars.githubusercontent.com/u/875218?v=4&s=48" width="48" height="48" alt="kkarimi" title="kkarimi"/></a>
-  <a href="https://github.com/levifig"><img src="https://avatars.githubusercontent.com/u/1605?v=4&s=48" width="48" height="48" alt="levifig" title="levifig"/></a> <a href="https://github.com/search?q=Lloyd"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Lloyd" title="Lloyd"/></a> <a href="https://github.com/loukotal"><img src="https://avatars.githubusercontent.com/u/18210858?v=4&s=48" width="48" height="48" alt="loukotal" title="loukotal"/></a> <a href="https://github.com/martinpucik"><img src="https://avatars.githubusercontent.com/u/5503097?v=4&s=48" width="48" height="48" alt="martinpucik" title="martinpucik"/></a> <a href="https://github.com/search?q=Miles"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Miles" title="Miles"/></a> <a href="https://github.com/mrdbstn"><img src="https://avatars.githubusercontent.com/u/58957632?v=4&s=48" width="48" height="48" alt="mrdbstn" title="mrdbstn"/></a> <a href="https://github.com/MSch"><img src="https://avatars.githubusercontent.com/u/7475?v=4&s=48" width="48" height="48" alt="MSch" title="MSch"/></a> <a href="https://github.com/search?q=Mustafa%20Tag%20Eldeen"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Mustafa Tag Eldeen" title="Mustafa Tag Eldeen"/></a> <a href="https://github.com/nexty5870"><img src="https://avatars.githubusercontent.com/u/3869659?v=4&s=48" width="48" height="48" alt="nexty5870" title="nexty5870"/></a> <a href="https://github.com/prathamdby"><img src="https://avatars.githubusercontent.com/u/134331217?v=4&s=48" width="48" height="48" alt="prathamdby" title="prathamdby"/></a>
-  <a href="https://github.com/reeltimeapps"><img src="https://avatars.githubusercontent.com/u/637338?v=4&s=48" width="48" height="48" alt="reeltimeapps" title="reeltimeapps"/></a> <a href="https://github.com/RLTCmpe"><img src="https://avatars.githubusercontent.com/u/10762242?v=4&s=48" width="48" height="48" alt="RLTCmpe" title="RLTCmpe"/></a> <a href="https://github.com/search?q=Rolf%20Fredheim"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rolf Fredheim" title="Rolf Fredheim"/></a> <a href="https://github.com/search?q=Rony%20Kelner"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rony Kelner" title="Rony Kelner"/></a> <a href="https://github.com/search?q=Samrat%20Jha"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Samrat Jha" title="Samrat Jha"/></a> <a href="https://github.com/siraht"><img src="https://avatars.githubusercontent.com/u/73152895?v=4&s=48" width="48" height="48" alt="siraht" title="siraht"/></a> <a href="https://github.com/snopoke"><img src="https://avatars.githubusercontent.com/u/249606?v=4&s=48" width="48" height="48" alt="snopoke" title="snopoke"/></a> <a href="https://github.com/search?q=The%20Admiral"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="The Admiral" title="The Admiral"/></a> <a href="https://github.com/wes-davis"><img src="https://avatars.githubusercontent.com/u/16506720?v=4&s=48" width="48" height="48" alt="wes-davis" title="wes-davis"/></a> <a href="https://github.com/wstock"><img src="https://avatars.githubusercontent.com/u/1394687?v=4&s=48" width="48" height="48" alt="wstock" title="wstock"/></a>
-  <a href="https://github.com/YuriNachos"><img src="https://avatars.githubusercontent.com/u/19365375?v=4&s=48" width="48" height="48" alt="YuriNachos" title="YuriNachos"/></a> <a href="https://github.com/search?q=Zach%20Knickerbocker"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Zach Knickerbocker" title="Zach Knickerbocker"/></a> <a href="https://github.com/search?q=Azade"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Azade" title="Azade"/></a> <a href="https://github.com/carlulsoe"><img src="https://avatars.githubusercontent.com/u/34673973?v=4&s=48" width="48" height="48" alt="carlulsoe" title="carlulsoe"/></a> <a href="https://github.com/search?q=ddyo"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="ddyo" title="ddyo"/></a> <a href="https://github.com/search?q=Erik"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Erik" title="Erik"/></a> <a href="https://github.com/latitudeki5223"><img src="https://avatars.githubusercontent.com/u/119656367?v=4&s=48" width="48" height="48" alt="latitudeki5223" title="latitudeki5223"/></a> <a href="https://github.com/search?q=Manuel%20Maly"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Manuel Maly" title="Manuel Maly"/></a> <a href="https://github.com/search?q=Mourad%20Boustani"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Mourad Boustani" title="Mourad Boustani"/></a> <a href="https://github.com/pcty-nextgen-ios-builder"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="pcty-nextgen-ios-builder" title="pcty-nextgen-ios-builder"/></a>
-  <a href="https://github.com/search?q=Quentin"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Quentin" title="Quentin"/></a> <a href="https://github.com/search?q=Randy%20Torres"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Randy Torres" title="Randy Torres"/></a> <a href="https://github.com/thesash"><img src="https://avatars.githubusercontent.com/u/1166151?v=4&s=48" width="48" height="48" alt="thesash" title="thesash"/></a> <a href="https://github.com/search?q=William%20Stock"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="William Stock" title="William Stock"/></a>
+  <a href="https://github.com/conhecendocontato"><img src="https://avatars.githubusercontent.com/u/82890727?v=4&s=48" width="48" height="48" alt="conhecendocontato" title="conhecendocontato"/></a> <a href="https://github.com/search?q=Drake%20Thomsen"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Drake Thomsen" title="Drake Thomsen"/></a> <a href="https://github.com/gtsifrikas"><img src="https://avatars.githubusercontent.com/u/8904378?v=4&s=48" width="48" height="48" alt="gtsifrikas" title="gtsifrikas"/></a> <a href="https://github.com/HazAT"><img src="https://avatars.githubusercontent.com/u/363802?v=4&s=48" width="48" height="48" alt="HazAT" title="HazAT"/></a> <a href="https://github.com/hrdwdmrbl"><img src="https://avatars.githubusercontent.com/u/554881?v=4&s=48" width="48" height="48" alt="hrdwdmrbl" title="hrdwdmrbl"/></a> <a href="https://github.com/hugobarauna"><img src="https://avatars.githubusercontent.com/u/2719?v=4&s=48" width="48" height="48" alt="hugobarauna" title="hugobarauna"/></a> <a href="https://github.com/search?q=Jarvis"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jarvis" title="Jarvis"/></a> <a href="https://github.com/search?q=Jefferson%20Nunn"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jefferson Nunn" title="Jefferson Nunn"/></a> <a href="https://github.com/kitze"><img src="https://avatars.githubusercontent.com/u/1160594?v=4&s=48" width="48" height="48" alt="kitze" title="kitze"/></a> <a href="https://github.com/kkarimi"><img src="https://avatars.githubusercontent.com/u/875218?v=4&s=48" width="48" height="48" alt="kkarimi" title="kkarimi"/></a>
+  <a href="https://github.com/levifig"><img src="https://avatars.githubusercontent.com/u/1605?v=4&s=48" width="48" height="48" alt="levifig" title="levifig"/></a> <a href="https://github.com/search?q=Lloyd"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Lloyd" title="Lloyd"/></a> <a href="https://github.com/loukotal"><img src="https://avatars.githubusercontent.com/u/18210858?v=4&s=48" width="48" height="48" alt="loukotal" title="loukotal"/></a> <a href="https://github.com/search?q=Marc"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Marc" title="Marc"/></a> <a href="https://github.com/martinpucik"><img src="https://avatars.githubusercontent.com/u/5503097?v=4&s=48" width="48" height="48" alt="martinpucik" title="martinpucik"/></a> <a href="https://github.com/search?q=Miles"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Miles" title="Miles"/></a> <a href="https://github.com/mrdbstn"><img src="https://avatars.githubusercontent.com/u/58957632?v=4&s=48" width="48" height="48" alt="mrdbstn" title="mrdbstn"/></a> <a href="https://github.com/MSch"><img src="https://avatars.githubusercontent.com/u/7475?v=4&s=48" width="48" height="48" alt="MSch" title="MSch"/></a> <a href="https://github.com/search?q=Mustafa%20Tag%20Eldeen"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Mustafa Tag Eldeen" title="Mustafa Tag Eldeen"/></a> <a href="https://github.com/ndraiman"><img src="https://avatars.githubusercontent.com/u/12609607?v=4&s=48" width="48" height="48" alt="ndraiman" title="ndraiman"/></a>
+  <a href="https://github.com/nexty5870"><img src="https://avatars.githubusercontent.com/u/3869659?v=4&s=48" width="48" height="48" alt="nexty5870" title="nexty5870"/></a> <a href="https://github.com/prathamdby"><img src="https://avatars.githubusercontent.com/u/134331217?v=4&s=48" width="48" height="48" alt="prathamdby" title="prathamdby"/></a> <a href="https://github.com/reeltimeapps"><img src="https://avatars.githubusercontent.com/u/637338?v=4&s=48" width="48" height="48" alt="reeltimeapps" title="reeltimeapps"/></a> <a href="https://github.com/RLTCmpe"><img src="https://avatars.githubusercontent.com/u/10762242?v=4&s=48" width="48" height="48" alt="RLTCmpe" title="RLTCmpe"/></a> <a href="https://github.com/search?q=Rolf%20Fredheim"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rolf Fredheim" title="Rolf Fredheim"/></a> <a href="https://github.com/search?q=Rony%20Kelner"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rony Kelner" title="Rony Kelner"/></a> <a href="https://github.com/search?q=Samrat%20Jha"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Samrat Jha" title="Samrat Jha"/></a> <a href="https://github.com/siraht"><img src="https://avatars.githubusercontent.com/u/73152895?v=4&s=48" width="48" height="48" alt="siraht" title="siraht"/></a> <a href="https://github.com/snopoke"><img src="https://avatars.githubusercontent.com/u/249606?v=4&s=48" width="48" height="48" alt="snopoke" title="snopoke"/></a> <a href="https://github.com/search?q=The%20Admiral"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="The Admiral" title="The Admiral"/></a>
+  <a href="https://github.com/wes-davis"><img src="https://avatars.githubusercontent.com/u/16506720?v=4&s=48" width="48" height="48" alt="wes-davis" title="wes-davis"/></a> <a href="https://github.com/wstock"><img src="https://avatars.githubusercontent.com/u/1394687?v=4&s=48" width="48" height="48" alt="wstock" title="wstock"/></a> <a href="https://github.com/YuriNachos"><img src="https://avatars.githubusercontent.com/u/19365375?v=4&s=48" width="48" height="48" alt="YuriNachos" title="YuriNachos"/></a> <a href="https://github.com/search?q=Zach%20Knickerbocker"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Zach Knickerbocker" title="Zach Knickerbocker"/></a> <a href="https://github.com/search?q=Azade"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Azade" title="Azade"/></a> <a href="https://github.com/carlulsoe"><img src="https://avatars.githubusercontent.com/u/34673973?v=4&s=48" width="48" height="48" alt="carlulsoe" title="carlulsoe"/></a> <a href="https://github.com/cpojer"><img src="https://avatars.githubusercontent.com/u/13352?v=4&s=48" width="48" height="48" alt="cpojer" title="cpojer"/></a> <a href="https://github.com/search?q=ddyo"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="ddyo" title="ddyo"/></a> <a href="https://github.com/search?q=Erik"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Erik" title="Erik"/></a> <a href="https://github.com/latitudeki5223"><img src="https://avatars.githubusercontent.com/u/119656367?v=4&s=48" width="48" height="48" alt="latitudeki5223" title="latitudeki5223"/></a>
+  <a href="https://github.com/search?q=Manuel%20Maly"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Manuel Maly" title="Manuel Maly"/></a> <a href="https://github.com/search?q=Mourad%20Boustani"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Mourad Boustani" title="Mourad Boustani"/></a> <a href="https://github.com/pcty-nextgen-ios-builder"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="pcty-nextgen-ios-builder" title="pcty-nextgen-ios-builder"/></a> <a href="https://github.com/search?q=Quentin"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Quentin" title="Quentin"/></a> <a href="https://github.com/search?q=Randy%20Torres"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Randy Torres" title="Randy Torres"/></a> <a href="https://github.com/thesash"><img src="https://avatars.githubusercontent.com/u/1166151?v=4&s=48" width="48" height="48" alt="thesash" title="thesash"/></a> <a href="https://github.com/search?q=William%20Stock"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="William Stock" title="William Stock"/></a>
 </p>

SECURITY.md

@@ -0,0 +1,15 @@
+# Security Policy
+
+If you believe you’ve found a security issue in Clawdbot, please report it privately.
+
+## Reporting
+
+- Email: `steipete@gmail.com`
+- What to include: reproduction steps, impact assessment, and (if possible) a minimal PoC.
+
+## Operational Guidance
+
+For threat model + hardening guidance (including `clawdbot security audit --deep` and `--fix`), see:
+
+- `https://docs.clawd.bot/gateway/security`
+

Swabble/Sources/SwabbleCore/Support/AttributedString+Sentences.swift

@@ -34,8 +34,7 @@ extension AttributedString {
             var ranges: [Range<AttributedString.Index>] = []
             for wordRange in wordRanges {
                 if let lastRange = ranges.last,
-                   self[lastRange].characters.count + self[wordRange].characters.count <= maxLength
-                {
+                   self[lastRange].characters.count + self[wordRange].characters.count <= maxLength {
                     ranges[ranges.count - 1] = lastRange.lowerBound..<wordRange.upperBound
                 } else {
                     ranges.append(wordRange)

Swabble/Sources/SwabbleCore/Support/TranscriptsStore.swift

@@ -13,8 +13,7 @@ public actor TranscriptsStore {
         try? FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
         fileURL = dir.appendingPathComponent("transcripts.log")
         if let data = try? Data(contentsOf: fileURL),
-           let text = String(data: data, encoding: .utf8)
-        {
+           let text = String(data: data, encoding: .utf8) {
             entries = text.split(separator: "\n").map(String.init).suffix(limit)
         }
     }

Swabble/Sources/SwabbleKit/WakeWordGate.swift

@@ -24,8 +24,7 @@ public struct WakeWordGateConfig: Sendable, Equatable {
     public init(
         triggers: [String],
         minPostTriggerGap: TimeInterval = 0.45,
-        minCommandLength: Int = 1)
-    {
+        minCommandLength: Int = 1) {
         self.triggers = triggers
         self.minPostTriggerGap = minPostTriggerGap
         self.minCommandLength = minCommandLength
@@ -57,6 +56,12 @@ public enum WakeWordGate {
         let tokens: [String]
     }
 
+    private struct MatchCandidate {
+        let index: Int
+        let triggerEnd: TimeInterval
+        let gap: TimeInterval
+    }
+
     public static func match(
         transcript: String,
         segments: [WakeWordSegment],
@@ -68,7 +73,7 @@ public enum WakeWordGate {
         let tokens = normalizeSegments(segments)
         guard !tokens.isEmpty else { return nil }
 
-        var best: (index: Int, triggerEnd: TimeInterval, gap: TimeInterval)?
+        var best: MatchCandidate?
 
         for trigger in triggerTokens {
             let count = trigger.tokens.count
@@ -84,7 +89,7 @@ public enum WakeWordGate {
 
                 if let best, i <= best.index { continue }
 
-                best = (i, triggerEnd, gap)
+                best = MatchCandidate(index: i, triggerEnd: triggerEnd, gap: gap)
             }
         }
 

Swabble/Sources/swabble/CLI/CLIRegistry.swift

@@ -24,7 +24,7 @@ enum CLIRegistry {
             subcommands: [
                 descriptor(for: ServiceInstall.self),
                 descriptor(for: ServiceUninstall.self),
-                descriptor(for: ServiceStatus.self),
+                descriptor(for: ServiceStatus.self)
             ])
         let doctorDesc = descriptor(for: DoctorCommand.self)
         let setupDesc = descriptor(for: SetupCommand.self)
@@ -54,7 +54,7 @@ enum CLIRegistry {
                 startDesc,
                 stopDesc,
                 restartDesc,
-                statusDesc,
+                statusDesc
             ])
         return [root]
     }

Swabble/Sources/swabble/Commands/ServiceCommands.swift

@@ -25,7 +25,7 @@ private enum LaunchdHelper {
             "Label": label,
             "ProgramArguments": [executable, "serve"],
             "RunAtLoad": true,
-            "KeepAlive": true,
+            "KeepAlive": true
         ]
         let data = try PropertyListSerialization.data(fromPropertyList: plist, format: .xml, options: 0)
         try data.write(to: plistURL)

Swabble/Sources/swabble/main.swift

@@ -25,78 +25,123 @@ private func dispatch(invocation: CommandInvocation) async throws {
 
     switch first {
     case "swabble":
-        guard path.count >= 2 else { throw CommanderProgramError.missingSubcommand(command: "swabble") }
-        let sub = path[1]
-        switch sub {
-        case "serve":
-            var cmd = ServeCommand(parsed: parsed)
-            try await cmd.run()
-        case "transcribe":
-            var cmd = TranscribeCommand(parsed: parsed)
-            try await cmd.run()
-        case "test-hook":
-            var cmd = TestHookCommand(parsed: parsed)
-            try await cmd.run()
-        case "mic":
-            guard path.count >= 3 else { throw CommanderProgramError.missingSubcommand(command: "mic") }
-            let micSub = path[2]
-            if micSub == "list" {
-                var cmd = MicList(parsed: parsed)
-                try await cmd.run()
-            } else if micSub == "set" {
-                var cmd = MicSet(parsed: parsed)
-                try await cmd.run()
-            } else {
-                throw CommanderProgramError.unknownSubcommand(command: "mic", name: micSub)
-            }
-        case "service":
-            guard path.count >= 3 else { throw CommanderProgramError.missingSubcommand(command: "service") }
-            let svcSub = path[2]
-            switch svcSub {
-            case "install":
-                var cmd = ServiceInstall()
-                try await cmd.run()
-            case "uninstall":
-                var cmd = ServiceUninstall()
-                try await cmd.run()
-            case "status":
-                var cmd = ServiceStatus()
-                try await cmd.run()
-            default:
-                throw CommanderProgramError.unknownSubcommand(command: "service", name: svcSub)
-            }
-        case "doctor":
-            var cmd = DoctorCommand(parsed: parsed)
-            try await cmd.run()
-        case "setup":
-            var cmd = SetupCommand(parsed: parsed)
-            try await cmd.run()
-        case "health":
-            var cmd = HealthCommand(parsed: parsed)
-            try await cmd.run()
-        case "tail-log":
-            var cmd = TailLogCommand(parsed: parsed)
-            try await cmd.run()
-        case "start":
-            var cmd = StartCommand()
-            try await cmd.run()
-        case "stop":
-            var cmd = StopCommand()
-            try await cmd.run()
-        case "restart":
-            var cmd = RestartCommand()
-            try await cmd.run()
-        case "status":
-            var cmd = StatusCommand()
-            try await cmd.run()
-        default:
-            throw CommanderProgramError.unknownSubcommand(command: "swabble", name: sub)
-        }
+        try await dispatchSwabble(parsed: parsed, path: path)
     default:
         throw CommanderProgramError.unknownCommand(first)
     }
 }
 
+@available(macOS 26.0, *)
+@MainActor
+private func dispatchSwabble(parsed: ParsedValues, path: [String]) async throws {
+    let sub = try subcommand(path, index: 1, command: "swabble")
+    switch sub {
+    case "mic":
+        try await dispatchMic(parsed: parsed, path: path)
+    case "service":
+        try await dispatchService(path: path)
+    default:
+        let handlers = swabbleHandlers(parsed: parsed)
+        guard let handler = handlers[sub] else {
+            throw CommanderProgramError.unknownSubcommand(command: "swabble", name: sub)
+        }
+        try await handler()
+    }
+}
+
+@available(macOS 26.0, *)
+@MainActor
+private func swabbleHandlers(parsed: ParsedValues) -> [String: () async throws -> Void] {
+    [
+        "serve": {
+            var cmd = ServeCommand(parsed: parsed)
+            try await cmd.run()
+        },
+        "transcribe": {
+            var cmd = TranscribeCommand(parsed: parsed)
+            try await cmd.run()
+        },
+        "test-hook": {
+            var cmd = TestHookCommand(parsed: parsed)
+            try await cmd.run()
+        },
+        "doctor": {
+            var cmd = DoctorCommand(parsed: parsed)
+            try await cmd.run()
+        },
+        "setup": {
+            var cmd = SetupCommand(parsed: parsed)
+            try await cmd.run()
+        },
+        "health": {
+            var cmd = HealthCommand(parsed: parsed)
+            try await cmd.run()
+        },
+        "tail-log": {
+            var cmd = TailLogCommand(parsed: parsed)
+            try await cmd.run()
+        },
+        "start": {
+            var cmd = StartCommand()
+            try await cmd.run()
+        },
+        "stop": {
+            var cmd = StopCommand()
+            try await cmd.run()
+        },
+        "restart": {
+            var cmd = RestartCommand()
+            try await cmd.run()
+        },
+        "status": {
+            var cmd = StatusCommand()
+            try await cmd.run()
+        }
+    ]
+}
+
+@available(macOS 26.0, *)
+@MainActor
+private func dispatchMic(parsed: ParsedValues, path: [String]) async throws {
+    let micSub = try subcommand(path, index: 2, command: "mic")
+    switch micSub {
+    case "list":
+        var cmd = MicList(parsed: parsed)
+        try await cmd.run()
+    case "set":
+        var cmd = MicSet(parsed: parsed)
+        try await cmd.run()
+    default:
+        throw CommanderProgramError.unknownSubcommand(command: "mic", name: micSub)
+    }
+}
+
+@available(macOS 26.0, *)
+@MainActor
+private func dispatchService(path: [String]) async throws {
+    let svcSub = try subcommand(path, index: 2, command: "service")
+    switch svcSub {
+    case "install":
+        var cmd = ServiceInstall()
+        try await cmd.run()
+    case "uninstall":
+        var cmd = ServiceUninstall()
+        try await cmd.run()
+    case "status":
+        var cmd = ServiceStatus()
+        try await cmd.run()
+    default:
+        throw CommanderProgramError.unknownSubcommand(command: "service", name: svcSub)
+    }
+}
+
+private func subcommand(_ path: [String], index: Int, command: String) throws -> String {
+    guard path.count > index else {
+        throw CommanderProgramError.missingSubcommand(command: command)
+    }
+    return path[index]
+}
+
 if #available(macOS 26.0, *) {
     let exitCode = await runCLI()
     exit(exitCode)

appcast.xml

@@ -2,6 +2,22 @@
 <rss xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle" version="2.0">
     <channel>
         <title>Clawdbot</title>
+        <item>
+            <title>2026.1.12-2</title>
+            <pubDate>Tue, 13 Jan 2026 10:05:25 +0000</pubDate>
+            <link>https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml</link>
+            <sparkle:version>5534</sparkle:version>
+            <sparkle:shortVersionString>2026.1.12-2</sparkle:shortVersionString>
+            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+            <description><![CDATA[<h2>Clawdbot 2026.1.12-2</h2>
+<h3>Fixes</h3>
+<ul>
+<li>Packaging: include <code>dist/memory/**</code> in the npm tarball (fixes <code>ERR_MODULE_NOT_FOUND</code> for <code>dist/memory/index.js</code>).</li>
+</ul>
+<p><a href="https://github.com/clawdbot/clawdbot/blob/main/CHANGELOG.md">View full changelog</a></p>
+]]></description>
+            <enclosure url="https://github.com/clawdbot/clawdbot/releases/download/v2026.1.12-2/Clawdbot-2026.1.12-2.zip" length="19854203" type="application/octet-stream" sparkle:edSignature="CVpUofNS+pl6Smk/K0Q8q35saRuuFx90s4sePABORFvGcAF1biajC8zpiImKuXpqD0ENb+VTwDJ1ul1Oxh3wDA=="/>
+        </item>
         <item>
             <title>2026.1.11-3</title>
             <pubDate>Mon, 12 Jan 2026 10:40:23 +0000</pubDate>
@@ -36,21 +52,5 @@
 ]]></description>
             <enclosure url="https://github.com/clawdbot/clawdbot/releases/download/v2026.1.11-2/Clawdbot-2026.1.11-2.zip" length="19860732" type="application/octet-stream" sparkle:edSignature="0UG+d9v3Qf5F9vs/KozUB404WpHjFBQRVoRuhwtzF8kpU7jJmmGlQzh1c61E+LMN4fHcljpxIwHHrvvIfRyrCw=="/>
         </item>
-        <item>
-            <title>2026.1.11-1</title>
-            <pubDate>Mon, 12 Jan 2026 09:53:46 +0000</pubDate>
-            <link>https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml</link>
-            <sparkle:version>5207</sparkle:version>
-            <sparkle:shortVersionString>2026.1.11-1</sparkle:shortVersionString>
-            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
-            <description><![CDATA[<h2>Clawdbot 2026.1.11-1</h2>
-<h3>Fixes</h3>
-<ul>
-<li>Installer: include <code>patches/</code> in the npm package so postinstall patching works for npm/bun installs.</li>
-</ul>
-<p><a href="https://github.com/clawdbot/clawdbot/blob/main/CHANGELOG.md">View full changelog</a></p>
-]]></description>
-            <enclosure url="https://github.com/clawdbot/clawdbot/releases/download/v2026.1.11-1/Clawdbot-2026.1.11-1.zip" length="19860761" type="application/octet-stream" sparkle:edSignature="CXKzzha/s6cGBeF0TMz+cV8/pfqoAL9ZyNVacYRLnnHEwA1cMbOWRftpGRhYe4HknVQYYBgNQqZK2lBxpOZgBg=="/>
-        </item>
     </channel>
 </rss>

apps/macos/Sources/Clawdbot/Bridge/BridgeServer.swift

@@ -187,7 +187,7 @@ actor BridgeServer {
                 thinking: "low",
                 deliver: false,
                 to: nil,
-                provider: .last))
+                channel: .last))
 
         case "agent.request":
             guard let json = evt.payloadJSON, let data = json.data(using: .utf8) else {
@@ -205,7 +205,7 @@ actor BridgeServer {
                 ?? "node-\(nodeId)"
             let thinking = link.thinking?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty
             let to = link.to?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty
-            let provider = GatewayAgentProvider(raw: link.channel)
+            let channel = GatewayAgentChannel(raw: link.channel)
 
             _ = await GatewayConnection.shared.sendAgent(GatewayAgentInvocation(
                 message: message,
@@ -213,7 +213,7 @@ actor BridgeServer {
                 thinking: thinking,
                 deliver: link.deliver,
                 to: to,
-                provider: provider))
+                channel: channel))
 
         default:
             break

apps/macos/Sources/Clawdbot/CanvasA2UIActionMessageHandler.swift

@@ -86,7 +86,7 @@ final class CanvasA2UIActionMessageHandler: NSObject, WKScriptMessageHandler {
                     thinking: "low",
                     deliver: false,
                     to: nil,
-                    provider: .last,
+                    channel: .last,
                     idempotencyKey: actionId))
 
             await MainActor.run {

apps/macos/Sources/Clawdbot/ConfigStore.swift

@@ -19,6 +19,7 @@ enum ConfigStore {
     }
 
     private static let overrideStore = OverrideStore()
+    @MainActor private static var lastHash: String?
 
     private static func isRemoteMode() async -> Bool {
         let overrides = await self.overrideStore.overrides
@@ -75,6 +76,7 @@ enum ConfigStore {
                 method: .configGet,
                 params: nil,
                 timeoutMs: 8000)
+            self.lastHash = snap.hash
             return snap.config?.mapValues { $0.foundationValue } ?? [:]
         } catch {
             return nil
@@ -83,17 +85,24 @@ enum ConfigStore {
 
     @MainActor
     private static func saveToGateway(_ root: [String: Any]) async throws {
+        if self.lastHash == nil {
+            _ = await self.loadFromGateway()
+        }
         let data = try JSONSerialization.data(withJSONObject: root, options: [.prettyPrinted, .sortedKeys])
         guard let raw = String(data: data, encoding: .utf8) else {
             throw NSError(domain: "ConfigStore", code: 1, userInfo: [
                 NSLocalizedDescriptionKey: "Failed to encode config.",
             ])
         }
-        let params: [String: AnyCodable] = ["raw": AnyCodable(raw)]
+        var params: [String: AnyCodable] = ["raw": AnyCodable(raw)]
+        if let baseHash = self.lastHash {
+            params["baseHash"] = AnyCodable(baseHash)
+        }
         _ = try await GatewayConnection.shared.requestRaw(
             method: .configSet,
             params: params,
             timeoutMs: 10000)
+        _ = await self.loadFromGateway()
     }
 
     #if DEBUG

apps/macos/Sources/Clawdbot/ConnectionsSettings+ChannelSections.swift

@@ -11,9 +11,9 @@ extension ConnectionsSettings {
     }
 
     @ViewBuilder
-    func providerHeaderActions(_ provider: ConnectionProvider) -> some View {
+    func channelHeaderActions(_ channel: ConnectionChannel) -> some View {
         HStack(spacing: 8) {
-            if provider == .whatsapp {
+            if channel == .whatsapp {
                 Button("Logout") {
                     Task { await self.store.logoutWhatsApp() }
                 }
@@ -21,7 +21,7 @@ extension ConnectionsSettings {
                 .disabled(self.store.whatsappBusy)
             }
 
-            if provider == .telegram {
+            if channel == .telegram {
                 Button("Logout") {
                     Task { await self.store.logoutTelegram() }
                 }

apps/macos/Sources/Clawdbot/ConnectionsSettings+ChannelState.swift

@@ -1,15 +1,15 @@
 import SwiftUI
 
 extension ConnectionsSettings {
-    private func providerStatus<T: Decodable>(
+    private func channelStatus<T: Decodable>(
         _ id: String,
         as type: T.Type) -> T?
     {
-        self.store.snapshot?.decodeProvider(id, as: type)
+        self.store.snapshot?.decodeChannel(id, as: type)
     }
 
     var whatsAppTint: Color {
-        guard let status = self.providerStatus("whatsapp", as: ProvidersStatusSnapshot.WhatsAppStatus.self)
+        guard let status = self.channelStatus("whatsapp", as: ChannelsStatusSnapshot.WhatsAppStatus.self)
         else { return .secondary }
         if !status.configured { return .secondary }
         if !status.linked { return .red }
@@ -20,7 +20,7 @@ extension ConnectionsSettings {
     }
 
     var telegramTint: Color {
-        guard let status = self.providerStatus("telegram", as: ProvidersStatusSnapshot.TelegramStatus.self)
+        guard let status = self.channelStatus("telegram", as: ChannelsStatusSnapshot.TelegramStatus.self)
         else { return .secondary }
         if !status.configured { return .secondary }
         if status.lastError != nil { return .orange }
@@ -30,7 +30,7 @@ extension ConnectionsSettings {
     }
 
     var discordTint: Color {
-        guard let status = self.providerStatus("discord", as: ProvidersStatusSnapshot.DiscordStatus.self)
+        guard let status = self.channelStatus("discord", as: ChannelsStatusSnapshot.DiscordStatus.self)
         else { return .secondary }
         if !status.configured { return .secondary }
         if status.lastError != nil { return .orange }
@@ -40,7 +40,7 @@ extension ConnectionsSettings {
     }
 
     var signalTint: Color {
-        guard let status = self.providerStatus("signal", as: ProvidersStatusSnapshot.SignalStatus.self)
+        guard let status = self.channelStatus("signal", as: ChannelsStatusSnapshot.SignalStatus.self)
         else { return .secondary }
         if !status.configured { return .secondary }
         if status.lastError != nil { return .orange }
@@ -50,7 +50,7 @@ extension ConnectionsSettings {
     }
 
     var imessageTint: Color {
-        guard let status = self.providerStatus("imessage", as: ProvidersStatusSnapshot.IMessageStatus.self)
+        guard let status = self.channelStatus("imessage", as: ChannelsStatusSnapshot.IMessageStatus.self)
         else { return .secondary }
         if !status.configured { return .secondary }
         if status.lastError != nil { return .orange }
@@ -60,7 +60,7 @@ extension ConnectionsSettings {
     }
 
     var whatsAppSummary: String {
-        guard let status = self.providerStatus("whatsapp", as: ProvidersStatusSnapshot.WhatsAppStatus.self)
+        guard let status = self.channelStatus("whatsapp", as: ChannelsStatusSnapshot.WhatsAppStatus.self)
         else { return "Checking…" }
         if !status.linked { return "Not linked" }
         if status.connected { return "Connected" }
@@ -69,7 +69,7 @@ extension ConnectionsSettings {
     }
 
     var telegramSummary: String {
-        guard let status = self.providerStatus("telegram", as: ProvidersStatusSnapshot.TelegramStatus.self)
+        guard let status = self.channelStatus("telegram", as: ChannelsStatusSnapshot.TelegramStatus.self)
         else { return "Checking…" }
         if !status.configured { return "Not configured" }
         if status.running { return "Running" }
@@ -77,7 +77,7 @@ extension ConnectionsSettings {
     }
 
     var discordSummary: String {
-        guard let status = self.providerStatus("discord", as: ProvidersStatusSnapshot.DiscordStatus.self)
+        guard let status = self.channelStatus("discord", as: ChannelsStatusSnapshot.DiscordStatus.self)
         else { return "Checking…" }
         if !status.configured { return "Not configured" }
         if status.running { return "Running" }
@@ -85,7 +85,7 @@ extension ConnectionsSettings {
     }
 
     var signalSummary: String {
-        guard let status = self.providerStatus("signal", as: ProvidersStatusSnapshot.SignalStatus.self)
+        guard let status = self.channelStatus("signal", as: ChannelsStatusSnapshot.SignalStatus.self)
         else { return "Checking…" }
         if !status.configured { return "Not configured" }
         if status.running { return "Running" }
@@ -93,7 +93,7 @@ extension ConnectionsSettings {
     }
 
     var imessageSummary: String {
-        guard let status = self.providerStatus("imessage", as: ProvidersStatusSnapshot.IMessageStatus.self)
+        guard let status = self.channelStatus("imessage", as: ChannelsStatusSnapshot.IMessageStatus.self)
         else { return "Checking…" }
         if !status.configured { return "Not configured" }
         if status.running { return "Running" }
@@ -101,7 +101,7 @@ extension ConnectionsSettings {
     }
 
     var whatsAppDetails: String? {
-        guard let status = self.providerStatus("whatsapp", as: ProvidersStatusSnapshot.WhatsAppStatus.self)
+        guard let status = self.channelStatus("whatsapp", as: ChannelsStatusSnapshot.WhatsAppStatus.self)
         else { return nil }
         var lines: [String] = []
         if let e164 = status.`self`?.e164 ?? status.`self`?.jid {
@@ -132,7 +132,7 @@ extension ConnectionsSettings {
     }
 
     var telegramDetails: String? {
-        guard let status = self.providerStatus("telegram", as: ProvidersStatusSnapshot.TelegramStatus.self)
+        guard let status = self.channelStatus("telegram", as: ChannelsStatusSnapshot.TelegramStatus.self)
         else { return nil }
         var lines: [String] = []
         if let source = status.tokenSource {
@@ -164,7 +164,7 @@ extension ConnectionsSettings {
     }
 
     var discordDetails: String? {
-        guard let status = self.providerStatus("discord", as: ProvidersStatusSnapshot.DiscordStatus.self)
+        guard let status = self.channelStatus("discord", as: ChannelsStatusSnapshot.DiscordStatus.self)
         else { return nil }
         var lines: [String] = []
         if let source = status.tokenSource {
@@ -193,7 +193,7 @@ extension ConnectionsSettings {
     }
 
     var signalDetails: String? {
-        guard let status = self.providerStatus("signal", as: ProvidersStatusSnapshot.SignalStatus.self)
+        guard let status = self.channelStatus("signal", as: ChannelsStatusSnapshot.SignalStatus.self)
         else { return nil }
         var lines: [String] = []
         lines.append("Base URL: \(status.baseUrl)")
@@ -220,7 +220,7 @@ extension ConnectionsSettings {
     }
 
     var imessageDetails: String? {
-        guard let status = self.providerStatus("imessage", as: ProvidersStatusSnapshot.IMessageStatus.self)
+        guard let status = self.channelStatus("imessage", as: ChannelsStatusSnapshot.IMessageStatus.self)
         else { return nil }
         var lines: [String] = []
         if let cliPath = status.cliPath, !cliPath.isEmpty {
@@ -243,68 +243,68 @@ extension ConnectionsSettings {
     }
 
     var isTelegramTokenLocked: Bool {
-        self.providerStatus("telegram", as: ProvidersStatusSnapshot.TelegramStatus.self)?.tokenSource == "env"
+        self.channelStatus("telegram", as: ChannelsStatusSnapshot.TelegramStatus.self)?.tokenSource == "env"
     }
 
     var isDiscordTokenLocked: Bool {
-        self.providerStatus("discord", as: ProvidersStatusSnapshot.DiscordStatus.self)?.tokenSource == "env"
+        self.channelStatus("discord", as: ChannelsStatusSnapshot.DiscordStatus.self)?.tokenSource == "env"
     }
 
-    var orderedProviders: [ConnectionProvider] {
-        ConnectionProvider.allCases.sorted { lhs, rhs in
-            let lhsEnabled = self.providerEnabled(lhs)
-            let rhsEnabled = self.providerEnabled(rhs)
+    var orderedChannels: [ConnectionChannel] {
+        ConnectionChannel.allCases.sorted { lhs, rhs in
+            let lhsEnabled = self.channelEnabled(lhs)
+            let rhsEnabled = self.channelEnabled(rhs)
             if lhsEnabled != rhsEnabled { return lhsEnabled && !rhsEnabled }
             return lhs.sortOrder < rhs.sortOrder
         }
     }
 
-    var enabledProviders: [ConnectionProvider] {
-        self.orderedProviders.filter { self.providerEnabled($0) }
+    var enabledChannels: [ConnectionChannel] {
+        self.orderedChannels.filter { self.channelEnabled($0) }
     }
 
-    var availableProviders: [ConnectionProvider] {
-        self.orderedProviders.filter { !self.providerEnabled($0) }
+    var availableChannels: [ConnectionChannel] {
+        self.orderedChannels.filter { !self.channelEnabled($0) }
     }
 
     func ensureSelection() {
-        guard let selected = self.selectedProvider else {
-            self.selectedProvider = self.orderedProviders.first
+        guard let selected = self.selectedChannel else {
+            self.selectedChannel = self.orderedChannels.first
             return
         }
-        if !self.orderedProviders.contains(selected) {
-            self.selectedProvider = self.orderedProviders.first
+        if !self.orderedChannels.contains(selected) {
+            self.selectedChannel = self.orderedChannels.first
         }
     }
 
-    func providerEnabled(_ provider: ConnectionProvider) -> Bool {
-        switch provider {
+    func channelEnabled(_ channel: ConnectionChannel) -> Bool {
+        switch channel {
         case .whatsapp:
-            guard let status = self.providerStatus("whatsapp", as: ProvidersStatusSnapshot.WhatsAppStatus.self)
+            guard let status = self.channelStatus("whatsapp", as: ChannelsStatusSnapshot.WhatsAppStatus.self)
             else { return false }
             return status.configured || status.linked || status.running
         case .telegram:
-            guard let status = self.providerStatus("telegram", as: ProvidersStatusSnapshot.TelegramStatus.self)
+            guard let status = self.channelStatus("telegram", as: ChannelsStatusSnapshot.TelegramStatus.self)
             else { return false }
             return status.configured || status.running
         case .discord:
-            guard let status = self.providerStatus("discord", as: ProvidersStatusSnapshot.DiscordStatus.self)
+            guard let status = self.channelStatus("discord", as: ChannelsStatusSnapshot.DiscordStatus.self)
             else { return false }
             return status.configured || status.running
         case .signal:
-            guard let status = self.providerStatus("signal", as: ProvidersStatusSnapshot.SignalStatus.self)
+            guard let status = self.channelStatus("signal", as: ChannelsStatusSnapshot.SignalStatus.self)
             else { return false }
             return status.configured || status.running
         case .imessage:
-            guard let status = self.providerStatus("imessage", as: ProvidersStatusSnapshot.IMessageStatus.self)
+            guard let status = self.channelStatus("imessage", as: ChannelsStatusSnapshot.IMessageStatus.self)
             else { return false }
             return status.configured || status.running
         }
     }
 
     @ViewBuilder
-    func providerSection(_ provider: ConnectionProvider) -> some View {
-        switch provider {
+    func channelSection(_ channel: ConnectionChannel) -> some View {
+        switch channel {
         case .whatsapp:
             self.whatsAppSection
         case .telegram:
@@ -318,8 +318,8 @@ extension ConnectionsSettings {
         }
     }
 
-    func providerTint(_ provider: ConnectionProvider) -> Color {
-        switch provider {
+    func channelTint(_ channel: ConnectionChannel) -> Color {
+        switch channel {
         case .whatsapp:
             self.whatsAppTint
         case .telegram:
@@ -333,8 +333,8 @@ extension ConnectionsSettings {
         }
     }
 
-    func providerSummary(_ provider: ConnectionProvider) -> String {
-        switch provider {
+    func channelSummary(_ channel: ConnectionChannel) -> String {
+        switch channel {
         case .whatsapp:
             self.whatsAppSummary
         case .telegram:
@@ -348,8 +348,8 @@ extension ConnectionsSettings {
         }
     }
 
-    func providerDetails(_ provider: ConnectionProvider) -> String? {
-        switch provider {
+    func channelDetails(_ channel: ConnectionChannel) -> String? {
+        switch channel {
         case .whatsapp:
             self.whatsAppDetails
         case .telegram:
@@ -363,55 +363,55 @@ extension ConnectionsSettings {
         }
     }
 
-    func providerLastCheckText(_ provider: ConnectionProvider) -> String {
-        guard let date = self.providerLastCheck(provider) else { return "never" }
+    func channelLastCheckText(_ channel: ConnectionChannel) -> String {
+        guard let date = self.channelLastCheck(channel) else { return "never" }
         return relativeAge(from: date)
     }
 
-    func providerLastCheck(_ provider: ConnectionProvider) -> Date? {
-        switch provider {
+    func channelLastCheck(_ channel: ConnectionChannel) -> Date? {
+        switch channel {
         case .whatsapp:
-            guard let status = self.providerStatus("whatsapp", as: ProvidersStatusSnapshot.WhatsAppStatus.self)
+            guard let status = self.channelStatus("whatsapp", as: ChannelsStatusSnapshot.WhatsAppStatus.self)
             else { return nil }
             return self.date(fromMs: status.lastEventAt ?? status.lastMessageAt ?? status.lastConnectedAt)
         case .telegram:
             return self
-                .date(fromMs: self.providerStatus("telegram", as: ProvidersStatusSnapshot.TelegramStatus.self)?
+                .date(fromMs: self.channelStatus("telegram", as: ChannelsStatusSnapshot.TelegramStatus.self)?
                     .lastProbeAt)
         case .discord:
             return self
-                .date(fromMs: self.providerStatus("discord", as: ProvidersStatusSnapshot.DiscordStatus.self)?
+                .date(fromMs: self.channelStatus("discord", as: ChannelsStatusSnapshot.DiscordStatus.self)?
                     .lastProbeAt)
         case .signal:
             return self
-                .date(fromMs: self.providerStatus("signal", as: ProvidersStatusSnapshot.SignalStatus.self)?.lastProbeAt)
+                .date(fromMs: self.channelStatus("signal", as: ChannelsStatusSnapshot.SignalStatus.self)?.lastProbeAt)
         case .imessage:
             return self
-                .date(fromMs: self.providerStatus("imessage", as: ProvidersStatusSnapshot.IMessageStatus.self)?
+                .date(fromMs: self.channelStatus("imessage", as: ChannelsStatusSnapshot.IMessageStatus.self)?
                     .lastProbeAt)
         }
     }
 
-    func providerHasError(_ provider: ConnectionProvider) -> Bool {
-        switch provider {
+    func channelHasError(_ channel: ConnectionChannel) -> Bool {
+        switch channel {
         case .whatsapp:
-            guard let status = self.providerStatus("whatsapp", as: ProvidersStatusSnapshot.WhatsAppStatus.self)
+            guard let status = self.channelStatus("whatsapp", as: ChannelsStatusSnapshot.WhatsAppStatus.self)
             else { return false }
             return status.lastError?.isEmpty == false || status.lastDisconnect?.loggedOut == true
         case .telegram:
-            guard let status = self.providerStatus("telegram", as: ProvidersStatusSnapshot.TelegramStatus.self)
+            guard let status = self.channelStatus("telegram", as: ChannelsStatusSnapshot.TelegramStatus.self)
             else { return false }
             return status.lastError?.isEmpty == false || status.probe?.ok == false
         case .discord:
-            guard let status = self.providerStatus("discord", as: ProvidersStatusSnapshot.DiscordStatus.self)
+            guard let status = self.channelStatus("discord", as: ChannelsStatusSnapshot.DiscordStatus.self)
             else { return false }
             return status.lastError?.isEmpty == false || status.probe?.ok == false
         case .signal:
-            guard let status = self.providerStatus("signal", as: ProvidersStatusSnapshot.SignalStatus.self)
+            guard let status = self.channelStatus("signal", as: ChannelsStatusSnapshot.SignalStatus.self)
             else { return false }
             return status.lastError?.isEmpty == false || status.probe?.ok == false
         case .imessage:
-            guard let status = self.providerStatus("imessage", as: ProvidersStatusSnapshot.IMessageStatus.self)
+            guard let status = self.channelStatus("imessage", as: ChannelsStatusSnapshot.IMessageStatus.self)
             else { return false }
             return status.lastError?.isEmpty == false || status.probe?.ok == false
         }

apps/macos/Sources/Clawdbot/ConnectionsSettings+View.swift

@@ -11,7 +11,7 @@ extension ConnectionsSettings {
             self.store.start()
             self.ensureSelection()
         }
-        .onChange(of: self.orderedProviders) { _, _ in
+        .onChange(of: self.orderedChannels) { _, _ in
             self.ensureSelection()
         }
         .onDisappear { self.store.stop() }
@@ -20,17 +20,17 @@ extension ConnectionsSettings {
     private var sidebar: some View {
         ScrollView {
             LazyVStack(alignment: .leading, spacing: 8) {
-                if !self.enabledProviders.isEmpty {
+                if !self.enabledChannels.isEmpty {
                     self.sidebarSectionHeader("Configured")
-                    ForEach(self.enabledProviders) { provider in
-                        self.sidebarRow(provider)
+                    ForEach(self.enabledChannels) { channel in
+                        self.sidebarRow(channel)
                     }
                 }
 
-                if !self.availableProviders.isEmpty {
+                if !self.availableChannels.isEmpty {
                     self.sidebarSectionHeader("Available")
-                    ForEach(self.availableProviders) { provider in
-                        self.sidebarRow(provider)
+                    ForEach(self.availableChannels) { channel in
+                        self.sidebarRow(channel)
                     }
                 }
             }
@@ -46,8 +46,8 @@ extension ConnectionsSettings {
 
     private var detail: some View {
         Group {
-            if let provider = self.selectedProvider {
-                self.providerDetail(provider)
+            if let channel = self.selectedChannel {
+                self.channelDetail(channel)
             } else {
                 self.emptyDetail
             }
@@ -59,7 +59,7 @@ extension ConnectionsSettings {
         VStack(alignment: .leading, spacing: 8) {
             Text("Connections")
                 .font(.title3.weight(.semibold))
-            Text("Select a provider to view status and settings.")
+            Text("Select a channel to view status and settings.")
                 .font(.callout)
                 .foregroundStyle(.secondary)
         }
@@ -67,12 +67,12 @@ extension ConnectionsSettings {
         .padding(.vertical, 18)
     }
 
-    private func providerDetail(_ provider: ConnectionProvider) -> some View {
+    private func channelDetail(_ channel: ConnectionChannel) -> some View {
         ScrollView(.vertical) {
             VStack(alignment: .leading, spacing: 16) {
-                self.detailHeader(for: provider)
+                self.detailHeader(for: channel)
                 Divider()
-                self.providerSection(provider)
+                self.channelSection(channel)
                 Spacer(minLength: 0)
             }
             .frame(maxWidth: .infinity, alignment: .leading)
@@ -81,18 +81,18 @@ extension ConnectionsSettings {
         }
     }
 
-    private func sidebarRow(_ provider: ConnectionProvider) -> some View {
-        let isSelected = self.selectedProvider == provider
+    private func sidebarRow(_ channel: ConnectionChannel) -> some View {
+        let isSelected = self.selectedChannel == channel
         return Button {
-            self.selectedProvider = provider
+            self.selectedChannel = channel
         } label: {
             HStack(spacing: 8) {
                 Circle()
-                    .fill(self.providerTint(provider))
+                    .fill(self.channelTint(channel))
                     .frame(width: 8, height: 8)
                 VStack(alignment: .leading, spacing: 2) {
-                    Text(provider.title)
-                    Text(self.providerSummary(provider))
+                    Text(channel.title)
+                    Text(self.channelSummary(channel))
                         .font(.caption)
                         .foregroundStyle(.secondary)
                 }
@@ -119,23 +119,23 @@ extension ConnectionsSettings {
             .padding(.top, 2)
     }
 
-    private func detailHeader(for provider: ConnectionProvider) -> some View {
+    private func detailHeader(for channel: ConnectionChannel) -> some View {
         VStack(alignment: .leading, spacing: 8) {
             HStack(alignment: .firstTextBaseline, spacing: 10) {
-                Label(provider.detailTitle, systemImage: provider.systemImage)
+                Label(channel.detailTitle, systemImage: channel.systemImage)
                     .font(.title3.weight(.semibold))
                 self.statusBadge(
-                    self.providerSummary(provider),
-                    color: self.providerTint(provider))
+                    self.channelSummary(channel),
+                    color: self.channelTint(channel))
                 Spacer()
-                self.providerHeaderActions(provider)
+                self.channelHeaderActions(channel)
             }
 
             HStack(spacing: 10) {
-                Text("Last check \(self.providerLastCheckText(provider))")
+                Text("Last check \(self.channelLastCheckText(channel))")
                     .font(.caption)
                     .foregroundStyle(.secondary)
-                if self.providerHasError(provider) {
+                if self.channelHasError(channel) {
                     Text("Error")
                         .font(.caption2.weight(.semibold))
                         .padding(.horizontal, 6)
@@ -146,7 +146,7 @@ extension ConnectionsSettings {
                 }
             }
 
-            if let details = self.providerDetails(provider) {
+            if let details = self.channelDetails(channel) {
                 Text(details)
                     .font(.caption)
                     .foregroundStyle(.secondary)

apps/macos/Sources/Clawdbot/ConnectionsSettings.swift

@@ -2,7 +2,7 @@ import AppKit
 import SwiftUI
 
 struct ConnectionsSettings: View {
-    enum ConnectionProvider: String, CaseIterable, Identifiable, Hashable {
+    enum ConnectionChannel: String, CaseIterable, Identifiable, Hashable {
         case whatsapp
         case telegram
         case discord
@@ -53,7 +53,7 @@ struct ConnectionsSettings: View {
     }
 
     @Bindable var store: ConnectionsStore
-    @State var selectedProvider: ConnectionProvider?
+    @State var selectedChannel: ConnectionChannel?
     @State var showTelegramToken = false
     @State var showDiscordToken = false
 

apps/macos/Sources/Clawdbot/ConnectionsStore+Config.swift

@@ -12,6 +12,7 @@ extension ConnectionsStore {
                 ? "Config invalid; fix it in ~/.clawdbot/clawdbot.json."
                 : nil
             self.configRoot = snap.config?.mapValues { $0.foundationValue } ?? [:]
+            self.configHash = snap.hash
             self.configLoaded = true
 
             self.applyUIConfig(snap)
@@ -34,10 +35,22 @@ extension ConnectionsStore {
         AppStateStore.shared.seamColorHex = rawSeam.isEmpty ? nil : rawSeam
     }
 
+    private func resolveChannelConfig(_ snap: ConfigSnapshot, key: String) -> [String: AnyCodable]? {
+        if let channels = snap.config?["channels"]?.dictionaryValue,
+           let entry = channels[key]?.dictionaryValue {
+            return entry
+        }
+        return snap.config?[key]?.dictionaryValue
+    }
+
     private func applyTelegramConfig(_ snap: ConfigSnapshot) {
-        let telegram = snap.config?["telegram"]?.dictionaryValue
+        let telegram = self.resolveChannelConfig(snap, key: "telegram")
         self.telegramToken = telegram?["botToken"]?.stringValue ?? ""
-        self.telegramRequireMention = telegram?["requireMention"]?.boolValue ?? true
+        let groups = telegram?["groups"]?.dictionaryValue
+        let defaultGroup = groups?["*"]?.dictionaryValue
+        self.telegramRequireMention = defaultGroup?["requireMention"]?.boolValue
+            ?? telegram?["requireMention"]?.boolValue
+            ?? true
         self.telegramAllowFrom = self.stringList(from: telegram?["allowFrom"]?.arrayValue)
         self.telegramProxy = telegram?["proxy"]?.stringValue ?? ""
         self.telegramWebhookUrl = telegram?["webhookUrl"]?.stringValue ?? ""
@@ -46,7 +59,7 @@ extension ConnectionsStore {
     }
 
     private func applyDiscordConfig(_ snap: ConfigSnapshot) {
-        let discord = snap.config?["discord"]?.dictionaryValue
+        let discord = self.resolveChannelConfig(snap, key: "discord")
         self.discordEnabled = discord?["enabled"]?.boolValue ?? true
         self.discordToken = discord?["token"]?.stringValue ?? ""
 
@@ -122,7 +135,7 @@ extension ConnectionsStore {
     }
 
     private func applySignalConfig(_ snap: ConfigSnapshot) {
-        let signal = snap.config?["signal"]?.dictionaryValue
+        let signal = self.resolveChannelConfig(snap, key: "signal")
         self.signalEnabled = signal?["enabled"]?.boolValue ?? true
         self.signalAccount = signal?["account"]?.stringValue ?? ""
         self.signalHttpUrl = signal?["httpUrl"]?.stringValue ?? ""
@@ -139,7 +152,7 @@ extension ConnectionsStore {
     }
 
     private func applyIMessageConfig(_ snap: ConfigSnapshot) {
-        let imessage = snap.config?["imessage"]?.dictionaryValue
+        let imessage = self.resolveChannelConfig(snap, key: "imessage")
         self.imessageEnabled = imessage?["enabled"]?.boolValue ?? true
         self.imessageCliPath = imessage?["cliPath"]?.stringValue ?? ""
         self.imessageDbPath = imessage?["dbPath"]?.stringValue ?? ""
@@ -150,6 +163,15 @@ extension ConnectionsStore {
         self.imessageMediaMaxMb = self.numberString(from: imessage?["mediaMaxMb"])
     }
 
+    private func channelConfigRoot(for key: String) -> [String: Any] {
+        if let channels = self.configRoot["channels"] as? [String: Any],
+           let entry = channels[key] as? [String: Any]
+        {
+            return entry
+        }
+        return self.configRoot[key] as? [String: Any] ?? [:]
+    }
+
     func saveTelegramConfig() async {
         guard !self.isSavingConfig else { return }
         self.isSavingConfig = true
@@ -158,30 +180,24 @@ extension ConnectionsStore {
             await self.loadConfig()
         }
 
-        var telegram: [String: Any] = (self.configRoot["telegram"] as? [String: Any]) ?? [:]
-        let token = self.trimmed(self.telegramToken)
-        if token.isEmpty {
-            telegram.removeValue(forKey: "botToken")
-        } else {
-            telegram["botToken"] = token
+        var telegram: [String: Any] = [:]
+        if !self.isTelegramTokenLocked {
+            self.setPatchString(&telegram, key: "botToken", value: self.telegramToken)
         }
-
-        telegram["requireMention"] = self.telegramRequireMention
-
+        telegram["requireMention"] = NSNull()
+        telegram["groups"] = [
+            "*": [
+                "requireMention": self.telegramRequireMention,
+            ],
+        ]
         let allow = self.splitCsv(self.telegramAllowFrom)
-        if allow.isEmpty {
-            telegram.removeValue(forKey: "allowFrom")
-        } else {
-            telegram["allowFrom"] = allow
-        }
+        self.setPatchList(&telegram, key: "allowFrom", values: allow)
+        self.setPatchString(&telegram, key: "proxy", value: self.telegramProxy)
+        self.setPatchString(&telegram, key: "webhookUrl", value: self.telegramWebhookUrl)
+        self.setPatchString(&telegram, key: "webhookSecret", value: self.telegramWebhookSecret)
+        self.setPatchString(&telegram, key: "webhookPath", value: self.telegramWebhookPath)
 
-        self.setOptionalString(&telegram, key: "proxy", value: self.telegramProxy)
-        self.setOptionalString(&telegram, key: "webhookUrl", value: self.telegramWebhookUrl)
-        self.setOptionalString(&telegram, key: "webhookSecret", value: self.telegramWebhookSecret)
-        self.setOptionalString(&telegram, key: "webhookPath", value: self.telegramWebhookPath)
-
-        self.setSection("telegram", payload: telegram)
-        await self.persistConfig()
+        await self.persistChannelPatch("telegram", payload: telegram)
     }
 
     func saveDiscordConfig() async {
@@ -192,9 +208,9 @@ extension ConnectionsStore {
             await self.loadConfig()
         }
 
-        let discord = self.buildDiscordConfig()
-        self.setSection("discord", payload: discord)
-        await self.persistConfig()
+        let base = self.channelConfigRoot(for: "discord")
+        let discord = self.buildDiscordPatch(base: base)
+        await self.persistChannelPatch("discord", payload: discord)
     }
 
     func saveSignalConfig() async {
@@ -205,42 +221,23 @@ extension ConnectionsStore {
             await self.loadConfig()
         }
 
-        var signal: [String: Any] = (self.configRoot["signal"] as? [String: Any]) ?? [:]
-        if self.signalEnabled {
-            signal.removeValue(forKey: "enabled")
-        } else {
-            signal["enabled"] = false
-        }
-
-        self.setOptionalString(&signal, key: "account", value: self.signalAccount)
-        self.setOptionalString(&signal, key: "httpUrl", value: self.signalHttpUrl)
-        self.setOptionalString(&signal, key: "httpHost", value: self.signalHttpHost)
-        self.setOptionalNumber(&signal, key: "httpPort", value: self.signalHttpPort)
-        self.setOptionalString(&signal, key: "cliPath", value: self.signalCliPath)
-
-        if self.signalAutoStart {
-            signal.removeValue(forKey: "autoStart")
-        } else {
-            signal["autoStart"] = false
-        }
-
-        self.setOptionalString(&signal, key: "receiveMode", value: self.signalReceiveMode)
-
-        self.setOptionalBool(&signal, key: "ignoreAttachments", value: self.signalIgnoreAttachments)
-        self.setOptionalBool(&signal, key: "ignoreStories", value: self.signalIgnoreStories)
-        self.setOptionalBool(&signal, key: "sendReadReceipts", value: self.signalSendReadReceipts)
-
+        var signal: [String: Any] = [:]
+        self.setPatchBool(&signal, key: "enabled", value: self.signalEnabled, defaultValue: true)
+        self.setPatchString(&signal, key: "account", value: self.signalAccount)
+        self.setPatchString(&signal, key: "httpUrl", value: self.signalHttpUrl)
+        self.setPatchString(&signal, key: "httpHost", value: self.signalHttpHost)
+        self.setPatchNumber(&signal, key: "httpPort", value: self.signalHttpPort)
+        self.setPatchString(&signal, key: "cliPath", value: self.signalCliPath)
+        self.setPatchBool(&signal, key: "autoStart", value: self.signalAutoStart, defaultValue: true)
+        self.setPatchString(&signal, key: "receiveMode", value: self.signalReceiveMode)
+        self.setPatchBool(&signal, key: "ignoreAttachments", value: self.signalIgnoreAttachments, defaultValue: false)
+        self.setPatchBool(&signal, key: "ignoreStories", value: self.signalIgnoreStories, defaultValue: false)
+        self.setPatchBool(&signal, key: "sendReadReceipts", value: self.signalSendReadReceipts, defaultValue: false)
         let allow = self.splitCsv(self.signalAllowFrom)
-        if allow.isEmpty {
-            signal.removeValue(forKey: "allowFrom")
-        } else {
-            signal["allowFrom"] = allow
-        }
+        self.setPatchList(&signal, key: "allowFrom", values: allow)
+        self.setPatchNumber(&signal, key: "mediaMaxMb", value: self.signalMediaMaxMb)
 
-        self.setOptionalNumber(&signal, key: "mediaMaxMb", value: self.signalMediaMaxMb)
-
-        self.setSection("signal", payload: signal)
-        await self.persistConfig()
+        await self.persistChannelPatch("signal", payload: signal)
     }
 
     func saveIMessageConfig() async {
@@ -251,147 +248,168 @@ extension ConnectionsStore {
             await self.loadConfig()
         }
 
-        var imessage: [String: Any] = (self.configRoot["imessage"] as? [String: Any]) ?? [:]
-        if self.imessageEnabled {
-            imessage.removeValue(forKey: "enabled")
-        } else {
-            imessage["enabled"] = false
-        }
-
-        self.setOptionalString(&imessage, key: "cliPath", value: self.imessageCliPath)
-        self.setOptionalString(&imessage, key: "dbPath", value: self.imessageDbPath)
+        var imessage: [String: Any] = [:]
+        self.setPatchBool(&imessage, key: "enabled", value: self.imessageEnabled, defaultValue: true)
+        self.setPatchString(&imessage, key: "cliPath", value: self.imessageCliPath)
+        self.setPatchString(&imessage, key: "dbPath", value: self.imessageDbPath)
 
         let service = self.trimmed(self.imessageService)
         if service.isEmpty || service == "auto" {
-            imessage.removeValue(forKey: "service")
+            imessage["service"] = NSNull()
         } else {
             imessage["service"] = service
         }
 
-        self.setOptionalString(&imessage, key: "region", value: self.imessageRegion)
+        self.setPatchString(&imessage, key: "region", value: self.imessageRegion)
 
         let allow = self.splitCsv(self.imessageAllowFrom)
-        if allow.isEmpty {
-            imessage.removeValue(forKey: "allowFrom")
-        } else {
-            imessage["allowFrom"] = allow
-        }
+        self.setPatchList(&imessage, key: "allowFrom", values: allow)
 
-        self.setOptionalBool(&imessage, key: "includeAttachments", value: self.imessageIncludeAttachments)
-        self.setOptionalNumber(&imessage, key: "mediaMaxMb", value: self.imessageMediaMaxMb)
+        self.setPatchBool(
+            &imessage,
+            key: "includeAttachments",
+            value: self.imessageIncludeAttachments,
+            defaultValue: false)
+        self.setPatchNumber(&imessage, key: "mediaMaxMb", value: self.imessageMediaMaxMb)
 
-        self.setSection("imessage", payload: imessage)
-        await self.persistConfig()
+        await self.persistChannelPatch("imessage", payload: imessage)
     }
 
-    private func buildDiscordConfig() -> [String: Any] {
-        var discord: [String: Any] = (self.configRoot["discord"] as? [String: Any]) ?? [:]
-        if self.discordEnabled {
-            discord.removeValue(forKey: "enabled")
-        } else {
-            discord["enabled"] = false
+    private func buildDiscordPatch(base: [String: Any]) -> [String: Any] {
+        var discord: [String: Any] = [:]
+        self.setPatchBool(&discord, key: "enabled", value: self.discordEnabled, defaultValue: true)
+        if !self.isDiscordTokenLocked {
+            self.setPatchString(&discord, key: "token", value: self.discordToken)
         }
-        self.setOptionalString(&discord, key: "token", value: self.discordToken)
 
-        if let dm = self.buildDiscordDmConfig(base: discord["dm"] as? [String: Any] ?? [:]) {
+        if let dm = self.buildDiscordDmPatch() {
             discord["dm"] = dm
         } else {
-            discord.removeValue(forKey: "dm")
+            discord["dm"] = NSNull()
         }
 
-        self.setOptionalNumber(&discord, key: "mediaMaxMb", value: self.discordMediaMaxMb)
-        self.setOptionalInt(&discord, key: "historyLimit", value: self.discordHistoryLimit, allowZero: true)
-        self.setOptionalInt(&discord, key: "textChunkLimit", value: self.discordTextChunkLimit, allowZero: false)
+        self.setPatchNumber(&discord, key: "mediaMaxMb", value: self.discordMediaMaxMb)
+        self.setPatchInt(&discord, key: "historyLimit", value: self.discordHistoryLimit, allowZero: true)
+        self.setPatchInt(&discord, key: "textChunkLimit", value: self.discordTextChunkLimit, allowZero: false)
 
         let replyToMode = self.trimmed(self.discordReplyToMode)
-        if replyToMode.isEmpty || replyToMode == "off" {
-            discord.removeValue(forKey: "replyToMode")
-        } else if ["first", "all"].contains(replyToMode) {
-            discord["replyToMode"] = replyToMode
+        if replyToMode.isEmpty || replyToMode == "off" || !["first", "all"].contains(replyToMode) {
+            discord["replyToMode"] = NSNull()
         } else {
-            discord.removeValue(forKey: "replyToMode")
+            discord["replyToMode"] = replyToMode
         }
 
-        if let guilds = self.buildDiscordGuildsConfig() {
+        let baseGuilds = base["guilds"] as? [String: Any] ?? [:]
+        if let guilds = self.buildDiscordGuildsPatch(base: baseGuilds) {
             discord["guilds"] = guilds
         } else {
-            discord.removeValue(forKey: "guilds")
+            discord["guilds"] = NSNull()
         }
 
-        if let actions = self.buildDiscordActionsConfig(base: discord["actions"] as? [String: Any] ?? [:]) {
+        if let actions = self.buildDiscordActionsPatch() {
             discord["actions"] = actions
         } else {
-            discord.removeValue(forKey: "actions")
+            discord["actions"] = NSNull()
         }
 
-        if let slash = self.buildDiscordSlashConfig(base: discord["slashCommand"] as? [String: Any] ?? [:]) {
+        if let slash = self.buildDiscordSlashPatch() {
             discord["slashCommand"] = slash
         } else {
-            discord.removeValue(forKey: "slashCommand")
+            discord["slashCommand"] = NSNull()
         }
 
         return discord
     }
 
-    private func buildDiscordDmConfig(base: [String: Any]) -> [String: Any]? {
-        var dm = base
-        if self.discordDmEnabled {
-            dm.removeValue(forKey: "enabled")
-        } else {
-            dm["enabled"] = false
-        }
+    private func buildDiscordDmPatch() -> [String: Any]? {
+        var dm: [String: Any] = [:]
+        self.setPatchBool(&dm, key: "enabled", value: self.discordDmEnabled, defaultValue: true)
         let allow = self.splitCsv(self.discordAllowFrom)
-        if allow.isEmpty {
-            dm.removeValue(forKey: "allowFrom")
-        } else {
-            dm["allowFrom"] = allow
-        }
-
-        if self.discordGroupEnabled {
-            dm["groupEnabled"] = true
-        } else {
-            dm.removeValue(forKey: "groupEnabled")
-        }
-
+        self.setPatchList(&dm, key: "allowFrom", values: allow)
+        self.setPatchBool(&dm, key: "groupEnabled", value: self.discordGroupEnabled, defaultValue: false)
         let groupChannels = self.splitCsv(self.discordGroupChannels)
-        if groupChannels.isEmpty {
-            dm.removeValue(forKey: "groupChannels")
-        } else {
-            dm["groupChannels"] = groupChannels
-        }
-
+        self.setPatchList(&dm, key: "groupChannels", values: groupChannels)
         return dm.isEmpty ? nil : dm
     }
 
-    private func buildDiscordGuildsConfig() -> [String: Any]? {
-        let guilds: [String: Any] = self.discordGuilds.reduce(into: [:]) { result, entry in
-            let key = self.trimmed(entry.key)
-            guard !key.isEmpty else { return }
-            var payload: [String: Any] = [:]
-            let slug = self.trimmed(entry.slug)
-            if !slug.isEmpty { payload["slug"] = slug }
-            if entry.requireMention { payload["requireMention"] = true }
-            if ["off", "own", "all", "allowlist"].contains(entry.reactionNotifications) {
-                payload["reactionNotifications"] = entry.reactionNotifications
-            }
-            let users = self.splitCsv(entry.users)
-            if !users.isEmpty { payload["users"] = users }
-            let channels: [String: Any] = entry.channels.reduce(into: [:]) { channelsResult, channel in
-                let channelKey = self.trimmed(channel.key)
-                guard !channelKey.isEmpty else { return }
-                var channelPayload: [String: Any] = [:]
-                if !channel.allow { channelPayload["allow"] = false }
-                if channel.requireMention { channelPayload["requireMention"] = true }
-                channelsResult[channelKey] = channelPayload
-            }
-            if !channels.isEmpty { payload["channels"] = channels }
-            result[key] = payload
+    private func buildDiscordGuildsPatch(base: [String: Any]) -> Any? {
+        if self.discordGuilds.isEmpty {
+            return NSNull()
         }
-        return guilds.isEmpty ? nil : guilds
+        var patch: [String: Any] = [:]
+        let baseKeys = Set(base.keys)
+        var formKeys = Set<String>()
+        for entry in self.discordGuilds {
+            let key = self.trimmed(entry.key)
+            guard !key.isEmpty else { continue }
+            formKeys.insert(key)
+            let baseGuild = base[key] as? [String: Any] ?? [:]
+            patch[key] = self.buildDiscordGuildPatch(entry, base: baseGuild)
+        }
+        for key in baseKeys.subtracting(formKeys) {
+            patch[key] = NSNull()
+        }
+        return patch.isEmpty ? NSNull() : patch
     }
 
-    private func buildDiscordActionsConfig(base: [String: Any]) -> [String: Any]? {
-        var actions = base
+    private func buildDiscordGuildPatch(_ entry: DiscordGuildForm, base: [String: Any]) -> [String: Any] {
+        var payload: [String: Any] = [:]
+        let slug = self.trimmed(entry.slug)
+        if slug.isEmpty {
+            payload["slug"] = NSNull()
+        } else {
+            payload["slug"] = slug
+        }
+        if entry.requireMention {
+            payload["requireMention"] = true
+        } else {
+            payload["requireMention"] = NSNull()
+        }
+        if ["off", "all", "allowlist"].contains(entry.reactionNotifications) {
+            payload["reactionNotifications"] = entry.reactionNotifications
+        } else {
+            payload["reactionNotifications"] = NSNull()
+        }
+        let users = self.splitCsv(entry.users)
+        self.setPatchList(&payload, key: "users", values: users)
+
+        let baseChannels = base["channels"] as? [String: Any] ?? [:]
+        if let channels = self.buildDiscordChannelsPatch(base: baseChannels, forms: entry.channels) {
+            payload["channels"] = channels
+        } else {
+            payload["channels"] = NSNull()
+        }
+        return payload
+    }
+
+    private func buildDiscordChannelsPatch(base: [String: Any], forms: [DiscordGuildChannelForm]) -> Any? {
+        if forms.isEmpty {
+            return NSNull()
+        }
+        var patch: [String: Any] = [:]
+        let baseKeys = Set(base.keys)
+        var formKeys = Set<String>()
+        for channel in forms {
+            let channelKey = self.trimmed(channel.key)
+            guard !channelKey.isEmpty else { continue }
+            formKeys.insert(channelKey)
+            var channelPayload: [String: Any] = [:]
+            self.setPatchBool(&channelPayload, key: "allow", value: channel.allow, defaultValue: true)
+            self.setPatchBool(
+                &channelPayload,
+                key: "requireMention",
+                value: channel.requireMention,
+                defaultValue: false)
+            patch[channelKey] = channelPayload
+        }
+        for key in baseKeys.subtracting(formKeys) {
+            patch[key] = NSNull()
+        }
+        return patch.isEmpty ? NSNull() : patch
+    }
+
+    private func buildDiscordActionsPatch() -> [String: Any]? {
+        var actions: [String: Any] = [:]
         self.setAction(&actions, key: "reactions", value: self.discordActionReactions, defaultValue: true)
         self.setAction(&actions, key: "stickers", value: self.discordActionStickers, defaultValue: true)
         self.setAction(&actions, key: "polls", value: self.discordActionPolls, defaultValue: true)
@@ -410,52 +428,44 @@ extension ConnectionsStore {
         return actions.isEmpty ? nil : actions
     }
 
-    private func buildDiscordSlashConfig(base: [String: Any]) -> [String: Any]? {
-        var slash = base
-        if self.discordSlashEnabled {
-            slash["enabled"] = true
-        } else {
-            slash.removeValue(forKey: "enabled")
-        }
-        self.setOptionalString(&slash, key: "name", value: self.discordSlashName)
-        self.setOptionalString(&slash, key: "sessionPrefix", value: self.discordSlashSessionPrefix)
-        if self.discordSlashEphemeral {
-            slash.removeValue(forKey: "ephemeral")
-        } else {
-            slash["ephemeral"] = false
-        }
+    private func buildDiscordSlashPatch() -> [String: Any]? {
+        var slash: [String: Any] = [:]
+        self.setPatchBool(&slash, key: "enabled", value: self.discordSlashEnabled, defaultValue: false)
+        self.setPatchString(&slash, key: "name", value: self.discordSlashName)
+        self.setPatchString(&slash, key: "sessionPrefix", value: self.discordSlashSessionPrefix)
+        self.setPatchBool(&slash, key: "ephemeral", value: self.discordSlashEphemeral, defaultValue: true)
         return slash.isEmpty ? nil : slash
     }
 
-    private func persistConfig() async {
+    private func persistChannelPatch(_ channelId: String, payload: [String: Any]) async {
         do {
+            guard let baseHash = self.configHash else {
+                self.configStatus = "Config hash missing; reload and retry."
+                return
+            }
             let data = try JSONSerialization.data(
-                withJSONObject: self.configRoot,
+                withJSONObject: ["channels": [channelId: payload]],
                 options: [.prettyPrinted, .sortedKeys])
             guard let raw = String(data: data, encoding: .utf8) else {
                 self.configStatus = "Failed to encode config."
                 return
             }
-            let params: [String: AnyCodable] = ["raw": AnyCodable(raw)]
+            let params: [String: AnyCodable] = [
+                "raw": AnyCodable(raw),
+                "baseHash": AnyCodable(baseHash),
+            ]
             _ = try await GatewayConnection.shared.requestRaw(
-                method: .configSet,
+                method: .configPatch,
                 params: params,
                 timeoutMs: 10000)
             self.configStatus = "Saved to ~/.clawdbot/clawdbot.json."
+            await self.loadConfig()
             await self.refresh(probe: true)
         } catch {
             self.configStatus = error.localizedDescription
         }
     }
 
-    private func setSection(_ key: String, payload: [String: Any]) {
-        if payload.isEmpty {
-            self.configRoot.removeValue(forKey: key)
-        } else {
-            self.configRoot[key] = payload
-        }
-    }
-
     private func stringList(from values: [AnyCodable]?) -> String {
         guard let values else { return "" }
         let strings = values.compactMap { entry -> String? in
@@ -492,25 +502,29 @@ extension ConnectionsStore {
         value.trimmingCharacters(in: .whitespacesAndNewlines)
     }
 
-    private func setOptionalString(_ target: inout [String: Any], key: String, value: String) {
+    private func setPatchString(_ target: inout [String: Any], key: String, value: String) {
         let trimmed = self.trimmed(value)
         if trimmed.isEmpty {
-            target.removeValue(forKey: key)
+            target[key] = NSNull()
         } else {
             target[key] = trimmed
         }
     }
 
-    private func setOptionalNumber(_ target: inout [String: Any], key: String, value: String) {
+    private func setPatchNumber(_ target: inout [String: Any], key: String, value: String) {
         let trimmed = self.trimmed(value)
         if trimmed.isEmpty {
-            target.removeValue(forKey: key)
-        } else if let number = Double(trimmed) {
+            target[key] = NSNull()
+            return
+        }
+        if let number = Double(trimmed) {
             target[key] = number
+        } else {
+            target[key] = NSNull()
         }
     }
 
-    private func setOptionalInt(
+    private func setPatchInt(
         _ target: inout [String: Any],
         key: String,
         value: String,
@@ -518,26 +532,39 @@ extension ConnectionsStore {
     {
         let trimmed = self.trimmed(value)
         if trimmed.isEmpty {
-            target.removeValue(forKey: key)
+            target[key] = NSNull()
             return
         }
         guard let number = Int(trimmed) else {
-            target.removeValue(forKey: key)
+            target[key] = NSNull()
             return
         }
         let isValid = allowZero ? number >= 0 : number > 0
         guard isValid else {
-            target.removeValue(forKey: key)
+            target[key] = NSNull()
             return
         }
         target[key] = number
     }
 
-    private func setOptionalBool(_ target: inout [String: Any], key: String, value: Bool) {
-        if value {
-            target[key] = true
+    private func setPatchBool(
+        _ target: inout [String: Any],
+        key: String,
+        value: Bool,
+        defaultValue: Bool)
+    {
+        if value == defaultValue {
+            target[key] = NSNull()
         } else {
-            target.removeValue(forKey: key)
+            target[key] = value
+        }
+    }
+
+    private func setPatchList(_ target: inout [String: Any], key: String, values: [String]) {
+        if values.isEmpty {
+            target[key] = NSNull()
+        } else {
+            target[key] = values
         }
     }
 
@@ -548,7 +575,7 @@ extension ConnectionsStore {
         defaultValue: Bool)
     {
         if value == defaultValue {
-            actions.removeValue(forKey: key)
+            actions[key] = NSNull()
         } else {
             actions[key] = value
         }

apps/macos/Sources/Clawdbot/ConnectionsStore+Lifecycle.swift

@@ -31,8 +31,8 @@ extension ConnectionsStore {
                 "probe": AnyCodable(probe),
                 "timeoutMs": AnyCodable(8000),
             ]
-            let snap: ProvidersStatusSnapshot = try await GatewayConnection.shared.requestDecoded(
-                method: .providersStatus,
+            let snap: ChannelsStatusSnapshot = try await GatewayConnection.shared.requestDecoded(
+                method: .channelsStatus,
                 params: params,
                 timeoutMs: 12000)
             self.snapshot = snap
@@ -101,10 +101,10 @@ extension ConnectionsStore {
         defer { self.whatsappBusy = false }
         do {
             let params: [String: AnyCodable] = [
-                "provider": AnyCodable("whatsapp"),
+                "channel": AnyCodable("whatsapp"),
             ]
-            let result: ProviderLogoutResult = try await GatewayConnection.shared.requestDecoded(
-                method: .providersLogout,
+            let result: ChannelLogoutResult = try await GatewayConnection.shared.requestDecoded(
+                method: .channelsLogout,
                 params: params,
                 timeoutMs: 15000)
             self.whatsappLoginMessage = result.cleared
@@ -123,10 +123,10 @@ extension ConnectionsStore {
         defer { self.telegramBusy = false }
         do {
             let params: [String: AnyCodable] = [
-                "provider": AnyCodable("telegram"),
+                "channel": AnyCodable("telegram"),
             ]
-            let result: ProviderLogoutResult = try await GatewayConnection.shared.requestDecoded(
-                method: .providersLogout,
+            let result: ChannelLogoutResult = try await GatewayConnection.shared.requestDecoded(
+                method: .channelsLogout,
                 params: params,
                 timeoutMs: 15000)
             if result.envToken == true {
@@ -154,8 +154,8 @@ private struct WhatsAppLoginWaitResult: Codable {
     let message: String
 }
 
-private struct ProviderLogoutResult: Codable {
-    let provider: String?
+private struct ChannelLogoutResult: Codable {
+    let channel: String?
     let accountId: String?
     let cleared: Bool
     let envToken: Bool?

apps/macos/Sources/Clawdbot/ConnectionsStore.swift

@@ -2,7 +2,7 @@ import ClawdbotProtocol
 import Foundation
 import Observation
 
-struct ProvidersStatusSnapshot: Codable {
+struct ChannelsStatusSnapshot: Codable {
     struct WhatsAppSelf: Codable {
         let e164: String?
         let jid: String?
@@ -121,7 +121,7 @@ struct ProvidersStatusSnapshot: Codable {
         let lastProbeAt: Double?
     }
 
-    struct ProviderAccountSnapshot: Codable {
+    struct ChannelAccountSnapshot: Codable {
         let accountId: String
         let name: String?
         let enabled: Bool?
@@ -154,14 +154,14 @@ struct ProvidersStatusSnapshot: Codable {
     }
 
     let ts: Double
-    let providerOrder: [String]
-    let providerLabels: [String: String]
-    let providers: [String: AnyCodable]
-    let providerAccounts: [String: [ProviderAccountSnapshot]]
-    let providerDefaultAccountId: [String: String]
+    let channelOrder: [String]
+    let channelLabels: [String: String]
+    let channels: [String: AnyCodable]
+    let channelAccounts: [String: [ChannelAccountSnapshot]]
+    let channelDefaultAccountId: [String: String]
 
-    func decodeProvider<T: Decodable>(_ id: String, as type: T.Type) -> T? {
-        guard let value = self.providers[id] else { return nil }
+    func decodeChannel<T: Decodable>(_ id: String, as type: T.Type) -> T? {
+        guard let value = self.channels[id] else { return nil }
         do {
             let data = try JSONEncoder().encode(value)
             return try JSONDecoder().decode(type, from: data)
@@ -180,6 +180,7 @@ struct ConfigSnapshot: Codable {
     let path: String?
     let exists: Bool?
     let raw: String?
+    let hash: String?
     let parsed: AnyCodable?
     let valid: Bool?
     let config: [String: AnyCodable]?
@@ -230,7 +231,7 @@ struct DiscordGuildForm: Identifiable {
 final class ConnectionsStore {
     static let shared = ConnectionsStore()
 
-    var snapshot: ProvidersStatusSnapshot?
+    var snapshot: ChannelsStatusSnapshot?
     var lastError: String?
     var lastSuccess: Date?
     var isRefreshing = false
@@ -307,6 +308,7 @@ final class ConnectionsStore {
     var pollTask: Task<Void, Never>?
     var configRoot: [String: Any] = [:]
     var configLoaded = false
+    var configHash: String?
 
     init(isPreview: Bool = ProcessInfo.processInfo.isPreview) {
         self.isPreview = isPreview

apps/macos/Sources/Clawdbot/CronJobEditor+Helpers.swift

@@ -36,13 +36,13 @@ extension CronJobEditor {
         case let .systemEvent(text):
             self.payloadKind = .systemEvent
             self.systemEventText = text
-        case let .agentTurn(message, thinking, timeoutSeconds, deliver, provider, to, bestEffortDeliver):
+        case let .agentTurn(message, thinking, timeoutSeconds, deliver, channel, to, bestEffortDeliver):
             self.payloadKind = .agentTurn
             self.agentMessage = message
             self.thinking = thinking ?? ""
             self.timeoutSeconds = timeoutSeconds.map(String.init) ?? ""
             self.deliver = deliver ?? false
-            self.provider = GatewayAgentProvider(raw: provider)
+            self.channel = GatewayAgentChannel(raw: channel)
             self.to = to ?? ""
             self.bestEffortDeliver = bestEffortDeliver ?? false
         }
@@ -204,7 +204,7 @@ extension CronJobEditor {
         if let n = Int(self.timeoutSeconds), n > 0 { payload["timeoutSeconds"] = n }
         payload["deliver"] = self.deliver
         if self.deliver {
-            payload["provider"] = self.provider.rawValue
+            payload["channel"] = self.channel.rawValue
             let to = self.to.trimmingCharacters(in: .whitespacesAndNewlines)
             if !to.isEmpty { payload["to"] = to }
             payload["bestEffortDeliver"] = self.bestEffortDeliver

apps/macos/Sources/Clawdbot/CronJobEditor+Testing.swift

@@ -14,7 +14,7 @@ extension CronJobEditor {
         self.payloadKind = .agentTurn
         self.agentMessage = "Run diagnostic"
         self.deliver = true
-        self.provider = .last
+        self.channel = .last
         self.to = "+15551230000"
         self.thinking = "low"
         self.timeoutSeconds = "90"

apps/macos/Sources/Clawdbot/CronJobEditor.swift

@@ -18,7 +18,7 @@ struct CronJobEditor: View {
     static let scheduleKindNote =
         "“At” runs once, “Every” repeats with a duration, “Cron” uses a 5-field Unix expression."
     static let isolatedPayloadNote =
-        "Isolated jobs always run an agent turn. The result can be delivered to a provider, "
+        "Isolated jobs always run an agent turn. The result can be delivered to a channel, "
             + "and a short summary is posted back to your main chat."
     static let mainPayloadNote =
         "System events are injected into the current main session. Agent turns require an isolated session target."
@@ -45,7 +45,7 @@ struct CronJobEditor: View {
     @State var systemEventText: String = ""
     @State var agentMessage: String = ""
     @State var deliver: Bool = false
-    @State var provider: GatewayAgentProvider = .last
+    @State var channel: GatewayAgentChannel = .last
     @State var to: String = ""
     @State var thinking: String = ""
     @State var timeoutSeconds: String = ""
@@ -323,7 +323,7 @@ struct CronJobEditor: View {
                 }
                 GridRow {
                     self.gridLabel("Deliver")
-                    Toggle("Deliver result to a provider", isOn: self.$deliver)
+                    Toggle("Deliver result to a channel", isOn: self.$deliver)
                         .toggleStyle(.switch)
                 }
             }
@@ -331,15 +331,15 @@ struct CronJobEditor: View {
             if self.deliver {
                 Grid(alignment: .leadingFirstTextBaseline, horizontalSpacing: 14, verticalSpacing: 10) {
                     GridRow {
-                        self.gridLabel("Provider")
-                        Picker("", selection: self.$provider) {
-                            Text("last").tag(GatewayAgentProvider.last)
-                            Text("whatsapp").tag(GatewayAgentProvider.whatsapp)
-                            Text("telegram").tag(GatewayAgentProvider.telegram)
-                            Text("discord").tag(GatewayAgentProvider.discord)
-                            Text("slack").tag(GatewayAgentProvider.slack)
-                            Text("signal").tag(GatewayAgentProvider.signal)
-                            Text("imessage").tag(GatewayAgentProvider.imessage)
+                        self.gridLabel("Channel")
+                        Picker("", selection: self.$channel) {
+                            Text("last").tag(GatewayAgentChannel.last)
+                            Text("whatsapp").tag(GatewayAgentChannel.whatsapp)
+                            Text("telegram").tag(GatewayAgentChannel.telegram)
+                            Text("discord").tag(GatewayAgentChannel.discord)
+                            Text("slack").tag(GatewayAgentChannel.slack)
+                            Text("signal").tag(GatewayAgentChannel.signal)
+                            Text("imessage").tag(GatewayAgentChannel.imessage)
                         }
                         .labelsHidden()
                         .pickerStyle(.segmented)

apps/macos/Sources/Clawdbot/CronModels.swift

@@ -74,12 +74,12 @@ enum CronPayload: Codable, Equatable {
         thinking: String?,
         timeoutSeconds: Int?,
         deliver: Bool?,
-        provider: String?,
+        channel: String?,
         to: String?,
         bestEffortDeliver: Bool?)
 
     enum CodingKeys: String, CodingKey {
-        case kind, text, message, thinking, timeoutSeconds, deliver, provider, to, bestEffortDeliver
+        case kind, text, message, thinking, timeoutSeconds, deliver, channel, provider, to, bestEffortDeliver
     }
 
     var kind: String {
@@ -101,7 +101,8 @@ enum CronPayload: Codable, Equatable {
                 thinking: container.decodeIfPresent(String.self, forKey: .thinking),
                 timeoutSeconds: container.decodeIfPresent(Int.self, forKey: .timeoutSeconds),
                 deliver: container.decodeIfPresent(Bool.self, forKey: .deliver),
-                provider: container.decodeIfPresent(String.self, forKey: .provider),
+                channel: container.decodeIfPresent(String.self, forKey: .channel)
+                    ?? container.decodeIfPresent(String.self, forKey: .provider),
                 to: container.decodeIfPresent(String.self, forKey: .to),
                 bestEffortDeliver: container.decodeIfPresent(Bool.self, forKey: .bestEffortDeliver))
         default:
@@ -118,12 +119,12 @@ enum CronPayload: Codable, Equatable {
         switch self {
         case let .systemEvent(text):
             try container.encode(text, forKey: .text)
-        case let .agentTurn(message, thinking, timeoutSeconds, deliver, provider, to, bestEffortDeliver):
+        case let .agentTurn(message, thinking, timeoutSeconds, deliver, channel, to, bestEffortDeliver):
             try container.encode(message, forKey: .message)
             try container.encodeIfPresent(thinking, forKey: .thinking)
             try container.encodeIfPresent(timeoutSeconds, forKey: .timeoutSeconds)
             try container.encodeIfPresent(deliver, forKey: .deliver)
-            try container.encodeIfPresent(provider, forKey: .provider)
+            try container.encodeIfPresent(channel, forKey: .channel)
             try container.encodeIfPresent(to, forKey: .to)
             try container.encodeIfPresent(bestEffortDeliver, forKey: .bestEffortDeliver)
         }

apps/macos/Sources/Clawdbot/CronSettings+Testing.swift

@@ -22,7 +22,7 @@ struct CronSettings_Previews: PreviewProvider {
                     thinking: "low",
                     timeoutSeconds: 600,
                     deliver: true,
-                    provider: "last",
+                    channel: "last",
                     to: nil,
                     bestEffortDeliver: true),
                 isolation: CronIsolation(postToMainPrefix: "Cron"),
@@ -76,7 +76,7 @@ extension CronSettings {
                 thinking: "low",
                 timeoutSeconds: 120,
                 deliver: true,
-                provider: "whatsapp",
+                channel: "whatsapp",
                 to: "+15551234567",
                 bestEffortDeliver: true),
             isolation: CronIsolation(postToMainPrefix: "[cron] "),

apps/macos/Sources/Clawdbot/DeepLinks.swift

@@ -59,7 +59,7 @@ final class DeepLinkHandler {
         }
 
         do {
-            let provider = GatewayAgentProvider(raw: link.channel)
+            let channel = GatewayAgentChannel(raw: link.channel)
             let explicitSessionKey = link.sessionKey?
                 .trimmingCharacters(in: .whitespacesAndNewlines)
                 .nonEmpty
@@ -72,9 +72,9 @@ final class DeepLinkHandler {
                 message: messagePreview,
                 sessionKey: resolvedSessionKey,
                 thinking: link.thinking?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty,
-                deliver: provider.shouldDeliver(link.deliver),
+                deliver: channel.shouldDeliver(link.deliver),
                 to: link.to?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty,
-                provider: provider,
+                channel: channel,
                 timeoutSeconds: link.timeoutSeconds,
                 idempotencyKey: UUID().uuidString)
 

apps/macos/Sources/Clawdbot/GatewayAgentChannel.swift

@@ -1,26 +0,0 @@
-import Foundation
-
-enum GatewayAgentChannel: String, CaseIterable, Sendable {
-    case last
-    case webchat
-    case whatsapp
-    case telegram
-
-    init(raw: String?) {
-        let trimmed = raw?
-            .trimmingCharacters(in: .whitespacesAndNewlines)
-            .lowercased() ?? ""
-        self = GatewayAgentChannel(rawValue: trimmed) ?? .last
-    }
-
-    func shouldDeliver(_ isLast: Bool) -> Bool {
-        switch self {
-        case .webchat:
-            false
-        case .last:
-            isLast
-        case .whatsapp, .telegram:
-            true
-        }
-    }
-}

apps/macos/Sources/Clawdbot/GatewayConnection.swift

@@ -5,7 +5,7 @@ import OSLog
 
 private let gatewayConnectionLogger = Logger(subsystem: "com.clawdbot", category: "gateway.connection")
 
-enum GatewayAgentProvider: String, Codable, CaseIterable, Sendable {
+enum GatewayAgentChannel: String, Codable, CaseIterable, Sendable {
     case last
     case whatsapp
     case telegram
@@ -18,7 +18,7 @@ enum GatewayAgentProvider: String, Codable, CaseIterable, Sendable {
 
     init(raw: String?) {
         let normalized = (raw ?? "").trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
-        self = GatewayAgentProvider(rawValue: normalized) ?? .last
+        self = GatewayAgentChannel(rawValue: normalized) ?? .last
     }
 
     var isDeliverable: Bool { self != .webchat }
@@ -32,7 +32,7 @@ struct GatewayAgentInvocation: Sendable {
     var thinking: String?
     var deliver: Bool = false
     var to: String?
-    var provider: GatewayAgentProvider = .last
+    var channel: GatewayAgentChannel = .last
     var timeoutSeconds: Int?
     var idempotencyKey: String = UUID().uuidString
 }
@@ -52,9 +52,10 @@ actor GatewayConnection {
         case setHeartbeats = "set-heartbeats"
         case systemEvent = "system-event"
         case health
-        case providersStatus = "providers.status"
+        case channelsStatus = "channels.status"
         case configGet = "config.get"
         case configSet = "config.set"
+        case configPatch = "config.patch"
         case wizardStart = "wizard.start"
         case wizardNext = "wizard.next"
         case wizardCancel = "wizard.cancel"
@@ -62,7 +63,7 @@ actor GatewayConnection {
         case talkMode = "talk.mode"
         case webLoginStart = "web.login.start"
         case webLoginWait = "web.login.wait"
-        case providersLogout = "providers.logout"
+        case channelsLogout = "channels.logout"
         case modelsList = "models.list"
         case chatHistory = "chat.history"
         case chatSend = "chat.send"
@@ -368,7 +369,7 @@ extension GatewayConnection {
             "thinking": AnyCodable(invocation.thinking ?? "default"),
             "deliver": AnyCodable(invocation.deliver),
             "to": AnyCodable(invocation.to ?? ""),
-            "provider": AnyCodable(invocation.provider.rawValue),
+            "channel": AnyCodable(invocation.channel.rawValue),
             "idempotencyKey": AnyCodable(invocation.idempotencyKey),
         ]
         if let timeout = invocation.timeoutSeconds {
@@ -389,7 +390,7 @@ extension GatewayConnection {
         sessionKey: String,
         deliver: Bool,
         to: String?,
-        provider: GatewayAgentProvider = .last,
+        channel: GatewayAgentChannel = .last,
         timeoutSeconds: Int? = nil,
         idempotencyKey: String = UUID().uuidString) async -> (ok: Bool, error: String?)
     {
@@ -399,7 +400,7 @@ extension GatewayConnection {
             thinking: thinking,
             deliver: deliver,
             to: to,
-            provider: provider,
+            channel: channel,
             timeoutSeconds: timeoutSeconds,
             idempotencyKey: idempotencyKey))
     }

apps/macos/Sources/Clawdbot/GatewayEndpointStore.swift

@@ -388,6 +388,43 @@ actor GatewayEndpointStore {
     }
 }
 
+extension GatewayEndpointStore {
+    static func dashboardURL(for config: GatewayConnection.Config) throws -> URL {
+        guard var components = URLComponents(url: config.url, resolvingAgainstBaseURL: false) else {
+            throw NSError(domain: "Dashboard", code: 1, userInfo: [
+                NSLocalizedDescriptionKey: "Invalid gateway URL",
+            ])
+        }
+        switch components.scheme?.lowercased() {
+        case "ws":
+            components.scheme = "http"
+        case "wss":
+            components.scheme = "https"
+        default:
+            components.scheme = "http"
+        }
+        components.path = "/"
+        var queryItems: [URLQueryItem] = []
+        if let token = config.token?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !token.isEmpty
+        {
+            queryItems.append(URLQueryItem(name: "token", value: token))
+        }
+        if let password = config.password?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !password.isEmpty
+        {
+            queryItems.append(URLQueryItem(name: "password", value: password))
+        }
+        components.queryItems = queryItems.isEmpty ? nil : queryItems
+        guard let url = components.url else {
+            throw NSError(domain: "Dashboard", code: 2, userInfo: [
+                NSLocalizedDescriptionKey: "Failed to build dashboard URL",
+            ])
+        }
+        return url
+    }
+}
+
 #if DEBUG
 extension GatewayEndpointStore {
     static func _testResolveGatewayPassword(

apps/macos/Sources/Clawdbot/GatewayProcessManager.swift

@@ -211,19 +211,19 @@ final class GatewayProcessManager {
     private func describe(details instance: String?, port: Int, snap: HealthSnapshot?) -> String {
         let instanceText = instance ?? "pid unknown"
         if let snap {
-            let linkId = snap.providerOrder?.first(where: {
-                if let summary = snap.providers[$0] { return summary.linked != nil }
+            let linkId = snap.channelOrder?.first(where: {
+                if let summary = snap.channels[$0] { return summary.linked != nil }
                 return false
-            }) ?? snap.providers.keys.first(where: {
-                if let summary = snap.providers[$0] { return summary.linked != nil }
+            }) ?? snap.channels.keys.first(where: {
+                if let summary = snap.channels[$0] { return summary.linked != nil }
                 return false
             })
-            let linked = linkId.flatMap { snap.providers[$0]?.linked } ?? false
-            let authAge = linkId.flatMap { snap.providers[$0]?.authAgeMs }.flatMap(msToAge) ?? "unknown age"
+            let linked = linkId.flatMap { snap.channels[$0]?.linked } ?? false
+            let authAge = linkId.flatMap { snap.channels[$0]?.authAgeMs }.flatMap(msToAge) ?? "unknown age"
             let label =
-                linkId.flatMap { snap.providerLabels?[$0] } ??
+                linkId.flatMap { snap.channelLabels?[$0] } ??
                 linkId?.capitalized ??
-                "provider"
+                "channel"
             let linkText = linked ? "linked" : "not linked"
             return "port \(port), \(label) \(linkText), auth \(authAge), \(instanceText)"
         }

apps/macos/Sources/Clawdbot/GeneralSettings.swift

@@ -496,18 +496,18 @@ struct GeneralSettings: View {
             }
 
             if let snap = snapshot {
-                let linkId = snap.providerOrder?.first(where: {
-                    if let summary = snap.providers[$0] { return summary.linked != nil }
+                let linkId = snap.channelOrder?.first(where: {
+                    if let summary = snap.channels[$0] { return summary.linked != nil }
                     return false
-                }) ?? snap.providers.keys.first(where: {
-                    if let summary = snap.providers[$0] { return summary.linked != nil }
+                }) ?? snap.channels.keys.first(where: {
+                    if let summary = snap.channels[$0] { return summary.linked != nil }
                     return false
                 })
                 let linkLabel =
-                    linkId.flatMap { snap.providerLabels?[$0] } ??
+                    linkId.flatMap { snap.channelLabels?[$0] } ??
                     linkId?.capitalized ??
-                    "Link provider"
-                let linkAge = linkId.flatMap { snap.providers[$0]?.authAgeMs }
+                    "Link channel"
+                let linkAge = linkId.flatMap { snap.channels[$0]?.authAgeMs }
                 Text("\(linkLabel) auth age: \(healthAgeString(linkAge))")
                     .font(.caption)
                     .foregroundStyle(.secondary)

apps/macos/Sources/Clawdbot/HealthStore.swift

@@ -4,7 +4,7 @@ import Observation
 import SwiftUI
 
 struct HealthSnapshot: Codable, Sendable {
-    struct ProviderSummary: Codable, Sendable {
+    struct ChannelSummary: Codable, Sendable {
         struct Probe: Codable, Sendable {
             struct Bot: Codable, Sendable {
                 let username: String?
@@ -44,9 +44,9 @@ struct HealthSnapshot: Codable, Sendable {
     let ok: Bool?
     let ts: Double
     let durationMs: Double
-    let providers: [String: ProviderSummary]
-    let providerOrder: [String]?
-    let providerLabels: [String: String]?
+    let channels: [String: ChannelSummary]
+    let channelOrder: [String]?
+    let channelLabels: [String: String]?
     let heartbeatSeconds: Int?
     let sessions: Sessions
 }
@@ -144,13 +144,13 @@ final class HealthStore {
         }
     }
 
-    private static func isProviderHealthy(_ summary: HealthSnapshot.ProviderSummary) -> Bool {
+    private static func isChannelHealthy(_ summary: HealthSnapshot.ChannelSummary) -> Bool {
         guard summary.configured == true else { return false }
         // If probe is missing, treat it as "configured but unknown health" (not a hard fail).
         return summary.probe?.ok ?? true
     }
 
-    private static func describeProbeFailure(_ probe: HealthSnapshot.ProviderSummary.Probe) -> String {
+    private static func describeProbeFailure(_ probe: HealthSnapshot.ChannelSummary.Probe) -> String {
         let elapsed = probe.elapsedMs.map { "\(Int($0))ms" }
         if let error = probe.error, error.lowercased().contains("timeout") || probe.status == nil {
             if let elapsed { return "Health check timed out (\(elapsed))" }
@@ -162,28 +162,28 @@ final class HealthStore {
         return "\(reason) (\(code))"
     }
 
-    private func resolveLinkProvider(
-        _ snap: HealthSnapshot) -> (id: String, summary: HealthSnapshot.ProviderSummary)?
+    private func resolveLinkChannel(
+        _ snap: HealthSnapshot) -> (id: String, summary: HealthSnapshot.ChannelSummary)?
     {
-        let order = snap.providerOrder ?? Array(snap.providers.keys)
+        let order = snap.channelOrder ?? Array(snap.channels.keys)
         for id in order {
-            if let summary = snap.providers[id], summary.linked != nil {
+            if let summary = snap.channels[id], summary.linked != nil {
                 return (id: id, summary: summary)
             }
         }
         return nil
     }
 
-    private func resolveFallbackProvider(
+    private func resolveFallbackChannel(
         _ snap: HealthSnapshot,
-        excluding id: String?) -> (id: String, summary: HealthSnapshot.ProviderSummary)?
+        excluding id: String?) -> (id: String, summary: HealthSnapshot.ChannelSummary)?
     {
-        let order = snap.providerOrder ?? Array(snap.providers.keys)
-        for providerId in order {
-            if providerId == id { continue }
-            guard let summary = snap.providers[providerId] else { continue }
-            if Self.isProviderHealthy(summary) {
-                return (id: providerId, summary: summary)
+        let order = snap.channelOrder ?? Array(snap.channels.keys)
+        for channelId in order {
+            if channelId == id { continue }
+            guard let summary = snap.channels[channelId] else { continue }
+            if Self.isChannelHealthy(summary) {
+                return (id: channelId, summary: summary)
             }
         }
         return nil
@@ -194,13 +194,13 @@ final class HealthStore {
             return .degraded(error)
         }
         guard let snap = self.snapshot else { return .unknown }
-        guard let link = self.resolveLinkProvider(snap) else { return .unknown }
+        guard let link = self.resolveLinkChannel(snap) else { return .unknown }
         if link.summary.linked != true {
-            // Linking is optional if any other provider is healthy; don't paint the whole app red.
-            let fallback = self.resolveFallbackProvider(snap, excluding: link.id)
+            // Linking is optional if any other channel is healthy; don't paint the whole app red.
+            let fallback = self.resolveFallbackChannel(snap, excluding: link.id)
             return fallback != nil ? .degraded("Not linked") : .linkingNeeded
         }
-        // A provider can be "linked" but still unhealthy (failed probe / cannot connect).
+        // A channel can be "linked" but still unhealthy (failed probe / cannot connect).
         if let probe = link.summary.probe, probe.ok == false {
             return .degraded(Self.describeProbeFailure(probe))
         }
@@ -211,10 +211,10 @@ final class HealthStore {
         if self.isRefreshing { return "Health check running…" }
         if let error = self.lastError { return "Health check failed: \(error)" }
         guard let snap = self.snapshot else { return "Health check pending" }
-        guard let link = self.resolveLinkProvider(snap) else { return "Health check pending" }
+        guard let link = self.resolveLinkChannel(snap) else { return "Health check pending" }
         if link.summary.linked != true {
-            if let fallback = self.resolveFallbackProvider(snap, excluding: link.id) {
-                let fallbackLabel = snap.providerLabels?[fallback.id] ?? fallback.id.capitalized
+            if let fallback = self.resolveFallbackChannel(snap, excluding: link.id) {
+                let fallbackLabel = snap.channelLabels?[fallback.id] ?? fallback.id.capitalized
                 let fallbackState = (fallback.summary.probe?.ok ?? true) ? "ok" : "degraded"
                 return "\(fallbackLabel) \(fallbackState) · Not linked — run clawdbot login"
             }
@@ -247,10 +247,10 @@ final class HealthStore {
     }
 
     func describeFailure(from snap: HealthSnapshot, fallback: String?) -> String {
-        if let link = self.resolveLinkProvider(snap), link.summary.linked != true {
+        if let link = self.resolveLinkChannel(snap), link.summary.linked != true {
             return "Not linked — run clawdbot login"
         }
-        if let link = self.resolveLinkProvider(snap), let probe = link.summary.probe, probe.ok == false {
+        if let link = self.resolveLinkChannel(snap), let probe = link.summary.probe, probe.ok == false {
             return Self.describeProbeFailure(probe)
         }
         if let fallback, !fallback.isEmpty {

apps/macos/Sources/Clawdbot/InstancesStore.swift

@@ -242,18 +242,18 @@ final class InstancesStore {
         do {
             let data = try await ControlChannel.shared.health(timeout: 8)
             guard let snap = decodeHealthSnapshot(from: data) else { return }
-            let linkId = snap.providerOrder?.first(where: {
-                if let summary = snap.providers[$0] { return summary.linked != nil }
+            let linkId = snap.channelOrder?.first(where: {
+                if let summary = snap.channels[$0] { return summary.linked != nil }
                 return false
-            }) ?? snap.providers.keys.first(where: {
-                if let summary = snap.providers[$0] { return summary.linked != nil }
+            }) ?? snap.channels.keys.first(where: {
+                if let summary = snap.channels[$0] { return summary.linked != nil }
                 return false
             })
-            let linked = linkId.flatMap { snap.providers[$0]?.linked } ?? false
+            let linked = linkId.flatMap { snap.channels[$0]?.linked } ?? false
             let linkLabel =
-                linkId.flatMap { snap.providerLabels?[$0] } ??
+                linkId.flatMap { snap.channelLabels?[$0] } ??
                 linkId?.capitalized ??
-                "provider"
+                "channel"
             let entry = InstanceInfo(
                 id: "health-\(snap.ts)",
                 host: "gateway (health)",

apps/macos/Sources/Clawdbot/LogLocator.swift

@@ -1,9 +1,25 @@
 import Foundation
 
 enum LogLocator {
-    private static let logDir = URL(fileURLWithPath: "/tmp/clawdbot")
-    private static let stdoutLog = logDir.appendingPathComponent("clawdbot-stdout.log")
-    private static let gatewayLog = logDir.appendingPathComponent("clawdbot-gateway.log")
+    private static var logDir: URL {
+        if let override = ProcessInfo.processInfo.environment["CLAWDBOT_LOG_DIR"], !override.isEmpty {
+            return URL(fileURLWithPath: override)
+        }
+
+        return URL(fileURLWithPath: "/tmp/clawdbot")
+    }
+
+    private static var stdoutLog: URL {
+        logDir.appendingPathComponent("clawdbot-stdout.log")
+    }
+
+    private static var gatewayLog: URL {
+        logDir.appendingPathComponent("clawdbot-gateway.log")
+    }
+
+    private static func ensureLogDirExists() {
+        try? FileManager.default.createDirectory(at: self.logDir, withIntermediateDirectories: true)
+    }
 
     private static func modificationDate(for url: URL) -> Date {
         (try? url.resourceValues(forKeys: [.contentModificationDateKey]).contentModificationDate) ?? .distantPast
@@ -11,6 +27,7 @@ enum LogLocator {
 
     /// Returns the newest log file under /tmp/clawdbot/ (rolling or stdout), or nil if none exist.
     static func bestLogFile() -> URL? {
+        self.ensureLogDirExists()
         let fm = FileManager.default
         let files = (try? fm.contentsOfDirectory(
             at: self.logDir,
@@ -26,11 +43,13 @@ enum LogLocator {
 
     /// Path to use for launchd stdout/err.
     static var launchdLogPath: String {
-        stdoutLog.path
+        self.ensureLogDirExists()
+        return stdoutLog.path
     }
 
     /// Path to use for the Gateway launchd job stdout/err.
     static var launchdGatewayLogPath: String {
-        gatewayLog.path
+        self.ensureLogDirExists()
+        return gatewayLog.path
     }
 }

apps/macos/Sources/Clawdbot/MenuContentView.swift

@@ -313,27 +313,7 @@ struct MenuContent: View {
     private func openDashboard() async {
         do {
             let config = try await GatewayEndpointStore.shared.requireConfig()
-            let wsURL = config.url
-            guard var components = URLComponents(url: wsURL, resolvingAgainstBaseURL: false) else {
-                throw NSError(domain: "Dashboard", code: 1, userInfo: [
-                    NSLocalizedDescriptionKey: "Invalid gateway URL",
-                ])
-            }
-            switch components.scheme?.lowercased() {
-            case "ws":
-                components.scheme = "http"
-            case "wss":
-                components.scheme = "https"
-            default:
-                components.scheme = "http"
-            }
-            components.path = "/"
-            components.query = nil
-            guard let url = components.url else {
-                throw NSError(domain: "Dashboard", code: 2, userInfo: [
-                    NSLocalizedDescriptionKey: "Failed to build dashboard URL",
-                ])
-            }
+            let url = try GatewayEndpointStore.dashboardURL(for: config)
             NSWorkspace.shared.open(url)
         } catch {
             let alert = NSAlert()

apps/macos/Sources/Clawdbot/OnboardingView+Pages.swift

@@ -694,7 +694,7 @@ extension OnboardingView {
                     systemImage: "bubble.left.and.bubble.right")
                 self.featureActionRow(
                     title: "Connect WhatsApp or Telegram",
-                    subtitle: "Open Settings → Connections to link providers and monitor status.",
+                    subtitle: "Open Settings → Connections to link channels and monitor status.",
                     systemImage: "link")
                 {
                     self.openSettings(tab: .connections)

apps/macos/Sources/Clawdbot/VoiceWakeForwarder.swift

@@ -37,7 +37,7 @@ enum VoiceWakeForwarder {
         var thinking: String = "low"
         var deliver: Bool = true
         var to: String?
-        var provider: GatewayAgentProvider = .last
+        var channel: GatewayAgentChannel = .last
     }
 
     @discardableResult
@@ -46,14 +46,14 @@ enum VoiceWakeForwarder {
         options: ForwardOptions = ForwardOptions()) async -> Result<Void, VoiceWakeForwardError>
     {
         let payload = Self.prefixedTranscript(transcript)
-        let deliver = options.provider.shouldDeliver(options.deliver)
+        let deliver = options.channel.shouldDeliver(options.deliver)
         let result = await GatewayConnection.shared.sendAgent(GatewayAgentInvocation(
             message: payload,
             sessionKey: options.sessionKey,
             thinking: options.thinking,
             deliver: deliver,
             to: options.to,
-            provider: options.provider))
+            channel: options.channel))
 
         if result.ok {
             self.logger.info("voice wake forward ok")

apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift

@@ -341,7 +341,7 @@ public struct SendParams: Codable, Sendable {
     public let message: String
     public let mediaurl: String?
     public let gifplayback: Bool?
-    public let provider: String?
+    public let channel: String?
     public let accountid: String?
     public let idempotencykey: String
 
@@ -350,7 +350,7 @@ public struct SendParams: Codable, Sendable {
         message: String,
         mediaurl: String?,
         gifplayback: Bool?,
-        provider: String?,
+        channel: String?,
         accountid: String?,
         idempotencykey: String
     ) {
@@ -358,7 +358,7 @@ public struct SendParams: Codable, Sendable {
         self.message = message
         self.mediaurl = mediaurl
         self.gifplayback = gifplayback
-        self.provider = provider
+        self.channel = channel
         self.accountid = accountid
         self.idempotencykey = idempotencykey
     }
@@ -367,7 +367,7 @@ public struct SendParams: Codable, Sendable {
         case message
         case mediaurl = "mediaUrl"
         case gifplayback = "gifPlayback"
-        case provider
+        case channel
         case accountid = "accountId"
         case idempotencykey = "idempotencyKey"
     }
@@ -379,7 +379,7 @@ public struct PollParams: Codable, Sendable {
     public let options: [String]
     public let maxselections: Int?
     public let durationhours: Int?
-    public let provider: String?
+    public let channel: String?
     public let accountid: String?
     public let idempotencykey: String
 
@@ -389,7 +389,7 @@ public struct PollParams: Codable, Sendable {
         options: [String],
         maxselections: Int?,
         durationhours: Int?,
-        provider: String?,
+        channel: String?,
         accountid: String?,
         idempotencykey: String
     ) {
@@ -398,7 +398,7 @@ public struct PollParams: Codable, Sendable {
         self.options = options
         self.maxselections = maxselections
         self.durationhours = durationhours
-        self.provider = provider
+        self.channel = channel
         self.accountid = accountid
         self.idempotencykey = idempotencykey
     }
@@ -408,7 +408,7 @@ public struct PollParams: Codable, Sendable {
         case options
         case maxselections = "maxSelections"
         case durationhours = "durationHours"
-        case provider
+        case channel
         case accountid = "accountId"
         case idempotencykey = "idempotencyKey"
     }
@@ -422,7 +422,7 @@ public struct AgentParams: Codable, Sendable {
     public let thinking: String?
     public let deliver: Bool?
     public let attachments: [AnyCodable]?
-    public let provider: String?
+    public let channel: String?
     public let timeout: Int?
     public let lane: String?
     public let extrasystemprompt: String?
@@ -438,7 +438,7 @@ public struct AgentParams: Codable, Sendable {
         thinking: String?,
         deliver: Bool?,
         attachments: [AnyCodable]?,
-        provider: String?,
+        channel: String?,
         timeout: Int?,
         lane: String?,
         extrasystemprompt: String?,
@@ -453,7 +453,7 @@ public struct AgentParams: Codable, Sendable {
         self.thinking = thinking
         self.deliver = deliver
         self.attachments = attachments
-        self.provider = provider
+        self.channel = channel
         self.timeout = timeout
         self.lane = lane
         self.extrasystemprompt = extrasystemprompt
@@ -469,7 +469,7 @@ public struct AgentParams: Codable, Sendable {
         case thinking
         case deliver
         case attachments
-        case provider
+        case channel
         case timeout
         case lane
         case extrasystemprompt = "extraSystemPrompt"
@@ -845,42 +845,67 @@ public struct ConfigGetParams: Codable, Sendable {
 
 public struct ConfigSetParams: Codable, Sendable {
     public let raw: String
+    public let basehash: String?
 
     public init(
-        raw: String
+        raw: String,
+        basehash: String?
     ) {
         self.raw = raw
+        self.basehash = basehash
     }
     private enum CodingKeys: String, CodingKey {
         case raw
+        case basehash = "baseHash"
     }
 }
 
 public struct ConfigApplyParams: Codable, Sendable {
     public let raw: String
+    public let basehash: String?
     public let sessionkey: String?
     public let note: String?
     public let restartdelayms: Int?
 
     public init(
         raw: String,
+        basehash: String?,
         sessionkey: String?,
         note: String?,
         restartdelayms: Int?
     ) {
         self.raw = raw
+        self.basehash = basehash
         self.sessionkey = sessionkey
         self.note = note
         self.restartdelayms = restartdelayms
     }
     private enum CodingKeys: String, CodingKey {
         case raw
+        case basehash = "baseHash"
         case sessionkey = "sessionKey"
         case note
         case restartdelayms = "restartDelayMs"
     }
 }
 
+public struct ConfigPatchParams: Codable, Sendable {
+    public let raw: String
+    public let basehash: String?
+
+    public init(
+        raw: String,
+        basehash: String?
+    ) {
+        self.raw = raw
+        self.basehash = basehash
+    }
+    private enum CodingKeys: String, CodingKey {
+        case raw
+        case basehash = "baseHash"
+    }
+}
+
 public struct ConfigSchemaParams: Codable, Sendable {
 }
 
@@ -1102,7 +1127,7 @@ public struct TalkModeParams: Codable, Sendable {
     }
 }
 
-public struct ProvidersStatusParams: Codable, Sendable {
+public struct ChannelsStatusParams: Codable, Sendable {
     public let probe: Bool?
     public let timeoutms: Int?
 
@@ -1119,52 +1144,52 @@ public struct ProvidersStatusParams: Codable, Sendable {
     }
 }
 
-public struct ProvidersStatusResult: Codable, Sendable {
+public struct ChannelsStatusResult: Codable, Sendable {
     public let ts: Int
-    public let providerorder: [String]
-    public let providerlabels: [String: AnyCodable]
-    public let providers: [String: AnyCodable]
-    public let provideraccounts: [String: AnyCodable]
-    public let providerdefaultaccountid: [String: AnyCodable]
+    public let channelorder: [String]
+    public let channellabels: [String: AnyCodable]
+    public let channels: [String: AnyCodable]
+    public let channelaccounts: [String: AnyCodable]
+    public let channeldefaultaccountid: [String: AnyCodable]
 
     public init(
         ts: Int,
-        providerorder: [String],
-        providerlabels: [String: AnyCodable],
-        providers: [String: AnyCodable],
-        provideraccounts: [String: AnyCodable],
-        providerdefaultaccountid: [String: AnyCodable]
+        channelorder: [String],
+        channellabels: [String: AnyCodable],
+        channels: [String: AnyCodable],
+        channelaccounts: [String: AnyCodable],
+        channeldefaultaccountid: [String: AnyCodable]
     ) {
         self.ts = ts
-        self.providerorder = providerorder
-        self.providerlabels = providerlabels
-        self.providers = providers
-        self.provideraccounts = provideraccounts
-        self.providerdefaultaccountid = providerdefaultaccountid
+        self.channelorder = channelorder
+        self.channellabels = channellabels
+        self.channels = channels
+        self.channelaccounts = channelaccounts
+        self.channeldefaultaccountid = channeldefaultaccountid
     }
     private enum CodingKeys: String, CodingKey {
         case ts
-        case providerorder = "providerOrder"
-        case providerlabels = "providerLabels"
-        case providers
-        case provideraccounts = "providerAccounts"
-        case providerdefaultaccountid = "providerDefaultAccountId"
+        case channelorder = "channelOrder"
+        case channellabels = "channelLabels"
+        case channels
+        case channelaccounts = "channelAccounts"
+        case channeldefaultaccountid = "channelDefaultAccountId"
     }
 }
 
-public struct ProvidersLogoutParams: Codable, Sendable {
-    public let provider: String
+public struct ChannelsLogoutParams: Codable, Sendable {
+    public let channel: String
     public let accountid: String?
 
     public init(
-        provider: String,
+        channel: String,
         accountid: String?
     ) {
-        self.provider = provider
+        self.channel = channel
         self.accountid = accountid
     }
     private enum CodingKeys: String, CodingKey {
-        case provider
+        case channel
         case accountid = "accountId"
     }
 }

apps/macos/Tests/ClawdbotIPCTests/ConnectionsSettingsSmokeTests.swift

@@ -7,16 +7,16 @@ import Testing
 struct ConnectionsSettingsSmokeTests {
     @Test func connectionsSettingsBuildsBodyWithSnapshot() {
         let store = ConnectionsStore(isPreview: true)
-        store.snapshot = ProvidersStatusSnapshot(
+        store.snapshot = ChannelsStatusSnapshot(
             ts: 1_700_000_000_000,
-            providerOrder: ["whatsapp", "telegram", "signal", "imessage"],
-            providerLabels: [
+            channelOrder: ["whatsapp", "telegram", "signal", "imessage"],
+            channelLabels: [
                 "whatsapp": "WhatsApp",
                 "telegram": "Telegram",
                 "signal": "Signal",
                 "imessage": "iMessage",
             ],
-            providers: [
+            channels: [
                 "whatsapp": AnyCodable([
                     "configured": true,
                     "linked": true,
@@ -72,8 +72,8 @@ struct ConnectionsSettingsSmokeTests {
                     "lastProbeAt": 1_700_000_050_000,
                 ]),
             ],
-            providerAccounts: [:],
-            providerDefaultAccountId: [
+            channelAccounts: [:],
+            channelDefaultAccountId: [
                 "whatsapp": "default",
                 "telegram": "default",
                 "signal": "default",
@@ -97,16 +97,16 @@ struct ConnectionsSettingsSmokeTests {
 
     @Test func connectionsSettingsBuildsBodyWithoutSnapshot() {
         let store = ConnectionsStore(isPreview: true)
-        store.snapshot = ProvidersStatusSnapshot(
+        store.snapshot = ChannelsStatusSnapshot(
             ts: 1_700_000_000_000,
-            providerOrder: ["whatsapp", "telegram", "signal", "imessage"],
-            providerLabels: [
+            channelOrder: ["whatsapp", "telegram", "signal", "imessage"],
+            channelLabels: [
                 "whatsapp": "WhatsApp",
                 "telegram": "Telegram",
                 "signal": "Signal",
                 "imessage": "iMessage",
             ],
-            providers: [
+            channels: [
                 "whatsapp": AnyCodable([
                     "configured": false,
                     "linked": false,
@@ -148,8 +148,8 @@ struct ConnectionsSettingsSmokeTests {
                     "lastProbeAt": 1_700_000_200_000,
                 ]),
             ],
-            providerAccounts: [:],
-            providerDefaultAccountId: [
+            channelAccounts: [:],
+            channelDefaultAccountId: [
                 "whatsapp": "default",
                 "telegram": "default",
                 "signal": "default",

apps/macos/Tests/ClawdbotIPCTests/HealthDecodeTests.swift

@@ -5,14 +5,14 @@ import Testing
 @Suite struct HealthDecodeTests {
     private let sampleJSON: String = // minimal but complete payload
         """
-        {"ts":1733622000,"durationMs":420,"providers":{"whatsapp":{"linked":true,"authAgeMs":120000},"telegram":{"configured":true,"probe":{"ok":true,"elapsedMs":800}}},"providerOrder":["whatsapp","telegram"],"heartbeatSeconds":60,"sessions":{"path":"/tmp/sessions.json","count":1,"recent":[{"key":"abc","updatedAt":1733621900,"age":120000}]}}
+        {"ts":1733622000,"durationMs":420,"channels":{"whatsapp":{"linked":true,"authAgeMs":120000},"telegram":{"configured":true,"probe":{"ok":true,"elapsedMs":800}}},"channelOrder":["whatsapp","telegram"],"heartbeatSeconds":60,"sessions":{"path":"/tmp/sessions.json","count":1,"recent":[{"key":"abc","updatedAt":1733621900,"age":120000}]}}
         """
 
     @Test func decodesCleanJSON() async throws {
         let data = Data(sampleJSON.utf8)
         let snap = decodeHealthSnapshot(from: data)
 
-        #expect(snap?.providers["whatsapp"]?.linked == true)
+        #expect(snap?.channels["whatsapp"]?.linked == true)
         #expect(snap?.sessions.count == 1)
     }
 
@@ -20,7 +20,7 @@ import Testing
         let noisy = "debug: something logged\n" + self.sampleJSON + "\ntrailer"
         let snap = decodeHealthSnapshot(from: Data(noisy.utf8))
 
-        #expect(snap?.providers["telegram"]?.probe?.elapsedMs == 800)
+        #expect(snap?.channels["telegram"]?.probe?.elapsedMs == 800)
     }
 
     @Test func failsWithoutBraces() async throws {

apps/macos/Tests/ClawdbotIPCTests/HealthStoreStateTests.swift

@@ -3,12 +3,12 @@ import Testing
 @testable import Clawdbot
 
 @Suite struct HealthStoreStateTests {
-    @Test @MainActor func linkedProviderProbeFailureDegradesState() async throws {
+    @Test @MainActor func linkedChannelProbeFailureDegradesState() async throws {
         let snap = HealthSnapshot(
             ok: true,
             ts: 0,
             durationMs: 1,
-            providers: [
+            channels: [
                 "whatsapp": .init(
                     configured: true,
                     linked: true,
@@ -22,8 +22,8 @@ import Testing
                         webhook: nil),
                     lastProbeAt: 0),
             ],
-            providerOrder: ["whatsapp"],
-            providerLabels: ["whatsapp": "WhatsApp"],
+            channelOrder: ["whatsapp"],
+            channelLabels: ["whatsapp": "WhatsApp"],
             heartbeatSeconds: 60,
             sessions: .init(path: "/tmp/sessions.json", count: 0, recent: []))
 
@@ -34,7 +34,7 @@ import Testing
         case let .degraded(message):
             #expect(!message.isEmpty)
         default:
-            Issue.record("Expected degraded state when probe fails for linked provider")
+            Issue.record("Expected degraded state when probe fails for linked channel")
         }
 
         #expect(store.summaryLine.contains("probe degraded"))

apps/macos/Tests/ClawdbotIPCTests/LogLocatorTests.swift

@@ -0,0 +1,24 @@
+import Darwin
+import Foundation
+import Testing
+@testable import Clawdbot
+
+@Suite struct LogLocatorTests {
+    @Test func launchdGatewayLogPathEnsuresTmpDirExists() throws {
+        let fm = FileManager.default
+        let baseDir = URL(fileURLWithPath: NSTemporaryDirectory(), isDirectory: true)
+        let logDir = baseDir.appendingPathComponent("clawdbot-tests-\(UUID().uuidString)")
+
+        setenv("CLAWDBOT_LOG_DIR", logDir.path, 1)
+        defer {
+            unsetenv("CLAWDBOT_LOG_DIR")
+            try? fm.removeItem(at: logDir)
+        }
+
+        _ = LogLocator.launchdGatewayLogPath
+
+        var isDir: ObjCBool = false
+        #expect(fm.fileExists(atPath: logDir.path, isDirectory: &isDir))
+        #expect(isDir.boolValue == true)
+    }
+}

assets/chrome-extension/README.md

@@ -0,0 +1,22 @@
+# Clawdbot Chrome Extension (Browser Relay)
+
+Purpose: attach Clawdbot to an existing Chrome tab so the Gateway can automate it (via the local CDP relay server).
+
+## Dev / load unpacked
+
+1. Build/run Clawdbot Gateway with browser control enabled.
+2. Ensure the relay server is reachable at `http://127.0.0.1:18792/` (default).
+3. Install the extension to a stable path:
+
+   ```bash
+   clawdbot browser extension install
+   clawdbot browser extension path
+   ```
+
+4. Chrome → `chrome://extensions` → enable “Developer mode”.
+5. “Load unpacked” → select the path printed above.
+6. Pin the extension. Click the icon on a tab to attach/detach.
+
+## Options
+
+- `Relay port`: defaults to `18792`.

assets/chrome-extension/background.js

@@ -0,0 +1,438 @@
+const DEFAULT_PORT = 18792
+
+const BADGE = {
+  on: { text: 'ON', color: '#FF5A36' },
+  off: { text: '', color: '#000000' },
+  connecting: { text: '…', color: '#F59E0B' },
+  error: { text: '!', color: '#B91C1C' },
+}
+
+/** @type {WebSocket|null} */
+let relayWs = null
+/** @type {Promise<void>|null} */
+let relayConnectPromise = null
+
+let debuggerListenersInstalled = false
+
+let nextSession = 1
+
+/** @type {Map<number, {state:'connecting'|'connected', sessionId?:string, targetId?:string, attachOrder?:number}>} */
+const tabs = new Map()
+/** @type {Map<string, number>} */
+const tabBySession = new Map()
+/** @type {Map<string, number>} */
+const childSessionToTab = new Map()
+
+/** @type {Map<number, {resolve:(v:any)=>void, reject:(e:Error)=>void}>} */
+const pending = new Map()
+
+function nowStack() {
+  try {
+    return new Error().stack || ''
+  } catch {
+    return ''
+  }
+}
+
+async function getRelayPort() {
+  const stored = await chrome.storage.local.get(['relayPort'])
+  const raw = stored.relayPort
+  const n = Number.parseInt(String(raw || ''), 10)
+  if (!Number.isFinite(n) || n <= 0 || n > 65535) return DEFAULT_PORT
+  return n
+}
+
+function setBadge(tabId, kind) {
+  const cfg = BADGE[kind]
+  void chrome.action.setBadgeText({ tabId, text: cfg.text })
+  void chrome.action.setBadgeBackgroundColor({ tabId, color: cfg.color })
+  void chrome.action.setBadgeTextColor({ tabId, color: '#FFFFFF' }).catch(() => {})
+}
+
+async function ensureRelayConnection() {
+  if (relayWs && relayWs.readyState === WebSocket.OPEN) return
+  if (relayConnectPromise) return await relayConnectPromise
+
+  relayConnectPromise = (async () => {
+    const port = await getRelayPort()
+    const httpBase = `http://127.0.0.1:${port}`
+    const wsUrl = `ws://127.0.0.1:${port}/extension`
+
+    // Fast preflight: is the relay server up?
+    try {
+      await fetch(`${httpBase}/`, { method: 'HEAD', signal: AbortSignal.timeout(2000) })
+    } catch (err) {
+      throw new Error(`Relay server not reachable at ${httpBase} (${String(err)})`)
+    }
+
+    const ws = new WebSocket(wsUrl)
+    relayWs = ws
+
+    await new Promise((resolve, reject) => {
+      const t = setTimeout(() => reject(new Error('WebSocket connect timeout')), 5000)
+      ws.onopen = () => {
+        clearTimeout(t)
+        resolve()
+      }
+      ws.onerror = () => {
+        clearTimeout(t)
+        reject(new Error('WebSocket connect failed'))
+      }
+      ws.onclose = (ev) => {
+        clearTimeout(t)
+        reject(new Error(`WebSocket closed (${ev.code} ${ev.reason || 'no reason'})`))
+      }
+    })
+
+    ws.onmessage = (event) => void onRelayMessage(String(event.data || ''))
+    ws.onclose = () => onRelayClosed('closed')
+    ws.onerror = () => onRelayClosed('error')
+
+    if (!debuggerListenersInstalled) {
+      debuggerListenersInstalled = true
+      chrome.debugger.onEvent.addListener(onDebuggerEvent)
+      chrome.debugger.onDetach.addListener(onDebuggerDetach)
+    }
+  })()
+
+  try {
+    await relayConnectPromise
+  } finally {
+    relayConnectPromise = null
+  }
+}
+
+function onRelayClosed(reason) {
+  relayWs = null
+  for (const [id, p] of pending.entries()) {
+    pending.delete(id)
+    p.reject(new Error(`Relay disconnected (${reason})`))
+  }
+
+  for (const tabId of tabs.keys()) {
+    void chrome.debugger.detach({ tabId }).catch(() => {})
+    setBadge(tabId, 'connecting')
+    void chrome.action.setTitle({
+      tabId,
+      title: 'Clawdbot Browser Relay: disconnected (click to re-attach)',
+    })
+  }
+  tabs.clear()
+  tabBySession.clear()
+  childSessionToTab.clear()
+}
+
+function sendToRelay(payload) {
+  const ws = relayWs
+  if (!ws || ws.readyState !== WebSocket.OPEN) {
+    throw new Error('Relay not connected')
+  }
+  ws.send(JSON.stringify(payload))
+}
+
+async function maybeOpenHelpOnce() {
+  try {
+    const stored = await chrome.storage.local.get(['helpOnErrorShown'])
+    if (stored.helpOnErrorShown === true) return
+    await chrome.storage.local.set({ helpOnErrorShown: true })
+    await chrome.runtime.openOptionsPage()
+  } catch {
+    // ignore
+  }
+}
+
+function requestFromRelay(command) {
+  const id = command.id
+  return new Promise((resolve, reject) => {
+    pending.set(id, { resolve, reject })
+    try {
+      sendToRelay(command)
+    } catch (err) {
+      pending.delete(id)
+      reject(err instanceof Error ? err : new Error(String(err)))
+    }
+  })
+}
+
+async function onRelayMessage(text) {
+  /** @type {any} */
+  let msg
+  try {
+    msg = JSON.parse(text)
+  } catch {
+    return
+  }
+
+  if (msg && msg.method === 'ping') {
+    try {
+      sendToRelay({ method: 'pong' })
+    } catch {
+      // ignore
+    }
+    return
+  }
+
+  if (msg && typeof msg.id === 'number' && (msg.result !== undefined || msg.error !== undefined)) {
+    const p = pending.get(msg.id)
+    if (!p) return
+    pending.delete(msg.id)
+    if (msg.error) p.reject(new Error(String(msg.error)))
+    else p.resolve(msg.result)
+    return
+  }
+
+  if (msg && typeof msg.id === 'number' && msg.method === 'forwardCDPCommand') {
+    try {
+      const result = await handleForwardCdpCommand(msg)
+      sendToRelay({ id: msg.id, result })
+    } catch (err) {
+      sendToRelay({ id: msg.id, error: err instanceof Error ? err.message : String(err) })
+    }
+  }
+}
+
+function getTabBySessionId(sessionId) {
+  const direct = tabBySession.get(sessionId)
+  if (direct) return { tabId: direct, kind: 'main' }
+  const child = childSessionToTab.get(sessionId)
+  if (child) return { tabId: child, kind: 'child' }
+  return null
+}
+
+function getTabByTargetId(targetId) {
+  for (const [tabId, tab] of tabs.entries()) {
+    if (tab.targetId === targetId) return tabId
+  }
+  return null
+}
+
+async function attachTab(tabId, opts = {}) {
+  const debuggee = { tabId }
+  await chrome.debugger.attach(debuggee, '1.3')
+  await chrome.debugger.sendCommand(debuggee, 'Page.enable').catch(() => {})
+
+  const info = /** @type {any} */ (await chrome.debugger.sendCommand(debuggee, 'Target.getTargetInfo'))
+  const targetInfo = info?.targetInfo
+  const targetId = String(targetInfo?.targetId || '').trim()
+  if (!targetId) {
+    throw new Error('Target.getTargetInfo returned no targetId')
+  }
+
+  const sessionId = `cb-tab-${nextSession++}`
+  const attachOrder = nextSession
+
+  tabs.set(tabId, { state: 'connected', sessionId, targetId, attachOrder })
+  tabBySession.set(sessionId, tabId)
+  void chrome.action.setTitle({
+    tabId,
+    title: 'Clawdbot Browser Relay: attached (click to detach)',
+  })
+
+  if (!opts.skipAttachedEvent) {
+    sendToRelay({
+      method: 'forwardCDPEvent',
+      params: {
+        method: 'Target.attachedToTarget',
+        params: {
+          sessionId,
+          targetInfo: { ...targetInfo, attached: true },
+          waitingForDebugger: false,
+        },
+      },
+    })
+  }
+
+  setBadge(tabId, 'on')
+  return { sessionId, targetId }
+}
+
+async function detachTab(tabId, reason) {
+  const tab = tabs.get(tabId)
+  if (tab?.sessionId && tab?.targetId) {
+    try {
+      sendToRelay({
+        method: 'forwardCDPEvent',
+        params: {
+          method: 'Target.detachedFromTarget',
+          params: { sessionId: tab.sessionId, targetId: tab.targetId, reason },
+        },
+      })
+    } catch {
+      // ignore
+    }
+  }
+
+  if (tab?.sessionId) tabBySession.delete(tab.sessionId)
+  tabs.delete(tabId)
+
+  for (const [childSessionId, parentTabId] of childSessionToTab.entries()) {
+    if (parentTabId === tabId) childSessionToTab.delete(childSessionId)
+  }
+
+  try {
+    await chrome.debugger.detach({ tabId })
+  } catch {
+    // ignore
+  }
+
+  setBadge(tabId, 'off')
+  void chrome.action.setTitle({
+    tabId,
+    title: 'Clawdbot Browser Relay (click to attach/detach)',
+  })
+}
+
+async function connectOrToggleForActiveTab() {
+  const [active] = await chrome.tabs.query({ active: true, currentWindow: true })
+  const tabId = active?.id
+  if (!tabId) return
+
+  const existing = tabs.get(tabId)
+  if (existing?.state === 'connected') {
+    await detachTab(tabId, 'toggle')
+    return
+  }
+
+  tabs.set(tabId, { state: 'connecting' })
+  setBadge(tabId, 'connecting')
+  void chrome.action.setTitle({
+    tabId,
+    title: 'Clawdbot Browser Relay: connecting to local relay…',
+  })
+
+  try {
+    await ensureRelayConnection()
+    await attachTab(tabId)
+  } catch (err) {
+    tabs.delete(tabId)
+    setBadge(tabId, 'error')
+    void chrome.action.setTitle({
+      tabId,
+      title: 'Clawdbot Browser Relay: relay not running (open options for setup)',
+    })
+    void maybeOpenHelpOnce()
+    // Extra breadcrumbs in chrome://extensions service worker logs.
+    const message = err instanceof Error ? err.message : String(err)
+    console.warn('attach failed', message, nowStack())
+  }
+}
+
+async function handleForwardCdpCommand(msg) {
+  const method = String(msg?.params?.method || '').trim()
+  const params = msg?.params?.params || undefined
+  const sessionId = typeof msg?.params?.sessionId === 'string' ? msg.params.sessionId : undefined
+
+  // Map command to tab
+  const bySession = sessionId ? getTabBySessionId(sessionId) : null
+  const targetId = typeof params?.targetId === 'string' ? params.targetId : undefined
+  const tabId =
+    bySession?.tabId ||
+    (targetId ? getTabByTargetId(targetId) : null) ||
+    (() => {
+      // No sessionId: pick the first connected tab (stable-ish).
+      for (const [id, tab] of tabs.entries()) {
+        if (tab.state === 'connected') return id
+      }
+      return null
+    })()
+
+  if (!tabId) throw new Error(`No attached tab for method ${method}`)
+
+  /** @type {chrome.debugger.DebuggerSession} */
+  const debuggee = { tabId }
+
+  if (method === 'Runtime.enable') {
+    try {
+      await chrome.debugger.sendCommand(debuggee, 'Runtime.disable')
+      await new Promise((r) => setTimeout(r, 50))
+    } catch {
+      // ignore
+    }
+    return await chrome.debugger.sendCommand(debuggee, 'Runtime.enable', params)
+  }
+
+  if (method === 'Target.createTarget') {
+    const url = typeof params?.url === 'string' ? params.url : 'about:blank'
+    const tab = await chrome.tabs.create({ url, active: false })
+    if (!tab.id) throw new Error('Failed to create tab')
+    await new Promise((r) => setTimeout(r, 100))
+    const attached = await attachTab(tab.id)
+    return { targetId: attached.targetId }
+  }
+
+  if (method === 'Target.closeTarget') {
+    const target = typeof params?.targetId === 'string' ? params.targetId : ''
+    const toClose = target ? getTabByTargetId(target) : tabId
+    if (!toClose) return { success: false }
+    try {
+      await chrome.tabs.remove(toClose)
+    } catch {
+      return { success: false }
+    }
+    return { success: true }
+  }
+
+  if (method === 'Target.activateTarget') {
+    const target = typeof params?.targetId === 'string' ? params.targetId : ''
+    const toActivate = target ? getTabByTargetId(target) : tabId
+    if (!toActivate) return {}
+    const tab = await chrome.tabs.get(toActivate).catch(() => null)
+    if (!tab) return {}
+    if (tab.windowId) {
+      await chrome.windows.update(tab.windowId, { focused: true }).catch(() => {})
+    }
+    await chrome.tabs.update(toActivate, { active: true }).catch(() => {})
+    return {}
+  }
+
+  const tabState = tabs.get(tabId)
+  const mainSessionId = tabState?.sessionId
+  const debuggerSession =
+    sessionId && mainSessionId && sessionId !== mainSessionId
+      ? { ...debuggee, sessionId }
+      : debuggee
+
+  return await chrome.debugger.sendCommand(debuggerSession, method, params)
+}
+
+function onDebuggerEvent(source, method, params) {
+  const tabId = source.tabId
+  if (!tabId) return
+  const tab = tabs.get(tabId)
+  if (!tab?.sessionId) return
+
+  if (method === 'Target.attachedToTarget' && params?.sessionId) {
+    childSessionToTab.set(String(params.sessionId), tabId)
+  }
+
+  if (method === 'Target.detachedFromTarget' && params?.sessionId) {
+    childSessionToTab.delete(String(params.sessionId))
+  }
+
+  try {
+    sendToRelay({
+      method: 'forwardCDPEvent',
+      params: {
+        sessionId: source.sessionId || tab.sessionId,
+        method,
+        params,
+      },
+    })
+  } catch {
+    // ignore
+  }
+}
+
+function onDebuggerDetach(source, reason) {
+  const tabId = source.tabId
+  if (!tabId) return
+  if (!tabs.has(tabId)) return
+  void detachTab(tabId, reason)
+}
+
+chrome.action.onClicked.addListener(() => void connectOrToggleForActiveTab())
+
+chrome.runtime.onInstalled.addListener(() => {
+  // Useful: first-time instructions.
+  void chrome.runtime.openOptionsPage()
+})

assets/chrome-extension/manifest.json

@@ -0,0 +1,25 @@
+{
+  "manifest_version": 3,
+  "name": "Clawdbot Browser Relay",
+  "version": "0.1.0",
+  "description": "Attach Clawdbot to your existing Chrome tab via a local CDP relay server.",
+  "icons": {
+    "16": "icons/icon16.png",
+    "32": "icons/icon32.png",
+    "48": "icons/icon48.png",
+    "128": "icons/icon128.png"
+  },
+  "permissions": ["debugger", "tabs", "activeTab", "storage"],
+  "host_permissions": ["http://127.0.0.1/*", "http://localhost/*"],
+  "background": { "service_worker": "background.js", "type": "module" },
+  "action": {
+    "default_title": "Clawdbot Browser Relay (click to attach/detach)",
+    "default_icon": {
+      "16": "icons/icon16.png",
+      "32": "icons/icon32.png",
+      "48": "icons/icon48.png",
+      "128": "icons/icon128.png"
+    }
+  },
+  "options_ui": { "page": "options.html", "open_in_tab": true }
+}

assets/chrome-extension/options.html

@@ -0,0 +1,197 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Clawdbot Browser Relay</title>
+    <style>
+      :root {
+        color-scheme: light dark;
+        --accent: #ff5a36;
+        --panel: color-mix(in oklab, canvas 92%, canvasText 8%);
+        --border: color-mix(in oklab, canvasText 18%, transparent);
+        --muted: color-mix(in oklab, canvasText 70%, transparent);
+        --shadow: 0 10px 30px color-mix(in oklab, canvasText 18%, transparent);
+        font-family: ui-rounded, system-ui, -apple-system, BlinkMacSystemFont, "SF Pro Rounded",
+          "SF Pro Display", "Segoe UI", sans-serif;
+        line-height: 1.4;
+      }
+      body {
+        margin: 0;
+        min-height: 100vh;
+        background:
+          radial-gradient(1000px 500px at 10% 0%, color-mix(in oklab, var(--accent) 30%, transparent), transparent 70%),
+          radial-gradient(900px 450px at 90% 0%, color-mix(in oklab, var(--accent) 18%, transparent), transparent 75%),
+          canvas;
+        color: canvasText;
+      }
+      .wrap {
+        max-width: 820px;
+        margin: 36px auto;
+        padding: 0 24px 48px 24px;
+      }
+      header {
+        display: flex;
+        align-items: center;
+        gap: 12px;
+        margin-bottom: 18px;
+      }
+      .logo {
+        width: 44px;
+        height: 44px;
+        border-radius: 14px;
+        background: color-mix(in oklab, var(--accent) 18%, transparent);
+        border: 1px solid color-mix(in oklab, var(--accent) 35%, transparent);
+        box-shadow: var(--shadow);
+        display: grid;
+        place-items: center;
+      }
+      .logo img {
+        width: 28px;
+        height: 28px;
+        image-rendering: pixelated;
+      }
+      h1 {
+        font-size: 20px;
+        margin: 0;
+        letter-spacing: -0.01em;
+      }
+      .subtitle {
+        margin: 2px 0 0 0;
+        color: var(--muted);
+        font-size: 13px;
+      }
+      .grid {
+        display: grid;
+        grid-template-columns: 1fr;
+        gap: 14px;
+      }
+      .card {
+        background: var(--panel);
+        border: 1px solid var(--border);
+        border-radius: 16px;
+        padding: 16px;
+        box-shadow: var(--shadow);
+      }
+      .card h2 {
+        margin: 0 0 10px 0;
+        font-size: 14px;
+        letter-spacing: 0.01em;
+      }
+      .card p {
+        margin: 8px 0 0 0;
+        color: var(--muted);
+        font-size: 13px;
+      }
+      .row {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        flex-wrap: wrap;
+      }
+      label {
+        display: block;
+        font-size: 12px;
+        color: var(--muted);
+        margin-bottom: 6px;
+      }
+      input {
+        width: 160px;
+        padding: 10px 12px;
+        border-radius: 12px;
+        border: 1px solid var(--border);
+        background: color-mix(in oklab, canvas 92%, canvasText 8%);
+        color: canvasText;
+        outline: none;
+      }
+      input:focus {
+        border-color: color-mix(in oklab, var(--accent) 70%, transparent);
+        box-shadow: 0 0 0 4px color-mix(in oklab, var(--accent) 20%, transparent);
+      }
+      button {
+        padding: 10px 14px;
+        border-radius: 12px;
+        border: 1px solid color-mix(in oklab, var(--accent) 55%, transparent);
+        background: linear-gradient(
+          180deg,
+          color-mix(in oklab, var(--accent) 80%, white 20%),
+          var(--accent)
+        );
+        color: white;
+        font-weight: 650;
+        letter-spacing: 0.01em;
+        cursor: pointer;
+      }
+      button:active {
+        transform: translateY(1px);
+      }
+      .hint {
+        margin-top: 10px;
+        font-size: 12px;
+        color: var(--muted);
+      }
+      code {
+        font-family: ui-monospace, Menlo, Monaco, Consolas, "SF Mono", monospace;
+        font-size: 12px;
+      }
+      a {
+        color: color-mix(in oklab, var(--accent) 85%, canvasText 15%);
+      }
+      .status {
+        margin-top: 10px;
+        font-size: 12px;
+        color: color-mix(in oklab, var(--accent) 70%, canvasText 30%);
+        min-height: 16px;
+      }
+      .status[data-kind='ok'] {
+        color: color-mix(in oklab, #16a34a 75%, canvasText 25%);
+      }
+      .status[data-kind='error'] {
+        color: color-mix(in oklab, #ef4444 75%, canvasText 25%);
+      }
+    </style>
+  </head>
+  <body>
+    <div class="wrap">
+      <header>
+        <div class="logo" aria-hidden="true">
+          <img src="icons/icon128.png" alt="" />
+        </div>
+        <div>
+          <h1>Clawdbot Browser Relay</h1>
+          <p class="subtitle">Click the toolbar button on a tab to attach / detach.</p>
+        </div>
+      </header>
+
+      <div class="grid">
+        <div class="card">
+          <h2>Getting started</h2>
+          <p>
+            If you see a red <code>!</code> badge on the extension icon, the relay server is not reachable.
+            Start Clawdbot’s browser relay on this machine (Gateway or <code>clawdbot browser serve</code>),
+            then click the toolbar button again.
+          </p>
+          <p>
+            Full guide (install, remote Gateway, security): <a href="https://docs.clawd.bot/tools/chrome-extension" target="_blank" rel="noreferrer">docs.clawd.bot/tools/chrome-extension</a>
+          </p>
+        </div>
+
+        <div class="card">
+          <h2>Relay port</h2>
+          <label for="port">Port</label>
+          <div class="row">
+            <input id="port" inputmode="numeric" pattern="[0-9]*" />
+            <button id="save" type="button">Save</button>
+          </div>
+          <div class="hint">
+            Default: <code>18792</code>. Extension connects to: <code id="relay-url">http://127.0.0.1:&lt;port&gt;/</code>.
+            Only change this if your Clawdbot profile uses a different <code>cdpUrl</code> port.
+          </div>
+          <div class="status" id="status"></div>
+        </div>
+      </div>
+
+      <script type="module" src="options.js"></script>
+    </div>
+  </body>
+</html>

assets/chrome-extension/options.js

@@ -0,0 +1,59 @@
+const DEFAULT_PORT = 18792
+
+function clampPort(value) {
+  const n = Number.parseInt(String(value || ''), 10)
+  if (!Number.isFinite(n)) return DEFAULT_PORT
+  if (n <= 0 || n > 65535) return DEFAULT_PORT
+  return n
+}
+
+function updateRelayUrl(port) {
+  const el = document.getElementById('relay-url')
+  if (!el) return
+  el.textContent = `http://127.0.0.1:${port}/`
+}
+
+function setStatus(kind, message) {
+  const status = document.getElementById('status')
+  if (!status) return
+  status.dataset.kind = kind || ''
+  status.textContent = message || ''
+}
+
+async function checkRelayReachable(port) {
+  const url = `http://127.0.0.1:${port}/`
+  const ctrl = new AbortController()
+  const t = setTimeout(() => ctrl.abort(), 900)
+  try {
+    const res = await fetch(url, { method: 'HEAD', signal: ctrl.signal })
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    setStatus('ok', `Relay reachable at ${url}`)
+  } catch {
+    setStatus(
+      'error',
+      `Relay not reachable at ${url}. Start Clawdbot’s browser relay on this machine, then click the toolbar button again.`,
+    )
+  } finally {
+    clearTimeout(t)
+  }
+}
+
+async function load() {
+  const stored = await chrome.storage.local.get(['relayPort'])
+  const port = clampPort(stored.relayPort)
+  document.getElementById('port').value = String(port)
+  updateRelayUrl(port)
+  await checkRelayReachable(port)
+}
+
+async function save() {
+  const input = document.getElementById('port')
+  const port = clampPort(input.value)
+  await chrome.storage.local.set({ relayPort: port })
+  input.value = String(port)
+  updateRelayUrl(port)
+  await checkRelayReachable(port)
+}
+
+document.getElementById('save').addEventListener('click', () => void save())
+void load()

biome.json

@@ -1,17 +0,0 @@
-{
-  "$schema": "https://biomejs.dev/schemas/biome.json",
-  "formatter": {
-    "enabled": true,
-    "indentWidth": 2,
-    "indentStyle": "space"
-  },
-  "files": {
-    "includes": ["src/**/*.ts", "test/**/*.ts"]
-  },
-  "linter": {
-    "enabled": true,
-    "rules": {
-      "recommended": true
-    }
-  }
-}

docs/_config.yml

@@ -41,7 +41,7 @@ nav:
   - title: "Android App"
     url: "/platforms/android/"
   - title: "Telegram"
-    url: "/providers/telegram/"
+    url: "/channels/telegram/"
   - title: "Security"
     url: "/gateway/security/"
   - title: "Troubleshooting"

docs/automation/cron-jobs.md

@@ -80,7 +80,7 @@ Key behaviors:
 - Prompt is prefixed with `[cron:<jobId> <job name>]` for traceability.
 - A summary is posted to the main session (prefix `Cron`, configurable).
 - `wakeMode: "now"` triggers an immediate heartbeat after posting the summary.
-- If `payload.deliver: true`, output is delivered to a provider; otherwise it stays internal.
+- If `payload.deliver: true`, output is delivered to a channel; otherwise it stays internal.
 
 Use isolated jobs for noisy, frequent, or "background chores" that shouldn't spam
 your main chat history.
@@ -94,9 +94,9 @@ Common `agentTurn` fields:
 - `message`: required text prompt.
 - `model` / `thinking`: optional overrides (see below).
 - `timeoutSeconds`: optional timeout override.
-- `deliver`: `true` to send output to a provider target.
-- `provider`: `last` or a specific provider.
-- `to`: provider-specific target (phone/chat/channel id).
+- `deliver`: `true` to send output to a channel target.
+- `channel`: `last` or a specific channel.
+- `to`: channel-specific target (phone/chat/channel id).
 - `bestEffortDeliver`: avoid failing the job if delivery fails.
 
 Isolation options (only for `session=isolated`):
@@ -116,12 +116,12 @@ Resolution priority:
 2. Hook-specific defaults (e.g., `hooks.gmail.model`)
 3. Agent config default
 
-### Delivery (provider + target)
-Isolated jobs can deliver output to a provider. The job payload can specify:
-- `provider`: `whatsapp` / `telegram` / `discord` / `slack` / `signal` / `imessage` / `last`
-- `to`: provider-specific recipient target
+### Delivery (channel + target)
+Isolated jobs can deliver output to a channel. The job payload can specify:
+- `channel`: `whatsapp` / `telegram` / `discord` / `slack` / `signal` / `imessage` / `last`
+- `to`: channel-specific recipient target
 
-If `provider` or `to` is omitted, cron can fall back to the main session’s “last route”
+If `channel` or `to` is omitted, cron can fall back to the main session’s “last route”
 (the last place the agent replied).
 
 Target format reminders:
@@ -192,7 +192,7 @@ clawdbot cron add \
   --session isolated \
   --message "Summarize inbox + calendar for today." \
   --deliver \
-  --provider whatsapp \
+  --channel whatsapp \
   --to "+15551234567"
 ```
 
@@ -205,7 +205,7 @@ clawdbot cron add \
   --session isolated \
   --message "Summarize today; send to the nightly topic." \
   --deliver \
-  --provider telegram \
+  --channel telegram \
   --to "-1001234567890:topic:123"
 ```
 
@@ -220,7 +220,7 @@ clawdbot cron add \
   --model "opus" \
   --thinking high \
   --deliver \
-  --provider whatsapp \
+  --channel whatsapp \
   --to "+15551234567"
 
 Agent selection (multi-agent setups):

docs/automation/gmail-pubsub.md

@@ -32,7 +32,7 @@ Example hook config (enable Gmail preset mapping):
 ```
 
 To deliver the Gmail summary to a chat surface, override the preset with a mapping
-that sets `deliver` + optional `provider`/`to`:
+that sets `deliver` + optional `channel`/`to`:
 
 ```json5
 {
@@ -51,7 +51,7 @@ that sets `deliver` + optional `provider`/`to`:
           "New email from {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}\n{{messages[0].body}}",
         model: "openai/gpt-5.2-mini",
         deliver: true,
-        provider: "last"
+        channel: "last"
         // to: "+15551234567"
       }
     ]
@@ -59,7 +59,7 @@ that sets `deliver` + optional `provider`/`to`:
 }
 ```
 
-If you want a fixed channel, set `provider` + `to`. Otherwise `provider: "last"`
+If you want a fixed channel, set `channel` + `to`. Otherwise `channel: "last"`
 uses the last delivery route (falls back to WhatsApp).
 
 To force a cheaper model for Gmail runs, set `model` in the mapping

docs/automation/poll.md

@@ -7,8 +7,8 @@ read_when:
 # Polls
 
 
-## Supported providers
-- WhatsApp (web provider)
+## Supported channels
+- WhatsApp (web channel)
 - Discord
 - MS Teams (Adaptive Cards)
 
@@ -22,18 +22,18 @@ clawdbot message poll --to 123456789@g.us \
   --poll-question "Meeting time?" --poll-option "10am" --poll-option "2pm" --poll-option "4pm" --poll-multi
 
 # Discord
-clawdbot message poll --provider discord --to channel:123456789 \
+clawdbot message poll --channel discord --to channel:123456789 \
   --poll-question "Snack?" --poll-option "Pizza" --poll-option "Sushi"
-clawdbot message poll --provider discord --to channel:123456789 \
+clawdbot message poll --channel discord --to channel:123456789 \
   --poll-question "Plan?" --poll-option "A" --poll-option "B" --poll-duration-hours 48
 
 # MS Teams
-clawdbot message poll --provider msteams --to conversation:19:abc@thread.tacv2 \
+clawdbot message poll --channel msteams --to conversation:19:abc@thread.tacv2 \
   --poll-question "Lunch?" --poll-option "Pizza" --poll-option "Sushi"
 ```
 
 Options:
-- `--provider`: `whatsapp` (default), `discord`, or `msteams`
+- `--channel`: `whatsapp` (default), `discord`, or `msteams`
 - `--poll-multi`: allow selecting multiple options
 - `--poll-duration-hours`: Discord-only (defaults to 24 when omitted)
 
@@ -47,16 +47,16 @@ Params:
 - `options` (string[], required)
 - `maxSelections` (number, optional)
 - `durationHours` (number, optional)
-- `provider` (string, optional, default: `whatsapp`)
+- `channel` (string, optional, default: `whatsapp`)
 - `idempotencyKey` (string, required)
 
-## Provider differences
+## Channel differences
 - WhatsApp: 2-12 options, `maxSelections` must be within option count, ignores `durationHours`.
 - Discord: 2-10 options, `durationHours` clamped to 1-768 hours (default 24). `maxSelections > 1` enables multi-select; Discord does not support a strict selection count.
 - MS Teams: Adaptive Card polls (Clawdbot-managed). No native poll API; `durationHours` is ignored.
 
 ## Agent tool (Message)
-Use the `message` tool with `poll` action (`to`, `pollQuestion`, `pollOption`, optional `pollMulti`, `pollDurationHours`, `provider`).
+Use the `message` tool with `poll` action (`to`, `pollQuestion`, `pollOption`, optional `pollMulti`, `pollDurationHours`, `channel`).
 
 Note: Discord has no “pick exactly N” mode; `pollMulti` maps to multi-select.
 Teams polls are rendered as Adaptive Cards and require the gateway to stay online

docs/automation/webhook.md

@@ -58,7 +58,7 @@ Payload:
   "sessionKey": "hook:email:msg-123",
   "wakeMode": "now",
   "deliver": true,
-  "provider": "last",
+  "channel": "last",
   "to": "+15551234567",
   "model": "openai/gpt-5.2-mini",
   "thinking": "low",
@@ -70,9 +70,9 @@ Payload:
 - `name` optional (string): Human-readable name for the hook (e.g., "GitHub"), used as a prefix in session summaries.
 - `sessionKey` optional (string): The key used to identify the agent's session. Defaults to a random `hook:<uuid>`. Using a consistent key allows for a multi-turn conversation within the hook context.
 - `wakeMode` optional (`now` | `next-heartbeat`): Whether to trigger an immediate heartbeat (default `now`) or wait for the next periodic check.
-- `deliver` optional (boolean): If `true`, the agent's response will be sent to the messaging provider. Defaults to `true`. Responses that are only heartbeat acknowledgments are automatically skipped.
-- `provider` optional (string): The messaging service for delivery. One of: `last`, `whatsapp`, `telegram`, `discord`, `slack`, `signal`, `imessage`, `msteams`. Defaults to `last`.
-- `to` optional (string): The recipient identifier for the provider (e.g., phone number for WhatsApp/Signal, chat ID for Telegram, channel ID for Discord/Slack, conversation ID for MS Teams). Defaults to the last recipient in the main session.
+- `deliver` optional (boolean): If `true`, the agent's response will be sent to the messaging channel. Defaults to `true`. Responses that are only heartbeat acknowledgments are automatically skipped.
+- `channel` optional (string): The messaging channel for delivery. One of: `last`, `whatsapp`, `telegram`, `discord`, `slack`, `signal`, `imessage`, `msteams`. Defaults to `last`.
+- `to` optional (string): The recipient identifier for the channel (e.g., phone number for WhatsApp/Signal, chat ID for Telegram, channel ID for Discord/Slack, conversation ID for MS Teams). Defaults to the last recipient in the main session.
 - `model` optional (string): Model override (e.g., `anthropic/claude-3-5-sonnet` or an alias). Must be in the allowed model list if restricted.
 - `thinking` optional (string): Thinking level override (e.g., `low`, `medium`, `high`).
 - `timeoutSeconds` optional (number): Maximum duration for the agent run in seconds.
@@ -94,8 +94,8 @@ Mapping options (summary):
 - `hooks.transformsDir` + `transform.module` loads a JS/TS module for custom logic.
 - Use `match.source` to keep a generic ingest endpoint (payload-driven routing).
 - TS transforms require a TS loader (e.g. `bun` or `tsx`) or precompiled `.js` at runtime.
-- Set `deliver: true` + `provider`/`to` on mappings to route replies to a chat surface
-  (`provider` defaults to `last` and falls back to WhatsApp).
+- Set `deliver: true` + `channel`/`to` on mappings to route replies to a chat surface
+  (`channel` defaults to `last` and falls back to WhatsApp).
 - `clawdbot hooks gmail setup` writes `hooks.gmail` config for `clawdbot hooks gmail run`.
 See [Gmail Pub/Sub](/automation/gmail-pubsub) for the full Gmail watch flow.
 

docs/broadcast-groups.md

@@ -15,9 +15,9 @@ status: experimental
 
 Broadcast Groups enable multiple agents to process and respond to the same message simultaneously. This allows you to create specialized agent teams that work together in a single WhatsApp group or DM — all using one phone number.
 
-Current scope: **WhatsApp only** (web provider).
+Current scope: **WhatsApp only** (web channel).
 
-Broadcast groups are evaluated after provider allowlists and group activation rules. In WhatsApp groups, this means broadcasts happen when Clawdbot would normally reply (for example: on mention, depending on your group settings).
+Broadcast groups are evaluated after channel allowlists and group activation rules. In WhatsApp groups, this means broadcasts happen when Clawdbot would normally reply (for example: on mention, depending on your group settings).
 
 ## Use Cases
 
@@ -152,7 +152,7 @@ Agents process in order (one waits for previous to finish):
 4. **If not in broadcast list**:
    - Normal routing applies (first matching binding)
 
-Note: broadcast groups do not bypass provider allowlists or group activation rules (mentions/commands/etc). They only change *which agents run* when a message is eligible for processing.
+Note: broadcast groups do not bypass channel allowlists or group activation rules (mentions/commands/etc). They only change *which agents run* when a message is eligible for processing.
 
 ### Session Isolation
 
@@ -272,7 +272,7 @@ Broadcast groups work alongside existing routing:
 ```json
 {
   "bindings": [
-    { "match": { "provider": "whatsapp", "peer": { "kind": "group", "id": "GROUP_A" } }, "agentId": "alfred" }
+    { "match": { "channel": "whatsapp", "peer": { "kind": "group", "id": "GROUP_A" } }, "agentId": "alfred" }
   ],
   "broadcast": {
     "GROUP_B": ["agent1", "agent2"]
@@ -403,5 +403,5 @@ Planned features:
 ## See Also
 
 - [Multi-Agent Configuration](/multi-agent-sandbox-tools)
-- [Routing Configuration](/concepts/provider-routing)
+- [Routing Configuration](/concepts/channel-routing)
 - [Session Management](/concepts/sessions)

docs/channels/discord.md

@@ -1,7 +1,7 @@
 ---
 summary: "Discord bot support status, capabilities, and configuration"
 read_when:
-  - Working on Discord provider features
+  - Working on Discord channel features
 ---
 # Discord (Bot API)
 
@@ -12,7 +12,7 @@ Status: ready for DM and guild text channels via the official Discord bot gatewa
 1) Create a Discord bot and copy the bot token.
 2) Set the token for Clawdbot:
    - Env: `DISCORD_BOT_TOKEN=...`
-   - Or config: `discord.token: "..."`.
+   - Or config: `channels.discord.token: "..."`.
 3) Invite the bot to your server with message permissions.
 4) Start the gateway.
 5) DM access is pairing by default; approve the pairing code on first contact.
@@ -20,9 +20,11 @@ Status: ready for DM and guild text channels via the official Discord bot gatewa
 Minimal config:
 ```json5
 {
-  discord: {
-    enabled: true,
-    token: "YOUR_BOT_TOKEN"
+  channels: {
+    discord: {
+      enabled: true,
+      token: "YOUR_BOT_TOKEN"
+    }
   }
 }
 ```
@@ -30,35 +32,45 @@ Minimal config:
 ## Goals
 - Talk to Clawdbot via Discord DMs or guild channels.
 - Direct chats collapse into the agent's main session (default `agent:main:main`); guild channels stay isolated as `agent:<agentId>:discord:channel:<channelId>` (display names use `discord:<guildSlug>#<channelSlug>`).
-- Group DMs are ignored by default; enable via `discord.dm.groupEnabled` and optionally restrict by `discord.dm.groupChannels`.
-- Keep routing deterministic: replies always go back to the provider they arrived on.
+- Group DMs are ignored by default; enable via `channels.discord.dm.groupEnabled` and optionally restrict by `channels.discord.dm.groupChannels`.
+- Keep routing deterministic: replies always go back to the channel they arrived on.
 
 ## How it works
 1. Create a Discord application → Bot, enable the intents you need (DMs + guild messages + message content), and grab the bot token.
 2. Invite the bot to your server with the permissions required to read/send messages where you want to use it.
-3. Configure Clawdbot with `DISCORD_BOT_TOKEN` (or `discord.token` in `~/.clawdbot/clawdbot.json`).
-4. Run the gateway; it auto-starts the Discord provider when a token is available (env or config) and `discord.enabled` is not `false`.
+3. Configure Clawdbot with `DISCORD_BOT_TOKEN` (or `channels.discord.token` in `~/.clawdbot/clawdbot.json`).
+4. Run the gateway; it auto-starts the Discord channel when a token is available (env or config) and `channels.discord.enabled` is not `false`.
    - If you prefer env vars, set `DISCORD_BOT_TOKEN` (a config block is optional).
 5. Direct chats: use `user:<id>` (or a `<@id>` mention) when delivering; all turns land in the shared `main` session. Bare numeric IDs are ambiguous and rejected.
 6. Guild channels: use `channel:<channelId>` for delivery. Mentions are required by default and can be set per guild or per channel.
-7. Direct chats: secure by default via `discord.dm.policy` (default: `"pairing"`). Unknown senders get a pairing code (expires after 1 hour); approve via `clawdbot pairing approve discord <code>`.
-   - To keep old “open to anyone” behavior: set `discord.dm.policy="open"` and `discord.dm.allowFrom=["*"]`.
-   - To hard-allowlist: set `discord.dm.policy="allowlist"` and list senders in `discord.dm.allowFrom`.
-   - To ignore all DMs: set `discord.dm.enabled=false` or `discord.dm.policy="disabled"`.
-8. Group DMs are ignored by default; enable via `discord.dm.groupEnabled` and optionally restrict by `discord.dm.groupChannels`.
-9. Optional guild rules: set `discord.guilds` keyed by guild id (preferred) or slug, with per-channel rules.
-10. Optional native commands: `commands.native` defaults to `"auto"` (on for Discord/Telegram, off for Slack). Override with `discord.commands.native: true|false|"auto"`; `false` clears previously registered commands. Text commands are controlled by `commands.text` and must be sent as standalone `/...` messages. Use `commands.useAccessGroups: false` to bypass access-group checks for commands.
+7. Direct chats: secure by default via `channels.discord.dm.policy` (default: `"pairing"`). Unknown senders get a pairing code (expires after 1 hour); approve via `clawdbot pairing approve discord <code>`.
+   - To keep old “open to anyone” behavior: set `channels.discord.dm.policy="open"` and `channels.discord.dm.allowFrom=["*"]`.
+   - To hard-allowlist: set `channels.discord.dm.policy="allowlist"` and list senders in `channels.discord.dm.allowFrom`.
+   - To ignore all DMs: set `channels.discord.dm.enabled=false` or `channels.discord.dm.policy="disabled"`.
+8. Group DMs are ignored by default; enable via `channels.discord.dm.groupEnabled` and optionally restrict by `channels.discord.dm.groupChannels`.
+9. Optional guild rules: set `channels.discord.guilds` keyed by guild id (preferred) or slug, with per-channel rules.
+10. Optional native commands: `commands.native` defaults to `"auto"` (on for Discord/Telegram, off for Slack). Override with `channels.discord.commands.native: true|false|"auto"`; `false` clears previously registered commands. Text commands are controlled by `commands.text` and must be sent as standalone `/...` messages. Use `commands.useAccessGroups: false` to bypass access-group checks for commands.
     - Full command list + config: [Slash commands](/tools/slash-commands)
-11. Optional guild context history: set `discord.historyLimit` (default 20, falls back to `messages.groupChat.historyLimit`) to include the last N guild messages as context when replying to a mention. Set `0` to disable.
-12. Reactions: the agent can trigger reactions via the `discord` tool (gated by `discord.actions.*`).
+11. Optional guild context history: set `channels.discord.historyLimit` (default 20, falls back to `messages.groupChat.historyLimit`) to include the last N guild messages as context when replying to a mention. Set `0` to disable.
+12. Reactions: the agent can trigger reactions via the `discord` tool (gated by `channels.discord.actions.*`).
     - Reaction removal semantics: see [/tools/reactions](/tools/reactions).
-    - The `discord` tool is only exposed when the current provider is Discord.
+    - The `discord` tool is only exposed when the current channel is Discord.
 13. Native commands use isolated session keys (`agent:<agentId>:discord:slash:<userId>`) rather than the shared `main` session.
 
 Note: Discord does not provide a simple username → id lookup without extra guild context, so prefer ids or `<@id>` mentions for DM delivery targets.
 Note: Slugs are lowercase with spaces replaced by `-`. Channel names are slugged without the leading `#`.
 Note: Guild context `[from:]` lines include `author.tag` + `id` to make ping-ready replies easy.
 
+## Config writes
+By default, Discord is allowed to write config updates triggered by `/config set|unset` (requires `commands.config: true`).
+
+Disable with:
+```json5
+{
+  channels: { discord: { configWrites: false } }
+}
+```
+
 ## How to create your own bot
 
 This is the “Discord Developer Portal” setup for running Clawdbot in a server (guild) channel like `#help`.
@@ -117,37 +129,41 @@ Or via config:
 
 ```json5
 {
-  discord: {
-    enabled: true,
-    token: "YOUR_BOT_TOKEN"
+  channels: {
+    discord: {
+      enabled: true,
+      token: "YOUR_BOT_TOKEN"
+    }
   }
 }
 ```
 
-Multi-account support: use `discord.accounts` with per-account tokens and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern.
+Multi-account support: use `channels.discord.accounts` with per-account tokens and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern.
 
 #### Allowlist + channel routing
 Example “single server, only allow me, only allow #help”:
 
 ```json5
 {
-  discord: {
-    enabled: true,
-    dm: { enabled: false },
-    guilds: {
-      "YOUR_GUILD_ID": {
-        users: ["YOUR_USER_ID"],
-        requireMention: true,
-        channels: {
-          help: { allow: true, requireMention: true }
+  channels: {
+    discord: {
+      enabled: true,
+      dm: { enabled: false },
+      guilds: {
+        "YOUR_GUILD_ID": {
+          users: ["YOUR_USER_ID"],
+          requireMention: true,
+          channels: {
+            help: { allow: true, requireMention: true }
+          }
         }
+      },
+      retry: {
+        attempts: 3,
+        minDelayMs: 500,
+        maxDelayMs: 30000,
+        jitter: 0.1
       }
-    },
-    retry: {
-      attempts: 3,
-      minDelayMs: 500,
-      maxDelayMs: 30000,
-      jitter: 0.1
     }
   }
 }
@@ -158,8 +174,8 @@ Notes:
 - `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`) also count as mentions for guild messages.
 - Multi-agent override: set per-agent patterns on `agents.list[].groupChat.mentionPatterns`.
 - If `channels` is present, any channel not listed is denied by default.
-- Bot-authored messages are ignored by default; set `discord.allowBots=true` to allow them (own messages remain filtered).
-- Warning: If you allow replies to other bots (`discord.allowBots=true`), prevent bot-to-bot reply loops with `requireMention`, `discord.guilds.*.channels.<id>.users` allowlists, and/or clear guardrails in `AGENTS.md` and `SOUL.md`.
+- Bot-authored messages are ignored by default; set `channels.discord.allowBots=true` to allow them (own messages remain filtered).
+- Warning: If you allow replies to other bots (`channels.discord.allowBots=true`), prevent bot-to-bot reply loops with `requireMention`, `channels.discord.guilds.*.channels.<id>.users` allowlists, and/or clear guardrails in `AGENTS.md` and `SOUL.md`.
 
 ### 6) Verify it works
 1. Start the gateway.
@@ -167,83 +183,88 @@ Notes:
 3. If nothing happens: check **Troubleshooting** below.
 
 ### Troubleshooting
-- First: run `clawdbot doctor` and `clawdbot providers status --probe` (actionable warnings + quick audits).
+- First: run `clawdbot doctor` and `clawdbot channels status --probe` (actionable warnings + quick audits).
 - **“Used disallowed intents”**: enable **Message Content Intent** (and likely **Server Members Intent**) in the Developer Portal, then restart the gateway.
 - **Bot connects but never replies in a guild channel**:
   - Missing **Message Content Intent**, or
   - The bot lacks channel permissions (View/Send/Read History), or
   - Your config requires mentions and you didn’t mention it, or
   - Your guild/channel allowlist denies the channel/user.
-- **Permission audits** (`providers status --probe`) only check numeric channel IDs. If you use slugs/names as `discord.guilds.*.channels` keys, the audit can’t verify permissions.
-- **DMs don’t work**: `discord.dm.enabled=false`, `discord.dm.policy="disabled"`, or you haven’t been approved yet (`discord.dm.policy="pairing"`).
+- **`requireMention: false` but still no replies**:
+  - `channels.discord.groupPolicy` defaults to **allowlist**; set it to `"open"` or explicitly list channels under `channels.discord.guilds.<id>.channels`.
+  - `requireMention` must live under `channels.discord.guilds` (or a specific channel). `channels.discord.requireMention` at the top level is ignored.
+- **Permission audits** (`channels status --probe`) only check numeric channel IDs. If you use slugs/names as `channels.discord.guilds.*.channels` keys, the audit can’t verify permissions.
+- **DMs don’t work**: `channels.discord.dm.enabled=false`, `channels.discord.dm.policy="disabled"`, or you haven’t been approved yet (`channels.discord.dm.policy="pairing"`).
 
 ## Capabilities & limits
 - DMs and guild text channels (threads are treated as separate channels; voice not supported).
-- Typing indicators sent best-effort; message chunking uses `discord.textChunkLimit` (default 2000) and splits tall replies by line count (`discord.maxLinesPerMessage`, default 17).
-- File uploads supported up to the configured `discord.mediaMaxMb` (default 8 MB).
+- Typing indicators sent best-effort; message chunking uses `channels.discord.textChunkLimit` (default 2000) and splits tall replies by line count (`channels.discord.maxLinesPerMessage`, default 17).
+- File uploads supported up to the configured `channels.discord.mediaMaxMb` (default 8 MB).
 - Mention-gated guild replies by default to avoid noisy bots.
 - Reply context is injected when a message references another message (quoted content + ids).
-- Native reply threading is **off by default**; enable with `discord.replyToMode` and reply tags.
+- Native reply threading is **off by default**; enable with `channels.discord.replyToMode` and reply tags.
 
 ## Retry policy
-Outbound Discord API calls retry on rate limits (429) using Discord `retry_after` when available, with exponential backoff and jitter. Configure via `discord.retry`. See [Retry policy](/concepts/retry).
+Outbound Discord API calls retry on rate limits (429) using Discord `retry_after` when available, with exponential backoff and jitter. Configure via `channels.discord.retry`. See [Retry policy](/concepts/retry).
 
 ## Config
 
 ```json5
 {
-  discord: {
-    enabled: true,
-    token: "abc.123",
-    groupPolicy: "allowlist",
-    guilds: {
-      "*": {
-        channels: {
-          general: { allow: true }
-        }
-      }
-    },
-    mediaMaxMb: 8,
-    actions: {
-      reactions: true,
-      stickers: true,
-      polls: true,
-      permissions: true,
-      messages: true,
-      threads: true,
-      pins: true,
-      search: true,
-      memberInfo: true,
-      roleInfo: true,
-      roles: false,
-      channelInfo: true,
-      voiceStatus: true,
-      events: true,
-      moderation: false
-    },
-    replyToMode: "off",
-    dm: {
+  channels: {
+    discord: {
       enabled: true,
-      policy: "pairing", // pairing | allowlist | open | disabled
-      allowFrom: ["123456789012345678", "steipete"],
-      groupEnabled: false,
-      groupChannels: ["clawd-dm"]
-    },
-    guilds: {
-      "*": { requireMention: true },
-      "123456789012345678": {
-        slug: "friends-of-clawd",
-        requireMention: false,
-        reactionNotifications: "own",
-        users: ["987654321098765432", "steipete"],
-        channels: {
-          general: { allow: true },
-          help: {
-            allow: true,
-            requireMention: true,
-            users: ["987654321098765432"],
-            skills: ["search", "docs"],
-            systemPrompt: "Keep answers short."
+      token: "abc.123",
+      groupPolicy: "allowlist",
+      guilds: {
+        "*": {
+          channels: {
+            general: { allow: true }
+          }
+        }
+      },
+      mediaMaxMb: 8,
+      actions: {
+        reactions: true,
+        stickers: true,
+        polls: true,
+        permissions: true,
+        messages: true,
+        threads: true,
+        pins: true,
+        search: true,
+        memberInfo: true,
+        roleInfo: true,
+        roles: false,
+        channelInfo: true,
+        voiceStatus: true,
+        events: true,
+        moderation: false
+      },
+      replyToMode: "off",
+      dm: {
+        enabled: true,
+        policy: "pairing", // pairing | allowlist | open | disabled
+        allowFrom: ["123456789012345678", "steipete"],
+        groupEnabled: false,
+        groupChannels: ["clawd-dm"]
+      },
+      guilds: {
+        "*": { requireMention: true },
+        "123456789012345678": {
+          slug: "friends-of-clawd",
+          requireMention: false,
+          reactionNotifications: "own",
+          users: ["987654321098765432", "steipete"],
+          channels: {
+            general: { allow: true },
+            help: {
+              allow: true,
+              requireMention: true,
+              users: ["987654321098765432"],
+              skills: ["search", "docs"],
+              systemPrompt: "Keep answers short."
+            }
           }
         }
       }
@@ -279,6 +300,7 @@ ack reaction after the bot replies.
 - `maxLinesPerMessage`: soft max line count per message. Default: 17.
 - `mediaMaxMb`: clamp inbound media saved to disk.
 - `historyLimit`: number of recent guild messages to include as context when replying to a mention (default 20; falls back to `messages.groupChat.historyLimit`; `0` disables).
+- `dmHistoryLimit`: DM history limit in user turns. Per-user overrides: `dms["<user_id>"].historyLimit`.
 - `retry`: retry policy for outbound Discord API calls (attempts, minDelayMs, maxDelayMs, jitter).
 - `actions`: per-action tool gates; omit to allow all (set `false` to disable).
   - `reactions` (covers react + read reactions)
@@ -320,7 +342,7 @@ To request a threaded reply, the model can include one tag in its output:
 - `[[reply_to:<id>]]` — reply to a specific message id from context/history.
 Current message ids are appended to prompts as `[message_id: …]`; history entries already include ids.
 
-Behavior is controlled by `discord.replyToMode`:
+Behavior is controlled by `channels.discord.replyToMode`:
 - `off`: ignore tags.
 - `first`: only the first outbound chunk/attachment is a reply.
 - `all`: every outbound chunk/attachment is a reply.
@@ -333,7 +355,7 @@ Allowlist matching notes:
 
 Native command notes:
 - The registered commands mirror Clawdbot’s chat commands.
-- Native commands honor the same allowlists as DMs/guild messages (`discord.dm.allowFrom`, `discord.guilds`, per-channel rules).
+- Native commands honor the same allowlists as DMs/guild messages (`channels.discord.dm.allowFrom`, `channels.discord.guilds`, per-channel rules).
 
 ## Tool actions
 The agent can call `discord` with actions like:

docs/channels/grammy.md

@@ -14,11 +14,11 @@ read_when:
 # What we shipped
 - **Single client path:** fetch-based implementation removed; grammY is now the sole Telegram client (send + gateway) with the grammY throttler enabled by default.
 - **Gateway:** `monitorTelegramProvider` builds a grammY `Bot`, wires mention/allowlist gating, media download via `getFile`/`download`, and delivers replies with `sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument`. Supports long-poll or webhook via `webhookCallback`.
-- **Proxy:** optional `telegram.proxy` uses `undici.ProxyAgent` through grammY’s `client.baseFetch`.
-- **Webhook support:** `webhook-set.ts` wraps `setWebhook/deleteWebhook`; `webhook.ts` hosts the callback with health + graceful shutdown. Gateway enables webhook mode when `telegram.webhookUrl` is set (otherwise it long-polls).
-- **Sessions:** direct chats collapse into the agent main session (`agent:<agentId>:<mainKey>`); groups use `agent:<agentId>:telegram:group:<chatId>`; replies route back to the same provider.
-- **Config knobs:** `telegram.botToken`, `telegram.dmPolicy`, `telegram.groups` (allowlist + mention defaults), `telegram.allowFrom`, `telegram.groupAllowFrom`, `telegram.groupPolicy`, `telegram.mediaMaxMb`, `telegram.proxy`, `telegram.webhookSecret`, `telegram.webhookUrl`.
-- **Draft streaming:** optional `telegram.streamMode` uses `sendMessageDraft` in private topic chats (Bot API 9.3+). This is separate from provider block streaming.
+- **Proxy:** optional `channels.telegram.proxy` uses `undici.ProxyAgent` through grammY’s `client.baseFetch`.
+- **Webhook support:** `webhook-set.ts` wraps `setWebhook/deleteWebhook`; `webhook.ts` hosts the callback with health + graceful shutdown. Gateway enables webhook mode when `channels.telegram.webhookUrl` is set (otherwise it long-polls).
+- **Sessions:** direct chats collapse into the agent main session (`agent:<agentId>:<mainKey>`); groups use `agent:<agentId>:telegram:group:<chatId>`; replies route back to the same channel.
+- **Config knobs:** `channels.telegram.botToken`, `channels.telegram.dmPolicy`, `channels.telegram.groups` (allowlist + mention defaults), `channels.telegram.allowFrom`, `channels.telegram.groupAllowFrom`, `channels.telegram.groupPolicy`, `channels.telegram.mediaMaxMb`, `channels.telegram.proxy`, `channels.telegram.webhookSecret`, `channels.telegram.webhookUrl`.
+- **Draft streaming:** optional `channels.telegram.streamMode` uses `sendMessageDraft` in private topic chats (Bot API 9.3+). This is separate from channel block streaming.
 - **Tests:** grammy mocks cover DM + group mention gating and outbound send; more media/webhook fixtures still welcome.
 
 Open questions

docs/channels/imessage.md

@@ -13,31 +13,43 @@ Status: external CLI integration. Gateway spawns `imsg rpc` (JSON-RPC over stdio
 1) Ensure Messages is signed in on this Mac.
 2) Install `imsg`:
    - `brew install steipete/tap/imsg`
-3) Configure Clawdbot with `imessage.cliPath` and `imessage.dbPath`.
+3) Configure Clawdbot with `channels.imessage.cliPath` and `channels.imessage.dbPath`.
 4) Start the gateway and approve any macOS prompts (Automation + Full Disk Access).
 
 Minimal config:
 ```json5
 {
-  imessage: {
-    enabled: true,
-    cliPath: "/usr/local/bin/imsg",
-    dbPath: "/Users/<you>/Library/Messages/chat.db"
+  channels: {
+    imessage: {
+      enabled: true,
+      cliPath: "/usr/local/bin/imsg",
+      dbPath: "/Users/<you>/Library/Messages/chat.db"
+    }
   }
 }
 ```
 
 ## What it is
-- iMessage provider backed by `imsg` on macOS.
+- iMessage channel backed by `imsg` on macOS.
 - Deterministic routing: replies always go back to iMessage.
 - DMs share the agent's main session; groups are isolated (`agent:<agentId>:imessage:group:<chat_id>`).
-- If a multi-participant thread arrives with `is_group=false`, you can still isolate it by `chat_id` using `imessage.groups` (see “Group-ish threads” below).
+- If a multi-participant thread arrives with `is_group=false`, you can still isolate it by `chat_id` using `channels.imessage.groups` (see “Group-ish threads” below).
+
+## Config writes
+By default, iMessage is allowed to write config updates triggered by `/config set|unset` (requires `commands.config: true`).
+
+Disable with:
+```json5
+{
+  channels: { imessage: { configWrites: false } }
+}
+```
 
 ## Requirements
 - macOS with Messages signed in.
 - Full Disk Access for Clawdbot + `imsg` (Messages DB access).
 - Automation permission when sending.
-- `imessage.cliPath` can point to any command that proxies stdin/stdout (for example, a wrapper script that SSHes to another Mac and runs `imsg rpc`).
+- `channels.imessage.cliPath` can point to any command that proxies stdin/stdout (for example, a wrapper script that SSHes to another Mac and runs `imsg rpc`).
 
 ## Setup (fast path)
 1) Ensure Messages is signed in on this Mac.
@@ -54,7 +66,7 @@ If you want the bot to send from a **separate iMessage identity** (and keep your
 5) Install `imsg`:
    - `brew install steipete/tap/imsg`
 6) Set up SSH so `ssh <bot-macos-user>@localhost true` works without a password.
-7) Point `imessage.accounts.bot.cliPath` at an SSH wrapper that runs `imsg` as the bot user.
+7) Point `channels.imessage.accounts.bot.cliPath` at an SSH wrapper that runs `imsg` as the bot user.
 
 First-run note: sending/receiving may require GUI approvals (Automation + Full Disk Access) in the *bot macOS user*. If `imsg rpc` looks stuck or exits, log into that user (Screen Sharing helps), run a one-time `imsg chats --limit 1` / `imsg send ...`, approve prompts, then retry.
 
@@ -72,24 +84,26 @@ exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T <bot-macos-user>@local
 Example config:
 ```json5
 {
-  imessage: {
-    enabled: true,
-    accounts: {
-      bot: {
-        name: "Bot",
-        enabled: true,
-        cliPath: "/path/to/imsg-bot",
-        dbPath: "/Users/<bot-macos-user>/Library/Messages/chat.db"
+  channels: {
+    imessage: {
+      enabled: true,
+      accounts: {
+        bot: {
+          name: "Bot",
+          enabled: true,
+          cliPath: "/path/to/imsg-bot",
+          dbPath: "/Users/<bot-macos-user>/Library/Messages/chat.db"
+        }
       }
     }
   }
 }
 ```
 
-For single-account setups, use flat options (`imessage.cliPath`, `imessage.dbPath`) instead of the `accounts` map.
+For single-account setups, use flat options (`channels.imessage.cliPath`, `channels.imessage.dbPath`) instead of the `accounts` map.
 
 ### Remote/SSH variant (optional)
-If you want iMessage on another Mac, set `imessage.cliPath` to a wrapper that runs `imsg` on the remote macOS host over SSH. Clawdbot only needs stdio.
+If you want iMessage on another Mac, set `channels.imessage.cliPath` to a wrapper that runs `imsg` on the remote macOS host over SSH. Clawdbot only needs stdio.
 
 Example wrapper:
 ```bash
@@ -97,11 +111,11 @@ Example wrapper:
 exec ssh -T mac-mini imsg "$@"
 ```
 
-Multi-account support: use `imessage.accounts` with per-account config and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern. Don’t commit `~/.clawdbot/clawdbot.json` (it often contains tokens).
+Multi-account support: use `channels.imessage.accounts` with per-account config and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern. Don’t commit `~/.clawdbot/clawdbot.json` (it often contains tokens).
 
 ## Access control (DMs + groups)
 DMs:
-- Default: `imessage.dmPolicy = "pairing"`.
+- Default: `channels.imessage.dmPolicy = "pairing"`.
 - Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
 - Approve via:
   - `clawdbot pairing list imessage`
@@ -109,30 +123,32 @@ DMs:
 - Pairing is the default token exchange for iMessage DMs. Details: [Pairing](/start/pairing)
 
 Groups:
-- `imessage.groupPolicy = open | allowlist | disabled`.
-- `imessage.groupAllowFrom` controls who can trigger in groups when `allowlist` is set.
+- `channels.imessage.groupPolicy = open | allowlist | disabled`.
+- `channels.imessage.groupAllowFrom` controls who can trigger in groups when `allowlist` is set.
 - Mention gating uses `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`) because iMessage has no native mention metadata.
 - Multi-agent override: set per-agent patterns on `agents.list[].groupChat.mentionPatterns`.
 
 ## How it works (behavior)
-- `imsg` streams message events; the gateway normalizes them into the shared provider envelope.
+- `imsg` streams message events; the gateway normalizes them into the shared channel envelope.
 - Replies always route back to the same chat id or handle.
 
 ## Group-ish threads (`is_group=false`)
 Some iMessage threads can have multiple participants but still arrive with `is_group=false` depending on how Messages stores the chat identifier.
 
-If you explicitly configure a `chat_id` under `imessage.groups`, Clawdbot treats that thread as a “group” for:
+If you explicitly configure a `chat_id` under `channels.imessage.groups`, Clawdbot treats that thread as a “group” for:
 - session isolation (separate `agent:<agentId>:imessage:group:<chat_id>` session key)
 - group allowlisting / mention gating behavior
 
 Example:
 ```json5
 {
-  imessage: {
-    groupPolicy: "allowlist",
-    groupAllowFrom: ["+15555550123"],
-    groups: {
-      "42": { "requireMention": false }
+  channels: {
+    imessage: {
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["+15555550123"],
+      groups: {
+        "42": { "requireMention": false }
+      }
     }
   }
 }
@@ -140,12 +156,12 @@ Example:
 This is useful when you want an isolated personality/model for a specific thread (see [Multi-agent routing](/concepts/multi-agent)). For filesystem isolation, see [Sandboxing](/gateway/sandboxing).
 
 ## Media + limits
-- Optional attachment ingestion via `imessage.includeAttachments`.
-- Media cap via `imessage.mediaMaxMb`.
+- Optional attachment ingestion via `channels.imessage.includeAttachments`.
+- Media cap via `channels.imessage.mediaMaxMb`.
 
 ## Limits
-- Outbound text is chunked to `imessage.textChunkLimit` (default 4000).
-- Media uploads are capped by `imessage.mediaMaxMb` (default 16).
+- Outbound text is chunked to `channels.imessage.textChunkLimit` (default 4000).
+- Media uploads are capped by `channels.imessage.mediaMaxMb` (default 16).
 
 ## Addressing / delivery targets
 Prefer `chat_id` for stable routing:
@@ -163,20 +179,21 @@ imsg chats --limit 20
 Full configuration: [Configuration](/gateway/configuration)
 
 Provider options:
-- `imessage.enabled`: enable/disable provider startup.
-- `imessage.cliPath`: path to `imsg`.
-- `imessage.dbPath`: Messages DB path.
-- `imessage.service`: `imessage | sms | auto`.
-- `imessage.region`: SMS region.
-- `imessage.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).
-- `imessage.allowFrom`: DM allowlist (handles or `chat_id:*`). `open` requires `"*"`.
-- `imessage.groupPolicy`: `open | allowlist | disabled` (default: allowlist).
-- `imessage.groupAllowFrom`: group sender allowlist.
-- `imessage.historyLimit` / `imessage.accounts.*.historyLimit`: max group messages to include as context (0 disables).
-- `imessage.groups`: per-group defaults + allowlist (use `"*"` for global defaults).
-- `imessage.includeAttachments`: ingest attachments into context.
-- `imessage.mediaMaxMb`: inbound/outbound media cap (MB).
-- `imessage.textChunkLimit`: outbound chunk size (chars).
+- `channels.imessage.enabled`: enable/disable channel startup.
+- `channels.imessage.cliPath`: path to `imsg`.
+- `channels.imessage.dbPath`: Messages DB path.
+- `channels.imessage.service`: `imessage | sms | auto`.
+- `channels.imessage.region`: SMS region.
+- `channels.imessage.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).
+- `channels.imessage.allowFrom`: DM allowlist (handles or `chat_id:*`). `open` requires `"*"`.
+- `channels.imessage.groupPolicy`: `open | allowlist | disabled` (default: allowlist).
+- `channels.imessage.groupAllowFrom`: group sender allowlist.
+- `channels.imessage.historyLimit` / `channels.imessage.accounts.*.historyLimit`: max group messages to include as context (0 disables).
+- `channels.imessage.dmHistoryLimit`: DM history limit in user turns. Per-user overrides: `channels.imessage.dms["<handle>"].historyLimit`.
+- `channels.imessage.groups`: per-group defaults + allowlist (use `"*"` for global defaults).
+- `channels.imessage.includeAttachments`: ingest attachments into context.
+- `channels.imessage.mediaMaxMb`: inbound/outbound media cap (MB).
+- `channels.imessage.textChunkLimit`: outbound chunk size (chars).
 
 Related global options:
 - `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`).

docs/channels/index.md

@@ -0,0 +1,31 @@
+---
+summary: "Messaging platforms Clawdbot can connect to"
+read_when:
+  - You want to choose a chat channel for Clawdbot
+  - You need a quick overview of supported messaging platforms
+---
+# Chat Channels
+
+Clawdbot can talk to you on any chat app you already use. Each channel connects via the Gateway.
+Text is supported everywhere; media and reactions vary by channel.
+
+## Supported channels
+
+- [WhatsApp](/channels/whatsapp) — Most popular; uses Baileys and requires QR pairing.
+- [Telegram](/channels/telegram) — Bot API via grammY; supports groups.
+- [Discord](/channels/discord) — Discord Bot API + Gateway; supports servers, channels, and DMs.
+- [Slack](/channels/slack) — Bolt SDK; workspace apps.
+- [Signal](/channels/signal) — signal-cli; privacy-focused.
+- [iMessage](/channels/imessage) — macOS only; native integration.
+- [Microsoft Teams](/channels/msteams) — Bot Framework; enterprise support.
+- [Zalo](/channels/zalo) — Zalo Bot API; Vietnam's popular messenger (plugin, installed separately).
+- [WebChat](/web/webchat) — Gateway WebChat UI over WebSocket.
+
+## Notes
+
+- Channels can run simultaneously; configure multiple and Clawdbot will route per chat.
+- Group behavior varies by channel; see [Groups](/concepts/groups).
+- DM pairing and allowlists are enforced for safety; see [Security](/gateway/security).
+- Telegram internals: [grammY notes](/channels/grammy).
+- Troubleshooting: [Channel troubleshooting](/channels/troubleshooting).
+- Model providers are documented separately; see [Model Providers](/providers/models).

docs/channels/location.md

@@ -1,13 +1,13 @@
 ---
-summary: "Inbound provider location parsing (Telegram + WhatsApp) and context fields"
+summary: "Inbound channel location parsing (Telegram + WhatsApp) and context fields"
 read_when:
-  - Adding or modifying provider location parsing
+  - Adding or modifying channel location parsing
   - Using location context fields in agent prompts or tools
 ---
 
-# Provider location parsing
+# Channel location parsing
 
-Clawdbot normalizes shared locations from chat providers into:
+Clawdbot normalizes shared locations from chat channels into:
 - human-readable text appended to the inbound body, and
 - structured fields in the auto-reply context payload.
 
@@ -25,7 +25,7 @@ Locations are rendered as friendly lines without brackets:
 - Live share:
   - `🛰 Live location: 48.858844, 2.294351 ±12m`
 
-If the provider includes a caption/comment, it is appended on the next line:
+If the channel includes a caption/comment, it is appended on the next line:
 ```
 📍 48.858844, 2.294351 ±12m
 Meet here
@@ -41,6 +41,6 @@ When a location is present, these fields are added to `ctx`:
 - `LocationSource` (`pin | place | live`)
 - `LocationIsLive` (boolean)
 
-## Provider notes
+## Channel notes
 - **Telegram**: venues map to `LocationName/LocationAddress`; live locations use `live_period`.
 - **WhatsApp**: `locationMessage.comment` and `liveLocationMessage.caption` are appended as the caption line.

docs/channels/msteams.md

@@ -1,7 +1,7 @@
 ---
 summary: "Microsoft Teams bot support status, capabilities, and configuration"
 read_when:
-  - Working on MS Teams provider features
+  - Working on MS Teams channel features
 ---
 # Microsoft Teams (Bot Framework)
 
@@ -21,39 +21,53 @@ Status: text + DM attachments are supported; channel/group attachments require M
 Minimal config:
 ```json5
 {
-  msteams: {
-    enabled: true,
-    appId: "<APP_ID>",
-    appPassword: "<APP_PASSWORD>",
-    tenantId: "<TENANT_ID>",
-    webhook: { port: 3978, path: "/api/messages" }
+  channels: {
+    msteams: {
+      enabled: true,
+      appId: "<APP_ID>",
+      appPassword: "<APP_PASSWORD>",
+      tenantId: "<TENANT_ID>",
+      webhook: { port: 3978, path: "/api/messages" }
+    }
   }
 }
 ```
-Note: group chats are blocked by default (`msteams.groupPolicy: "allowlist"`). To allow group replies, set `msteams.groupAllowFrom` (or use `groupPolicy: "open"` to allow any member, mention-gated).
+Note: group chats are blocked by default (`channels.msteams.groupPolicy: "allowlist"`). To allow group replies, set `channels.msteams.groupAllowFrom` (or use `groupPolicy: "open"` to allow any member, mention-gated).
 
 ## Goals
 - Talk to Clawdbot via Teams DMs, group chats, or channels.
-- Keep routing deterministic: replies always go back to the provider they arrived on.
+- Keep routing deterministic: replies always go back to the channel they arrived on.
 - Default to safe channel behavior (mentions required unless configured otherwise).
 
+## Config writes
+By default, Microsoft Teams is allowed to write config updates triggered by `/config set|unset` (requires `commands.config: true`).
+
+Disable with:
+```json5
+{
+  channels: { msteams: { configWrites: false } }
+}
+```
+
 ## Access control (DMs + groups)
 
 **DM access**
-- Default: `msteams.dmPolicy = "pairing"`. Unknown senders are ignored until approved.
-- `msteams.allowFrom` accepts AAD object IDs or UPNs.
+- Default: `channels.msteams.dmPolicy = "pairing"`. Unknown senders are ignored until approved.
+- `channels.msteams.allowFrom` accepts AAD object IDs or UPNs.
 
 **Group access**
-- Default: `msteams.groupPolicy = "allowlist"` (blocked unless you add `groupAllowFrom`).
-- `msteams.groupAllowFrom` controls which senders can trigger in group chats/channels (falls back to `msteams.allowFrom`).
+- Default: `channels.msteams.groupPolicy = "allowlist"` (blocked unless you add `groupAllowFrom`).
+- `channels.msteams.groupAllowFrom` controls which senders can trigger in group chats/channels (falls back to `channels.msteams.allowFrom`).
 - Set `groupPolicy: "open"` to allow any member (still mention‑gated by default).
 
 Example:
 ```json5
 {
-  msteams: {
-    groupPolicy: "allowlist",
-    groupAllowFrom: ["user@org.com"]
+  channels: {
+    msteams: {
+      groupPolicy: "allowlist",
+      groupAllowFrom: ["user@org.com"]
+    }
   }
 }
 ```
@@ -189,11 +203,12 @@ This is often easier than hand-editing JSON manifests.
      - `https://<host>:3978/api/messages` (or your chosen path/port).
 
 5. **Run the gateway**
-   - The Teams provider starts automatically when `msteams` config exists and credentials are set.
+   - The Teams channel starts automatically when `msteams` config exists and credentials are set.
 
 ## History context
-- `msteams.historyLimit` controls how many recent channel/group messages are wrapped into the prompt.
+- `channels.msteams.historyLimit` controls how many recent channel/group messages are wrapped into the prompt.
 - Falls back to `messages.groupChat.historyLimit`. Set `0` to disable (default 50).
+- DM history can be limited with `channels.msteams.dmHistoryLimit` (user turns). Per-user overrides: `channels.msteams.dms["<user_id>"].historyLimit`.
 
 ## Current Teams RSC Permissions (Manifest)
 These are the **existing resourceSpecific permissions** in our Teams app manifest. They only apply inside the team/chat where the app is installed.
@@ -336,22 +351,22 @@ Teams markdown is more limited than Slack or Discord:
 - Adaptive Cards are used for polls; other card types are not yet supported
 
 ## Configuration
-Key settings (see `/gateway/configuration` for shared provider patterns):
+Key settings (see `/gateway/configuration` for shared channel patterns):
 
-- `msteams.enabled`: enable/disable the provider.
-- `msteams.appId`, `msteams.appPassword`, `msteams.tenantId`: bot credentials.
-- `msteams.webhook.port` (default `3978`)
-- `msteams.webhook.path` (default `/api/messages`)
-- `msteams.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing)
-- `msteams.allowFrom`: allowlist for DMs (AAD object IDs or UPNs).
-- `msteams.textChunkLimit`: outbound text chunk size.
-- `msteams.mediaAllowHosts`: allowlist for inbound attachment hosts (defaults to Microsoft/Teams domains).
-- `msteams.requireMention`: require @mention in channels/groups (default true).
-- `msteams.replyStyle`: `thread | top-level` (see [Reply Style](#reply-style-threads-vs-posts)).
-- `msteams.teams.<teamId>.replyStyle`: per-team override.
-- `msteams.teams.<teamId>.requireMention`: per-team override.
-- `msteams.teams.<teamId>.channels.<conversationId>.replyStyle`: per-channel override.
-- `msteams.teams.<teamId>.channels.<conversationId>.requireMention`: per-channel override.
+- `channels.msteams.enabled`: enable/disable the channel.
+- `channels.msteams.appId`, `channels.msteams.appPassword`, `channels.msteams.tenantId`: bot credentials.
+- `channels.msteams.webhook.port` (default `3978`)
+- `channels.msteams.webhook.path` (default `/api/messages`)
+- `channels.msteams.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing)
+- `channels.msteams.allowFrom`: allowlist for DMs (AAD object IDs or UPNs).
+- `channels.msteams.textChunkLimit`: outbound text chunk size.
+- `channels.msteams.mediaAllowHosts`: allowlist for inbound attachment hosts (defaults to Microsoft/Teams domains).
+- `channels.msteams.requireMention`: require @mention in channels/groups (default true).
+- `channels.msteams.replyStyle`: `thread | top-level` (see [Reply Style](#reply-style-threads-vs-posts)).
+- `channels.msteams.teams.<teamId>.replyStyle`: per-team override.
+- `channels.msteams.teams.<teamId>.requireMention`: per-team override.
+- `channels.msteams.teams.<teamId>.channels.<conversationId>.replyStyle`: per-channel override.
+- `channels.msteams.teams.<teamId>.channels.<conversationId>.requireMention`: per-channel override.
 
 ## Routing & Sessions
 - Session keys follow the standard agent format (see [/concepts/session](/concepts/session)):
@@ -399,12 +414,12 @@ Teams recently introduced two channel UI styles over the same underlying data mo
 - **Channels/groups:** Attachments live in M365 storage (SharePoint/OneDrive). The webhook payload only includes an HTML stub, not the actual file bytes. **Graph API permissions are required** to download channel attachments.
 
 Without Graph permissions, channel messages with images will be received as text-only (the image content is not accessible to the bot).
-By default, Clawdbot only downloads media from Microsoft/Teams hostnames. Override with `msteams.mediaAllowHosts` (use `["*"]` to allow any host).
+By default, Clawdbot only downloads media from Microsoft/Teams hostnames. Override with `channels.msteams.mediaAllowHosts` (use `["*"]` to allow any host).
 
 ## Polls (Adaptive Cards)
 Clawdbot sends Teams polls as Adaptive Cards (there is no native Teams poll API).
 
-- CLI: `clawdbot message poll --provider msteams --to conversation:<id> ...`
+- CLI: `clawdbot message poll --channel msteams --to conversation:<id> ...`
 - Votes are recorded by the gateway in `~/.clawdbot/msteams-polls.json`.
 - The gateway must stay online to record votes.
 - Polls do not auto-post result summaries yet (inspect the store file if needed).
@@ -458,7 +473,7 @@ Bots have limited support in private channels:
 ### Common issues
 
 - **Images not showing in channels:** Graph permissions or admin consent missing. Reinstall the Teams app and fully quit/reopen Teams.
-- **No responses in channel:** mentions are required by default; set `msteams.requireMention=false` or configure per team/channel.
+- **No responses in channel:** mentions are required by default; set `channels.msteams.requireMention=false` or configure per team/channel.
 - **Version mismatch (Teams still shows old manifest):** remove + re-add the app and fully quit Teams to refresh.
 - **401 Unauthorized from webhook:** Expected when testing manually without Azure JWT - means endpoint is reachable but auth failed. Use Azure Web Chat to test properly.
 

docs/channels/signal.md

@@ -0,0 +1,134 @@
+---
+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. Gateway talks to `signal-cli` over HTTP JSON-RPC + SSE.
+
+## Quick setup (beginner)
+1) Use a **separate Signal number** for the bot (recommended).
+2) Install `signal-cli` (Java required).
+3) Link the bot device and start the daemon:
+   - `signal-cli link -n "Clawdbot"`
+4) Configure Clawdbot and start the gateway.
+
+Minimal config:
+```json5
+{
+  channels: {
+    signal: {
+      enabled: true,
+      account: "+15551234567",
+      cliPath: "signal-cli",
+      dmPolicy: "pairing",
+      allowFrom: ["+15557654321"]
+    }
+  }
+}
+```
+
+## What it is
+- Signal channel via `signal-cli` (not embedded libsignal).
+- Deterministic routing: replies always go back to Signal.
+- DMs share the agent's main session; groups are isolated (`agent:<agentId>:signal:group:<groupId>`).
+
+## Config writes
+By default, Signal is allowed to write config updates triggered by `/config set|unset` (requires `commands.config: true`).
+
+Disable with:
+```json5
+{
+  channels: { signal: { configWrites: false } }
+}
+```
+
+## The number model (important)
+- The gateway connects to a **Signal device** (the `signal-cli` account).
+- If you run the bot on **your personal Signal account**, it will ignore your own messages (loop protection).
+- For "I text the bot and it replies," use a **separate bot number**.
+
+## Setup (fast path)
+1) Install `signal-cli` (Java required).
+2) Link a bot account:
+   - `signal-cli link -n "Clawdbot"` then scan the QR in Signal.
+3) Configure Signal and start the gateway.
+
+Example:
+```json5
+{
+  channels: {
+    signal: {
+      enabled: true,
+      account: "+15551234567",
+      cliPath: "signal-cli",
+      dmPolicy: "pairing",
+      allowFrom: ["+15557654321"]
+    }
+  }
+}
+```
+
+Multi-account support: use `channels.signal.accounts` with per-account config and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern.
+
+## Access control (DMs + groups)
+DMs:
+- Default: `channels.signal.dmPolicy = "pairing"`.
+- Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
+- Approve via:
+  - `clawdbot pairing list signal`
+  - `clawdbot pairing approve signal <CODE>`
+- Pairing is the default token exchange for Signal DMs. Details: [Pairing](/start/pairing)
+- UUID-only senders (from `sourceUuid`) are stored as `uuid:<id>` in `channels.signal.allowFrom`.
+
+Groups:
+- `channels.signal.groupPolicy = open | allowlist | disabled`.
+- `channels.signal.groupAllowFrom` controls who can trigger in groups when `allowlist` is set.
+
+## How it works (behavior)
+- `signal-cli` runs as a daemon; the gateway reads events via SSE.
+- Inbound messages are normalized into the shared channel envelope.
+- Replies always route back to the same number or group.
+
+## Media + limits
+- Outbound text is chunked to `channels.signal.textChunkLimit` (default 4000).
+- Attachments supported (base64 fetched from `signal-cli`).
+- Default media cap: `channels.signal.mediaMaxMb` (default 8).
+- Use `channels.signal.ignoreAttachments` to skip downloading media.
+- Group history context uses `channels.signal.historyLimit` (or `channels.signal.accounts.*.historyLimit`), falling back to `messages.groupChat.historyLimit`. Set `0` to disable (default 50).
+
+## Delivery targets (CLI/cron)
+- DMs: `signal:+15551234567` (or plain E.164).
+- Groups: `signal:group:<groupId>`.
+- Usernames: `username:<name>` (if supported by your Signal account).
+
+## Configuration reference (Signal)
+Full configuration: [Configuration](/gateway/configuration)
+
+Provider options:
+- `channels.signal.enabled`: enable/disable channel startup.
+- `channels.signal.account`: E.164 for the bot account.
+- `channels.signal.cliPath`: path to `signal-cli`.
+- `channels.signal.httpUrl`: full daemon URL (overrides host/port).
+- `channels.signal.httpHost`, `channels.signal.httpPort`: daemon bind (default 127.0.0.1:8080).
+- `channels.signal.autoStart`: auto-spawn daemon (default true if `httpUrl` unset).
+- `channels.signal.receiveMode`: `on-start | manual`.
+- `channels.signal.ignoreAttachments`: skip attachment downloads.
+- `channels.signal.ignoreStories`: ignore stories from the daemon.
+- `channels.signal.sendReadReceipts`: forward read receipts.
+- `channels.signal.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).
+- `channels.signal.allowFrom`: DM allowlist (E.164 or `uuid:<id>`). `open` requires `"*"`.
+- `channels.signal.groupPolicy`: `open | allowlist | disabled` (default: allowlist).
+- `channels.signal.groupAllowFrom`: group sender allowlist.
+- `channels.signal.historyLimit`: max group messages to include as context (0 disables).
+- `channels.signal.dmHistoryLimit`: DM history limit in user turns. Per-user overrides: `channels.signal.dms["<phone_or_uuid>"].historyLimit`.
+- `channels.signal.textChunkLimit`: outbound chunk size (chars).
+- `channels.signal.mediaMaxMb`: inbound/outbound media cap (MB).
+
+Related global options:
+- `agents.list[].groupChat.mentionPatterns` (Signal does not support native mentions).
+- `messages.groupChat.mentionPatterns` (global fallback).
+- `messages.responsePrefix`.

docs/channels/slack.md

@@ -13,16 +13,18 @@ read_when: "Setting up Slack or debugging Slack socket mode"
 Minimal config:
 ```json5
 {
-  slack: {
-    enabled: true,
-    appToken: "xapp-...",
-    botToken: "xoxb-..."
+  channels: {
+    slack: {
+      enabled: true,
+      appToken: "xapp-...",
+      botToken: "xoxb-..."
+    }
   }
 }
 ```
 
 ## Setup
-1) Create a Slack app (From scratch) in https://api.slack.com/apps.
+1) Create a Slack app (From scratch) in https://api.channels.slack.com/apps.
 2) **Socket Mode** → toggle on. Then go to **Basic Information** → **App-Level Tokens** → **Generate Token and Scopes** with scope `connections:write`. Copy the **App Token** (`xapp-...`).
 3) **OAuth & Permissions** → add bot token scopes (use the manifest below). Click **Install to Workspace**. Copy the **Bot User OAuth Token** (`xoxb-...`).
 4) **Event Subscriptions** → enable events and subscribe to:
@@ -30,15 +32,16 @@ Minimal config:
    - `app_mention`
    - `reaction_added`, `reaction_removed`
    - `member_joined_channel`, `member_left_channel`
+   - `channel_id_changed`
    - `channel_rename`
    - `pin_added`, `pin_removed`
 5) Invite the bot to channels you want it to read.
-6) Slash Commands → create `/clawd` if you use `slack.slashCommand`. If you enable native commands, add one slash command per built-in command (same names as `/help`). Native defaults to off for Slack unless you set `slack.commands.native: true` (global `commands.native` is `"auto"` which leaves Slack off).
+6) Slash Commands → create `/clawd` if you use `channels.slack.slashCommand`. If you enable native commands, add one slash command per built-in command (same names as `/help`). Native defaults to off for Slack unless you set `channels.slack.commands.native: true` (global `commands.native` is `"auto"` which leaves Slack off).
 7) App Home → enable the **Messages Tab** so users can DM the bot.
 
 Use the manifest below so scopes and events stay in sync.
 
-Multi-account support: use `slack.accounts` with per-account tokens and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern.
+Multi-account support: use `channels.slack.accounts` with per-account tokens and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern.
 
 ## Clawdbot config (minimal)
 
@@ -50,17 +53,34 @@ Or via config:
 
 ```json5
 {
-  slack: {
-    enabled: true,
-    appToken: "xapp-...",
-    botToken: "xoxb-..."
+  channels: {
+    slack: {
+      enabled: true,
+      appToken: "xapp-...",
+      botToken: "xoxb-..."
+    }
   }
 }
 ```
 
 ## History context
-- `slack.historyLimit` (or `slack.accounts.*.historyLimit`) controls how many recent channel/group messages are wrapped into the prompt.
+- `channels.slack.historyLimit` (or `channels.slack.accounts.*.historyLimit`) controls how many recent channel/group messages are wrapped into the prompt.
 - Falls back to `messages.groupChat.historyLimit`. Set `0` to disable (default 50).
+- DM history can be limited with `channels.slack.dmHistoryLimit` (user turns). Per-user overrides: `channels.slack.dms["<user_id>"].historyLimit`.
+
+## Config writes
+By default, Slack is allowed to write config updates triggered by channel events or `/config set|unset`.
+
+This happens when:
+- Slack emits `channel_id_changed` (e.g. Slack Connect channel ID changes). Clawdbot can migrate `channels.slack.channels` automatically.
+- You run `/config set` or `/config unset` in Slack (requires `commands.config: true`).
+
+Disable with:
+```json5
+{
+  channels: { slack: { configWrites: false } }
+}
+```
 
 ## Manifest (optional)
 Use this Slack app manifest to create the app quickly (adjust the name/command if you want).
@@ -129,6 +149,7 @@ Use this Slack app manifest to create the app quickly (adjust the name/command i
         "reaction_removed",
         "member_joined_channel",
         "member_left_channel",
+        "channel_id_changed",
         "channel_rename",
         "pin_added",
         "pin_removed"
@@ -138,42 +159,42 @@ Use this Slack app manifest to create the app quickly (adjust the name/command i
 }
 ```
 
-If you enable native commands, add one `slash_commands` entry per command you want to expose (matching the `/help` list). Override with `slack.commands.native`.
+If you enable native commands, add one `slash_commands` entry per command you want to expose (matching the `/help` list). Override with `channels.slack.commands.native`.
 
 ## Scopes (current vs optional)
 Slack's Conversations API is type-scoped: you only need the scopes for the
 conversation types you actually touch (channels, groups, im, mpim). See
-https://api.slack.com/docs/conversations-api for the overview.
+https://api.channels.slack.com/docs/conversations-api for the overview.
 
 ### Required scopes
 - `chat:write` (send/update/delete messages via `chat.postMessage`)
-  https://api.slack.com/methods/chat.postMessage
+  https://api.channels.slack.com/methods/chat.postMessage
 - `im:write` (open DMs via `conversations.open` for user DMs)
-  https://api.slack.com/methods/conversations.open
+  https://api.channels.slack.com/methods/conversations.open
 - `channels:history`, `groups:history`, `im:history`, `mpim:history`
-  https://api.slack.com/methods/conversations.history
+  https://api.channels.slack.com/methods/conversations.history
 - `channels:read`, `groups:read`, `im:read`, `mpim:read`
-  https://api.slack.com/methods/conversations.info
+  https://api.channels.slack.com/methods/conversations.info
 - `users:read` (user lookup)
-  https://api.slack.com/methods/users.info
+  https://api.channels.slack.com/methods/users.info
 - `reactions:read`, `reactions:write` (`reactions.get` / `reactions.add`)
-  https://api.slack.com/methods/reactions.get
-  https://api.slack.com/methods/reactions.add
+  https://api.channels.slack.com/methods/reactions.get
+  https://api.channels.slack.com/methods/reactions.add
 - `pins:read`, `pins:write` (`pins.list` / `pins.add` / `pins.remove`)
-  https://api.slack.com/scopes/pins:read
-  https://api.slack.com/scopes/pins:write
+  https://api.channels.slack.com/scopes/pins:read
+  https://api.channels.slack.com/scopes/pins:write
 - `emoji:read` (`emoji.list`)
-  https://api.slack.com/scopes/emoji:read
+  https://api.channels.slack.com/scopes/emoji:read
 - `files:write` (uploads via `files.uploadV2`)
-  https://api.slack.com/messaging/files/uploading
+  https://api.channels.slack.com/messaging/files/uploading
 
 ### Not needed today (but likely future)
 - `mpim:write` (only if we add group-DM open/DM start via `conversations.open`)
 - `groups:write` (only if we add private-channel management: create/rename/invite/archive)
 - `chat:write.public` (only if we want to post to channels the bot isn't in)
-  https://api.slack.com/scopes/chat:write.public
+  https://api.channels.slack.com/scopes/chat:write.public
 - `users:read.email` (only if we need email fields from `users.info`)
-  https://api.slack.com/changelog/2017-04-narrowing-email-access
+  https://api.channels.slack.com/changelog/2017-04-narrowing-email-access
 - `files:read` (only if we start listing/reading file metadata)
 
 ## Config
@@ -234,11 +255,11 @@ Ack reactions are controlled globally via `messages.ackReaction` +
 ack reaction after the bot replies.
 
 ## Limits
-- Outbound text is chunked to `slack.textChunkLimit` (default 4000).
-- Media uploads are capped by `slack.mediaMaxMb` (default 20).
+- Outbound text is chunked to `channels.slack.textChunkLimit` (default 4000).
+- Media uploads are capped by `channels.slack.mediaMaxMb` (default 20).
 
 ## Reply threading
-By default, Clawdbot replies in the main channel. Use `slack.replyToMode` to control automatic threading:
+By default, Clawdbot replies in the main channel. Use `channels.slack.replyToMode` to control automatic threading:
 
 | Mode | Behavior |
 | --- | --- |
@@ -256,20 +277,20 @@ For fine-grained control, use these tags in agent responses:
 ## Sessions + routing
 - DMs share the `main` session (like WhatsApp/Telegram).
 - Channels map to `agent:<agentId>:slack:channel:<channelId>` sessions.
-- Slash commands use `agent:<agentId>:slack:slash:<userId>` sessions (prefix configurable via `slack.slashCommand.sessionPrefix`).
-- Native command registration uses `commands.native` (global default `"auto"` → Slack off) and can be overridden per-workspace with `slack.commands.native`. Text commands require standalone `/...` messages and can be disabled with `commands.text: false`. Slack slash commands are managed in the Slack app and are not removed automatically. Use `commands.useAccessGroups: false` to bypass access-group checks for commands.
+- Slash commands use `agent:<agentId>:slack:slash:<userId>` sessions (prefix configurable via `channels.slack.slashCommand.sessionPrefix`).
+- Native command registration uses `commands.native` (global default `"auto"` → Slack off) and can be overridden per-workspace with `channels.slack.commands.native`. Text commands require standalone `/...` messages and can be disabled with `commands.text: false`. Slack slash commands are managed in the Slack app and are not removed automatically. Use `commands.useAccessGroups: false` to bypass access-group checks for commands.
 - Full command list + config: [Slash commands](/tools/slash-commands)
 
 ## DM security (pairing)
-- Default: `slack.dm.policy="pairing"` — unknown DM senders get a pairing code (expires after 1 hour).
+- Default: `channels.slack.dm.policy="pairing"` — unknown DM senders get a pairing code (expires after 1 hour).
 - Approve via: `clawdbot pairing approve slack <code>`.
-- To allow anyone: set `slack.dm.policy="open"` and `slack.dm.allowFrom=["*"]`.
+- To allow anyone: set `channels.slack.dm.policy="open"` and `channels.slack.dm.allowFrom=["*"]`.
 
 ## Group policy
-- `slack.groupPolicy` controls channel handling (`open|disabled|allowlist`).
-- `allowlist` requires channels to be listed in `slack.channels`.
+- `channels.slack.groupPolicy` controls channel handling (`open|disabled|allowlist`).
+- `allowlist` requires channels to be listed in `channels.slack.channels`.
 
-Channel options (`slack.channels.<id>` or `slack.channels.<name>`):
+Channel options (`channels.slack.channels.<id>` or `channels.slack.channels.<name>`):
 - `allow`: allow/deny the channel when `groupPolicy="allowlist"`.
 - `requireMention`: mention gating for the channel.
 - `allowBots`: allow bot-authored messages in this channel (default: false).
@@ -284,7 +305,7 @@ Use these with cron/CLI sends:
 - `channel:<id>` for channels
 
 ## Tool actions
-Slack tool actions can be gated with `slack.actions.*`:
+Slack tool actions can be gated with `channels.slack.actions.*`:
 
 | Action group | Default | Notes |
 | --- | --- | --- |
@@ -295,10 +316,10 @@ Slack tool actions can be gated with `slack.actions.*`:
 | emojiList | enabled | Custom emoji list |
 
 ## Notes
-- Mention gating is controlled via `slack.channels` (set `requireMention` to `true`); `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`) also count as mentions.
+- Mention gating is controlled via `channels.slack.channels` (set `requireMention` to `true`); `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`) also count as mentions.
 - Multi-agent override: set per-agent patterns on `agents.list[].groupChat.mentionPatterns`.
-- Reaction notifications follow `slack.reactionNotifications` (use `reactionAllowlist` with mode `allowlist`).
-- Bot-authored messages are ignored by default; enable via `slack.allowBots` or `slack.channels.<id>.allowBots`.
-- Warning: If you allow replies to other bots (`slack.allowBots=true` or `slack.channels.<id>.allowBots=true`), prevent bot-to-bot reply loops with `requireMention`, `slack.channels.<id>.users` allowlists, and/or clear guardrails in `AGENTS.md` and `SOUL.md`.
+- Reaction notifications follow `channels.slack.reactionNotifications` (use `reactionAllowlist` with mode `allowlist`).
+- Bot-authored messages are ignored by default; enable via `channels.slack.allowBots` or `channels.slack.channels.<id>.allowBots`.
+- Warning: If you allow replies to other bots (`channels.slack.allowBots=true` or `channels.slack.channels.<id>.allowBots=true`), prevent bot-to-bot reply loops with `requireMention`, `channels.slack.channels.<id>.users` allowlists, and/or clear guardrails in `AGENTS.md` and `SOUL.md`.
 - For the Slack tool, reaction removal semantics are in [/tools/reactions](/tools/reactions).
 - Attachments are downloaded to the media store when permitted and under the size limit.

docs/channels/telegram.md

@@ -12,24 +12,26 @@ Status: production-ready for bot DMs + groups via grammY. Long-polling by defaul
 1) Create a bot with **@BotFather** and copy the token.
 2) Set the token:
    - Env: `TELEGRAM_BOT_TOKEN=...`
-   - Or config: `telegram.botToken: "..."`.
+   - Or config: `channels.telegram.botToken: "..."`.
 3) Start the gateway.
 4) DM access is pairing by default; approve the pairing code on first contact.
 
 Minimal config:
 ```json5
 {
-  telegram: {
-    enabled: true,
-    botToken: "123:abc",
-    dmPolicy: "pairing"
+  channels: {
+    telegram: {
+      enabled: true,
+      botToken: "123:abc",
+      dmPolicy: "pairing"
+    }
   }
 }
 ```
 
 ## What it is
-- A Telegram Bot API provider owned by the Gateway.
-- Deterministic routing: replies go back to Telegram; the model never chooses providers.
+- A Telegram Bot API channel owned by the Gateway.
+- Deterministic routing: replies go back to Telegram; the model never chooses channels.
 - DMs share the agent's main session; groups stay isolated (`agent:<agentId>:telegram:group:<chatId>`).
 
 ## Setup (fast path)
@@ -47,22 +49,24 @@ Example:
 
 ```json5
 {
-  telegram: {
-    enabled: true,
-    botToken: "123:abc",
-    dmPolicy: "pairing",
-    groups: { "*": { requireMention: true } }
+  channels: {
+    telegram: {
+      enabled: true,
+      botToken: "123:abc",
+      dmPolicy: "pairing",
+      groups: { "*": { requireMention: true } }
+    }
   }
 }
 ```
 
 Env option: `TELEGRAM_BOT_TOKEN=...` (works for the default account).
 
-Multi-account support: use `telegram.accounts` with per-account tokens and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern.
+Multi-account support: use `channels.telegram.accounts` with per-account tokens and optional `name`. See [`gateway/configuration`](/gateway/configuration#telegramaccounts--discordaccounts--slackaccounts--signalaccounts--imessageaccounts) for the shared pattern.
 
 3) Start the gateway. Telegram starts when a token is resolved (env or config).
 4) DM access defaults to pairing. Approve the code when the bot is first contacted.
-5) For groups: add the bot, decide privacy/admin behavior (below), then set `telegram.groups` to control mention gating + allowlists.
+5) For groups: add the bot, decide privacy/admin behavior (below), then set `channels.telegram.groups` to control mention gating + allowlists.
 
 ## Token + privacy + permissions (Telegram side)
 
@@ -84,11 +88,12 @@ Admin status is set inside the group (Telegram UI). Admin bots always receive al
 group messages, so use admin if you need full visibility.
 
 ## How it works (behavior)
-- Inbound messages are normalized into the shared provider envelope with reply context and media placeholders.
+- Inbound messages are normalized into the shared channel envelope with reply context and media placeholders.
 - Group replies require a mention by default (native @mention or `agents.list[].groupChat.mentionPatterns` / `messages.groupChat.mentionPatterns`).
 - Multi-agent override: set per-agent patterns on `agents.list[].groupChat.mentionPatterns`.
 - Replies always route back to the same Telegram chat.
 - Long-polling uses grammY runner with per-chat sequencing; overall concurrency is capped by `agents.defaults.maxConcurrent`.
+- Telegram Bot API does not support read receipts; there is no `sendReadReceipts` option.
 
 ## Formatting (Telegram HTML)
 - Outbound Telegram text uses `parse_mode: "HTML"` (Telegram’s supported tag subset).
@@ -97,9 +102,11 @@ group messages, so use admin if you need full visibility.
 - If Telegram rejects the HTML payload, Clawdbot retries the same message as plain text.
 
 ## Limits
-- Outbound text is chunked to `telegram.textChunkLimit` (default 4000).
-- Media downloads/uploads are capped by `telegram.mediaMaxMb` (default 5).
-- Group history context uses `telegram.historyLimit` (or `telegram.accounts.*.historyLimit`), falling back to `messages.groupChat.historyLimit`. Set `0` to disable (default 50).
+- Outbound text is chunked to `channels.telegram.textChunkLimit` (default 4000).
+- Media downloads/uploads are capped by `channels.telegram.mediaMaxMb` (default 5).
+- Telegram Bot API requests time out after `channels.telegram.timeoutSeconds` (default 500 via grammY). Set lower to avoid long hangs.
+- Group history context uses `channels.telegram.historyLimit` (or `channels.telegram.accounts.*.historyLimit`), falling back to `messages.groupChat.historyLimit`. Set `0` to disable (default 50).
+- DM history can be limited with `channels.telegram.dmHistoryLimit` (user turns). Per-user overrides: `channels.telegram.dms["<user_id>"].historyLimit`.
 
 ## Group activation modes
 
@@ -109,22 +116,26 @@ By default, the bot only responds to mentions in groups (`@botname` or patterns
 
 ```json5
 {
-  telegram: {
-    groups: {
-      "-1001234567890": { requireMention: false }  // always respond in this group
+  channels: {
+    telegram: {
+      groups: {
+        "-1001234567890": { requireMention: false }  // always respond in this group
+      }
     }
   }
 }
 ```
 
-**Important:** Setting `telegram.groups` creates an **allowlist** - only listed groups (or `"*"`) will be accepted.
+**Important:** Setting `channels.telegram.groups` creates an **allowlist** - only listed groups (or `"*"`) will be accepted.
 
 To allow all groups with always-respond:
 ```json5
 {
-  telegram: {
-    groups: {
-      "*": { requireMention: false }  // all groups, always respond
+  channels: {
+    telegram: {
+      groups: {
+        "*": { requireMention: false }  // all groups, always respond
+      }
     }
   }
 }
@@ -133,9 +144,11 @@ To allow all groups with always-respond:
 To keep mention-only for all groups (default behavior):
 ```json5
 {
-  telegram: {
-    groups: {
-      "*": { requireMention: true }  // or omit groups entirely
+  channels: {
+    telegram: {
+      groups: {
+        "*": { requireMention: true }  // or omit groups entirely
+      }
     }
   }
 }
@@ -155,56 +168,85 @@ Forward any message from the group to `@userinfobot` or `@getidsbot` on Telegram
 
 **Tip:** For your own user ID, DM the bot and it will reply with your user ID (pairing message), or use `/whoami` once commands are enabled.
 
-**Privacy note:** `@userinfobot` is a third-party bot. If you prefer, use gateway logs (`clawdbot logs`) or Telegram developer tools to find user/chat IDs.
+**Privacy note:** `@userinfobot` is a third-party bot. If you prefer, add the bot to the group, send a message, and use `clawdbot logs --follow` to read `chat.id`, or use the Bot API `getUpdates`.
+
+## Config writes
+By default, Telegram is allowed to write config updates triggered by channel events or `/config set|unset`.
+
+This happens when:
+- A group is upgraded to a supergroup and Telegram emits `migrate_to_chat_id` (chat ID changes). Clawdbot can migrate `channels.telegram.groups` automatically.
+- You run `/config set` or `/config unset` in a Telegram chat (requires `commands.config: true`).
+
+Disable with:
+```json5
+{
+  channels: { telegram: { configWrites: false } }
+}
+```
 
 ## Topics (forum supergroups)
 Telegram forum topics include a `message_thread_id` per message. Clawdbot:
 - Appends `:topic:<threadId>` to the Telegram group session key so each topic is isolated.
 - Sends typing indicators and replies with `message_thread_id` so responses stay in the topic.
 - Exposes `MessageThreadId` + `IsForum` in template context for routing/templating.
-- Topic-specific configuration is available under `telegram.groups.<chatId>.topics.<threadId>` (skills, allowlists, auto-reply, system prompts, disable).
+- Topic-specific configuration is available under `channels.telegram.groups.<chatId>.topics.<threadId>` (skills, allowlists, auto-reply, system prompts, disable).
 
 Private chats can include `message_thread_id` in some edge cases. Clawdbot keeps the DM session key unchanged, but still uses the thread id for replies/draft streaming when it is present.
 
 ## Access control (DMs + groups)
 
 ### DM access
-- Default: `telegram.dmPolicy = "pairing"`. Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
+- Default: `channels.telegram.dmPolicy = "pairing"`. Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
 - Approve via:
   - `clawdbot pairing list telegram`
   - `clawdbot pairing approve telegram <CODE>`
 - Pairing is the default token exchange used for Telegram DMs. Details: [Pairing](/start/pairing)
-- `telegram.allowFrom` accepts numeric user IDs (recommended) or `@username` entries. It is **not** the bot username; use the human sender’s ID (get it from `@userinfobot` or the `from.id` field in the gateway log).
+- `channels.telegram.allowFrom` accepts numeric user IDs (recommended) or `@username` entries. It is **not** the bot username; use the human sender’s ID.
+
+#### Finding your Telegram user ID
+Safer (no third-party bot):
+1) Start the gateway and DM your bot.
+2) Run `clawdbot logs --follow` and look for `from.id`.
+
+Alternate (official Bot API):
+1) DM your bot.
+2) Fetch updates with your bot token and read `message.from.id`:
+   ```bash
+   curl "https://api.telegram.org/bot<bot_token>/getUpdates"
+   ```
+
+Third-party (less private):
+- DM `@userinfobot` or `@getidsbot` and use the returned user id.
 
 ### Group access
 
 Two independent controls:
 
-**1. Which groups are allowed** (group allowlist via `telegram.groups`):
+**1. Which groups are allowed** (group allowlist via `channels.telegram.groups`):
 - No `groups` config = all groups allowed
 - With `groups` config = only listed groups or `"*"` are allowed
 - Example: `"groups": { "-1001234567890": {}, "*": {} }` allows all groups
 
-**2. Which senders are allowed** (sender filtering via `telegram.groupPolicy`):
+**2. Which senders are allowed** (sender filtering via `channels.telegram.groupPolicy`):
 - `"open"` = all senders in allowed groups can message
-- `"allowlist"` = only senders in `telegram.groupAllowFrom` can message
+- `"allowlist"` = only senders in `channels.telegram.groupAllowFrom` can message
 - `"disabled"` = no group messages accepted at all
 Default is `groupPolicy: "allowlist"` (blocked unless you add `groupAllowFrom`).
 
-Most users want: `groupPolicy: "allowlist"` + `groupAllowFrom` + specific groups listed in `telegram.groups`
+Most users want: `groupPolicy: "allowlist"` + `groupAllowFrom` + specific groups listed in `channels.telegram.groups`
 
 ## Long-polling vs webhook
 - Default: long-polling (no public URL required).
-- Webhook mode: set `telegram.webhookUrl` (optionally `telegram.webhookSecret` + `telegram.webhookPath`).
+- Webhook mode: set `channels.telegram.webhookUrl` (optionally `channels.telegram.webhookSecret` + `channels.telegram.webhookPath`).
   - The local listener binds to `0.0.0.0:8787` and serves `POST /telegram-webhook` by default.
-  - If your public URL is different, use a reverse proxy and point `telegram.webhookUrl` at the public endpoint.
+  - If your public URL is different, use a reverse proxy and point `channels.telegram.webhookUrl` at the public endpoint.
 
 ## Reply threading
 Telegram supports optional threaded replies via tags:
 - `[[reply_to_current]]` -- reply to the triggering message.
 - `[[reply_to:<id>]]` -- reply to a specific message id.
 
-Controlled by `telegram.replyToMode`:
+Controlled by `channels.telegram.replyToMode`:
 - `first` (default), `all`, `off`.
 
 ## Audio messages (voice vs file)
@@ -214,7 +256,7 @@ Clawdbot defaults to audio files for backward compatibility.
 To force a voice note bubble in agent replies, include this tag anywhere in the reply:
 - `[[audio_as_voice]]` — send audio as a voice note instead of a file.
 
-The tag is stripped from the delivered text. Other providers ignore this tag.
+The tag is stripped from the delivered text. Other channels ignore this tag.
 
 ## Streaming (drafts)
 Telegram can stream **draft bubbles** while the agent is generating a response.
@@ -227,93 +269,95 @@ Requirements (Telegram Bot API 9.3+):
 - Streaming is ignored for groups/supergroups/channels.
 
 Config:
-- `telegram.streamMode: "off" | "partial" | "block"` (default: `partial`)
+- `channels.telegram.streamMode: "off" | "partial" | "block"` (default: `partial`)
   - `partial`: update the draft bubble with the latest streaming text.
   - `block`: update the draft bubble in larger blocks (chunked).
   - `off`: disable draft streaming.
 - Optional (only for `streamMode: "block"`):
-  - `telegram.draftChunk: { minChars?, maxChars?, breakPreference? }`
-    - defaults: `minChars: 200`, `maxChars: 800`, `breakPreference: "paragraph"` (clamped to `telegram.textChunkLimit`).
+  - `channels.telegram.draftChunk: { minChars?, maxChars?, breakPreference? }`
+    - defaults: `minChars: 200`, `maxChars: 800`, `breakPreference: "paragraph"` (clamped to `channels.telegram.textChunkLimit`).
 
-Note: draft streaming is separate from **block streaming** (provider messages).
-Block streaming is off by default and requires `telegram.blockStreaming: true`
+Note: draft streaming is separate from **block streaming** (channel messages).
+Block streaming is off by default and requires `channels.telegram.blockStreaming: true`
 if you want early Telegram messages instead of draft updates.
 
 Reasoning stream (Telegram only):
 - `/reasoning stream` streams reasoning into the draft bubble while the reply is
   generating, then sends the final answer without reasoning.
-- If `telegram.streamMode` is `off`, reasoning stream is disabled.
+- If `channels.telegram.streamMode` is `off`, reasoning stream is disabled.
 More context: [Streaming + chunking](/concepts/streaming).
 
 ## Retry policy
-Outbound Telegram API calls retry on transient network/429 errors with exponential backoff and jitter. Configure via `telegram.retry`. See [Retry policy](/concepts/retry).
+Outbound Telegram API calls retry on transient network/429 errors with exponential backoff and jitter. Configure via `channels.telegram.retry`. See [Retry policy](/concepts/retry).
 
 ## Agent tool (messages + reactions)
 - Tool: `telegram` with `sendMessage` action (`to`, `content`, optional `mediaUrl`, `replyToMessageId`, `messageThreadId`).
 - Tool: `telegram` with `react` action (`chatId`, `messageId`, `emoji`).
+- Tool: `telegram` with `deleteMessage` action (`chatId`, `messageId`).
 - Reaction removal semantics: see [/tools/reactions](/tools/reactions).
-- Tool gating: `telegram.actions.reactions` and `telegram.actions.sendMessage` (default: enabled).
+- Tool gating: `channels.telegram.actions.reactions`, `channels.telegram.actions.sendMessage`, `channels.telegram.actions.deleteMessage` (default: enabled).
 
 ## Delivery targets (CLI/cron)
 - Use a chat id (`123456789`) or a username (`@name`) as the target.
-- Example: `clawdbot message send --provider telegram --to 123456789 --message "hi"`.
+- Example: `clawdbot message send --channel telegram --to 123456789 --message "hi"`.
 
 ## Troubleshooting
 
 **Bot doesn’t respond to non-mention messages in a group:**
-- If you set `telegram.groups.*.requireMention=false`, Telegram’s Bot API **privacy mode** must be disabled.
+- If you set `channels.telegram.groups.*.requireMention=false`, Telegram’s Bot API **privacy mode** must be disabled.
   - BotFather: `/setprivacy` → **Disable** (then remove + re-add the bot to the group)
-- `clawdbot providers status` shows a warning when config expects unmentioned group messages.
-- `clawdbot providers status --probe` can additionally check membership for explicit numeric group IDs (it can’t audit wildcard `"*"` rules).
+- `clawdbot channels status` shows a warning when config expects unmentioned group messages.
+- `clawdbot channels status --probe` can additionally check membership for explicit numeric group IDs (it can’t audit wildcard `"*"` rules).
 - Quick test: `/activation always` (session-only; use config for persistence)
 
 **Bot not seeing group messages at all:**
-- If `telegram.groups` is set, the group must be listed or use `"*"`
+- If `channels.telegram.groups` is set, the group must be listed or use `"*"`
 - Check Privacy Settings in @BotFather → "Group Privacy" should be **OFF**
 - Verify bot is actually a member (not just an admin with no read access)
 - Check gateway logs: `clawdbot logs --follow` (look for "skipping group message")
 
 **Bot responds to mentions but not `/activation always`:**
 - The `/activation` command updates session state but doesn't persist to config
-- For persistent behavior, add group to `telegram.groups` with `requireMention: false`
+- For persistent behavior, add group to `channels.telegram.groups` with `requireMention: false`
 
 **Commands like `/status` don't work:**
-- Make sure your Telegram user ID is authorized (via pairing or `telegram.allowFrom`)
+- Make sure your Telegram user ID is authorized (via pairing or `channels.telegram.allowFrom`)
 - Commands require authorization even in groups with `groupPolicy: "open"`
 
 ## Configuration reference (Telegram)
 Full configuration: [Configuration](/gateway/configuration)
 
 Provider options:
-- `telegram.enabled`: enable/disable provider startup.
-- `telegram.botToken`: bot token (BotFather).
-- `telegram.tokenFile`: read token from file path.
-- `telegram.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).
-- `telegram.allowFrom`: DM allowlist (ids/usernames). `open` requires `"*"`.
-- `telegram.groupPolicy`: `open | allowlist | disabled` (default: allowlist).
-- `telegram.groupAllowFrom`: group sender allowlist (ids/usernames).
-- `telegram.groups`: per-group defaults + allowlist (use `"*"` for global defaults).
-  - `telegram.groups.<id>.requireMention`: mention gating default.
-  - `telegram.groups.<id>.skills`: skill filter (omit = all skills, empty = none).
-  - `telegram.groups.<id>.allowFrom`: per-group sender allowlist override.
-  - `telegram.groups.<id>.systemPrompt`: extra system prompt for the group.
-  - `telegram.groups.<id>.enabled`: disable the group when `false`.
-  - `telegram.groups.<id>.topics.<threadId>.*`: per-topic overrides (same fields as group).
-  - `telegram.groups.<id>.topics.<threadId>.requireMention`: per-topic mention gating override.
-- `telegram.replyToMode`: `off | first | all` (default: `first`).
-- `telegram.textChunkLimit`: outbound chunk size (chars).
-- `telegram.streamMode`: `off | partial | block` (draft streaming).
-- `telegram.mediaMaxMb`: inbound/outbound media cap (MB).
-- `telegram.retry`: retry policy for outbound Telegram API calls (attempts, minDelayMs, maxDelayMs, jitter).
-- `telegram.proxy`: proxy URL for Bot API calls (SOCKS/HTTP).
-- `telegram.webhookUrl`: enable webhook mode.
-- `telegram.webhookSecret`: webhook secret (optional).
-- `telegram.webhookPath`: local webhook path (default `/telegram-webhook`).
-- `telegram.actions.reactions`: gate Telegram tool reactions.
-- `telegram.actions.sendMessage`: gate Telegram tool message sends.
+- `channels.telegram.enabled`: enable/disable channel startup.
+- `channels.telegram.botToken`: bot token (BotFather).
+- `channels.telegram.tokenFile`: read token from file path.
+- `channels.telegram.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).
+- `channels.telegram.allowFrom`: DM allowlist (ids/usernames). `open` requires `"*"`.
+- `channels.telegram.groupPolicy`: `open | allowlist | disabled` (default: allowlist).
+- `channels.telegram.groupAllowFrom`: group sender allowlist (ids/usernames).
+- `channels.telegram.groups`: per-group defaults + allowlist (use `"*"` for global defaults).
+  - `channels.telegram.groups.<id>.requireMention`: mention gating default.
+  - `channels.telegram.groups.<id>.skills`: skill filter (omit = all skills, empty = none).
+  - `channels.telegram.groups.<id>.allowFrom`: per-group sender allowlist override.
+  - `channels.telegram.groups.<id>.systemPrompt`: extra system prompt for the group.
+  - `channels.telegram.groups.<id>.enabled`: disable the group when `false`.
+  - `channels.telegram.groups.<id>.topics.<threadId>.*`: per-topic overrides (same fields as group).
+  - `channels.telegram.groups.<id>.topics.<threadId>.requireMention`: per-topic mention gating override.
+- `channels.telegram.replyToMode`: `off | first | all` (default: `first`).
+- `channels.telegram.textChunkLimit`: outbound chunk size (chars).
+- `channels.telegram.streamMode`: `off | partial | block` (draft streaming).
+- `channels.telegram.mediaMaxMb`: inbound/outbound media cap (MB).
+- `channels.telegram.retry`: retry policy for outbound Telegram API calls (attempts, minDelayMs, maxDelayMs, jitter).
+- `channels.telegram.proxy`: proxy URL for Bot API calls (SOCKS/HTTP).
+- `channels.telegram.webhookUrl`: enable webhook mode.
+- `channels.telegram.webhookSecret`: webhook secret (optional).
+- `channels.telegram.webhookPath`: local webhook path (default `/telegram-webhook`).
+- `channels.telegram.actions.reactions`: gate Telegram tool reactions.
+- `channels.telegram.actions.sendMessage`: gate Telegram tool message sends.
+- `channels.telegram.actions.deleteMessage`: gate Telegram tool message deletes.
 
 Related global options:
 - `agents.list[].groupChat.mentionPatterns` (mention gating patterns).
 - `messages.groupChat.mentionPatterns` (global fallback).
-- `commands.native` (defaults to `"auto"` → on for Telegram/Discord, off for Slack), `commands.text`, `commands.useAccessGroups` (command behavior). Override with `telegram.commands.native`.
+- `commands.native` (defaults to `"auto"` → on for Telegram/Discord, off for Slack), `commands.text`, `commands.useAccessGroups` (command behavior). Override with `channels.telegram.commands.native`.
 - `messages.responsePrefix`, `messages.ackReaction`, `messages.ackReactionScope`, `messages.removeAckAfterReply`.

docs/channels/troubleshooting.md

@@ -0,0 +1,21 @@
+---
+summary: "Channel-specific troubleshooting shortcuts (Discord/Telegram/WhatsApp)"
+read_when:
+  - A channel connects but messages don’t flow
+  - Investigating channel misconfiguration (intents, permissions, privacy mode)
+---
+# Channel troubleshooting
+
+Start with:
+
+```bash
+clawdbot doctor
+clawdbot channels status --probe
+```
+
+`channels status --probe` prints warnings when it can detect common channel misconfigurations, and includes small live checks (credentials, some permissions/membership).
+
+## Channels
+- Discord: [/channels/discord#troubleshooting](/channels/discord#troubleshooting)
+- Telegram: [/channels/telegram#troubleshooting](/channels/telegram#troubleshooting)
+- WhatsApp: [/channels/whatsapp#troubleshooting-quick](/channels/whatsapp#troubleshooting-quick)

docs/channels/whatsapp.md

@@ -1,9 +1,9 @@
 ---
-summary: "WhatsApp (web provider) integration: login, inbox, replies, media, and ops"
+summary: "WhatsApp (web channel) integration: login, inbox, replies, media, and ops"
 read_when:
-  - Working on WhatsApp/web provider behavior or inbox routing
+  - Working on WhatsApp/web channel behavior or inbox routing
 ---
-# WhatsApp (web provider)
+# WhatsApp (web channel)
 
 
 Status: WhatsApp Web via Baileys only. Gateway owns the session(s).
@@ -11,15 +11,17 @@ Status: WhatsApp Web via Baileys only. Gateway owns the session(s).
 ## Quick setup (beginner)
 1) Use a **separate phone number** if possible (recommended).
 2) Configure WhatsApp in `~/.clawdbot/clawdbot.json`.
-3) Run `clawdbot providers login` to scan the QR code (Linked Devices).
+3) Run `clawdbot channels login` to scan the QR code (Linked Devices).
 4) Start the gateway.
 
 Minimal config:
 ```json5
 {
-  whatsapp: {
-    dmPolicy: "allowlist",
-    allowFrom: ["+15551234567"]
+  channels: {
+    whatsapp: {
+      dmPolicy: "allowlist",
+      allowFrom: ["+15551234567"]
+    }
   }
 }
 ```
@@ -29,6 +31,16 @@ Minimal config:
 - Deterministic routing: replies return to WhatsApp, no model routing.
 - Model sees enough context to understand quoted replies.
 
+## Config writes
+By default, WhatsApp is allowed to write config updates triggered by `/config set|unset` (requires `commands.config: true`).
+
+Disable with:
+```json5
+{
+  channels: { whatsapp: { configWrites: false } }
+}
+```
+
 ## Architecture (who owns what)
 - **Gateway** owns the Baileys socket and inbox loop.
 - **CLI / macOS app** talk to the gateway; no direct Baileys use.
@@ -44,17 +56,19 @@ Use a **separate phone number** for Clawdbot. Best UX, clean routing, no self-ch
 **WhatsApp Business:** You can use WhatsApp Business on the same device with a different number. Great for keeping your personal WhatsApp separate — install WhatsApp Business and register the Clawdbot number there.
 
 **Sample config (dedicated number, single-user allowlist):**
-```json
+```json5
 {
-  "whatsapp": {
-    "dmPolicy": "allowlist",
-    "allowFrom": ["+15551234567"]
+  channels: {
+    whatsapp: {
+      dmPolicy: "allowlist",
+      allowFrom: ["+15551234567"]
+    }
   }
 }
 ```
 
 **Pairing mode (optional):**
-If you want pairing instead of allowlist, set `whatsapp.dmPolicy` to `pairing`. Unknown senders get a pairing code; approve with:
+If you want pairing instead of allowlist, set `channels.whatsapp.dmPolicy` to `pairing`. Unknown senders get a pairing code; approve with:
 `clawdbot pairing approve whatsapp <code>`
 
 ### Personal number (fallback)
@@ -96,13 +110,13 @@ on outbound replies.
 - Result: unreliable delivery and frequent blocks, so support was removed.
 
 ## Login + credentials
-- Login command: `clawdbot providers login` (QR via Linked Devices).
-- Multi-account login: `clawdbot providers login --account <id>` (`<id>` = `accountId`).
+- Login command: `clawdbot channels login` (QR via Linked Devices).
+- Multi-account login: `clawdbot channels login --account <id>` (`<id>` = `accountId`).
 - Default account (when `--account` is omitted): `default` if present, otherwise the first configured account id (sorted).
 - Credentials stored in `~/.clawdbot/credentials/whatsapp/<accountId>/creds.json`.
 - Backup copy at `creds.json.bak` (restored on corruption).
 - Legacy compatibility: older installs stored Baileys files directly in `~/.clawdbot/credentials/`.
-- Logout: `clawdbot providers logout` (or `--account <id>`) deletes WhatsApp auth state (but keeps shared `oauth.json`).
+- Logout: `clawdbot channels logout` (or `--account <id>`) deletes WhatsApp auth state (but keeps shared `oauth.json`).
 - Logged-out socket => error instructs re-link.
 
 ## Inbound flow (DM + group)
@@ -110,20 +124,46 @@ on outbound replies.
 - Inbox listeners are detached on shutdown to avoid accumulating event handlers in tests/restarts.
 - Status/broadcast chats are ignored.
 - Direct chats use E.164; groups use group JID.
-- **DM policy**: `whatsapp.dmPolicy` controls direct chat access (default: `pairing`).
+- **DM policy**: `channels.whatsapp.dmPolicy` controls direct chat access (default: `pairing`).
   - Pairing: unknown senders get a pairing code (approve via `clawdbot pairing approve whatsapp <code>`; codes expire after 1 hour).
-  - Open: requires `whatsapp.allowFrom` to include `"*"`.
-  - Self messages are always allowed; “self-chat mode” still requires `whatsapp.allowFrom` to include your own number.
+  - Open: requires `channels.whatsapp.allowFrom` to include `"*"`.
+  - Self messages are always allowed; “self-chat mode” still requires `channels.whatsapp.allowFrom` to include your own number.
 
 ### Personal-number mode (fallback)
-If you run Clawdbot on your **personal WhatsApp number**, enable `whatsapp.selfChatMode` (see sample above).
+If you run Clawdbot on your **personal WhatsApp number**, enable `channels.whatsapp.selfChatMode` (see sample above).
 
 Behavior:
 - Outbound DMs never trigger pairing replies (prevents spamming contacts).
-- Inbound unknown senders still follow `whatsapp.dmPolicy`.
+- Inbound unknown senders still follow `channels.whatsapp.dmPolicy`.
 - Self-chat mode (allowFrom includes your number) avoids auto read receipts and ignores mention JIDs.
 - Read receipts sent for non-self-chat DMs.
 
+## Read receipts
+By default, the gateway marks inbound WhatsApp messages as read (blue ticks) once they are accepted.
+
+Disable globally:
+```json5
+{
+  channels: { whatsapp: { sendReadReceipts: false } }
+}
+```
+
+Disable per account:
+```json5
+{
+  channels: {
+    whatsapp: {
+      accounts: {
+        personal: { sendReadReceipts: false }
+      }
+    }
+  }
+}
+```
+
+Notes:
+- Self-chat mode always skips read receipts.
+
 ## WhatsApp FAQ: sending messages + pairing
 
 **Will Clawdbot message random contacts when I link WhatsApp?**  
@@ -133,13 +173,13 @@ No. Default DM policy is **pairing**, so unknown senders only get a pairing code
 Pairing is a DM gate for unknown senders:
 - First DM from a new sender returns a short code (message is not processed).
 - Approve with: `clawdbot pairing approve whatsapp <code>` (list with `clawdbot pairing list whatsapp`).
-- Codes expire after 1 hour; pending requests are capped at 3 per provider.
+- Codes expire after 1 hour; pending requests are capped at 3 per channel.
 
 **Can multiple people use different Clawdbots on one WhatsApp number?**  
 Yes, by routing each sender to a different agent via `bindings` (peer `kind: "dm"`, sender E.164 like `+15551234567`). Replies still come from the **same WhatsApp account**, and direct chats collapse to each agent’s main session, so use **one agent per person**. DM access control (`dmPolicy`/`allowFrom`) is global per WhatsApp account. See [Multi-Agent Routing](/concepts/multi-agent).
 
 **Why do you ask for my phone number in the wizard?**  
-The wizard uses it to set your **allowlist/owner** so your own DMs are permitted. It’s not used for auto-sending. If you run on your personal WhatsApp number, use that same number and enable `whatsapp.selfChatMode`.
+The wizard uses it to set your **allowlist/owner** so your own DMs are permitted. It’s not used for auto-sending. If you run on your personal WhatsApp number, use that same number and enable `channels.whatsapp.selfChatMode`.
 
 ## Message normalization (what the model sees)
 - `Body` is the current message body with envelope.
@@ -158,12 +198,12 @@ The wizard uses it to set your **allowlist/owner** so your own DMs are permitted
 
 ## Groups
 - Groups map to `agent:<agentId>:whatsapp:group:<jid>` sessions.
-- Group policy: `whatsapp.groupPolicy = open|disabled|allowlist` (default `allowlist`).
+- Group policy: `channels.whatsapp.groupPolicy = open|disabled|allowlist` (default `allowlist`).
 - Activation modes:
   - `mention` (default): requires @mention or regex match.
   - `always`: always triggers.
 - `/activation mention|always` is owner-only and must be sent as a standalone message.
-- Owner = `whatsapp.allowFrom` (or self E.164 if unset).
+- Owner = `channels.whatsapp.allowFrom` (or self E.164 if unset).
 - **History injection**:
   - Recent messages (default 50) inserted under:
     `[Chat messages since your last reply - for context]`
@@ -174,7 +214,7 @@ The wizard uses it to set your **allowlist/owner** so your own DMs are permitted
 
 ## Reply delivery (threading)
 - WhatsApp Web sends standard messages (no quoted reply threading in the current gateway).
-- Reply tags are ignored on this provider.
+- Reply tags are ignored on this channel.
 
 ## Acknowledgment reactions (auto-react on receipt)
 
@@ -223,22 +263,22 @@ WhatsApp can automatically send emoji reactions to incoming messages immediately
 - In groups with `requireMention: false` (activation: always), `group: "mentions"` will react to all messages (not just @mentions).
 - Fire-and-forget: reaction failures are logged but don't prevent the bot from replying.
 - Participant JID is automatically included for group reactions.
-- WhatsApp ignores `messages.ackReaction`; use `whatsapp.ackReaction` instead.
+- WhatsApp ignores `messages.ackReaction`; use `channels.whatsapp.ackReaction` instead.
 
 ## Agent tool (reactions)
 - Tool: `whatsapp` with `react` action (`chatJid`, `messageId`, `emoji`, optional `remove`).
 - Optional: `participant` (group sender), `fromMe` (reacting to your own message), `accountId` (multi-account).
 - Reaction removal semantics: see [/tools/reactions](/tools/reactions).
-- Tool gating: `whatsapp.actions.reactions` (default: enabled).
+- Tool gating: `channels.whatsapp.actions.reactions` (default: enabled).
 
 ## Limits
-- Outbound text is chunked to `whatsapp.textChunkLimit` (default 4000).
-- Inbound media saves are capped by `whatsapp.mediaMaxMb` (default 50 MB).
+- Outbound text is chunked to `channels.whatsapp.textChunkLimit` (default 4000).
+- Inbound media saves are capped by `channels.whatsapp.mediaMaxMb` (default 50 MB).
 - Outbound media items are capped by `agents.defaults.mediaMaxMb` (default 5 MB).
 
 ## Outbound send (text + media)
 - Uses active web listener; error if gateway not running.
-- Text chunking: 4k max per message (configurable via `whatsapp.textChunkLimit`).
+- Text chunking: 4k max per message (configurable via `channels.whatsapp.textChunkLimit`).
 - Media:
   - Image/video/audio/document supported.
   - Audio sent as PTT; `audio/ogg` => `audio/ogg; codecs=opus`.
@@ -258,7 +298,7 @@ WhatsApp can automatically send emoji reactions to incoming messages immediately
 - **Gateway heartbeat** logs connection health (`web.heartbeatSeconds`, default 60s).
 - **Agent heartbeat** is global (`agents.defaults.heartbeat.*`) and runs in the main session.
   - Uses the configured heartbeat prompt (default: `Read HEARTBEAT.md if exists. Consider outstanding tasks. Checkup sometimes on your human during (user local) day time.`) + `HEARTBEAT_OK` skip behavior.
-  - Delivery defaults to the last used provider (or configured target).
+  - Delivery defaults to the last used channel (or configured target).
 
 ## Reconnect behavior
 - Backoff policy: `web.reconnect`:
@@ -267,22 +307,23 @@ WhatsApp can automatically send emoji reactions to incoming messages immediately
 - Logged-out => stop and require re-link.
 
 ## Config quick map
-- `whatsapp.dmPolicy` (DM policy: pairing/allowlist/open/disabled).
-- `whatsapp.selfChatMode` (same-phone setup; bot uses your personal WhatsApp number).
-- `whatsapp.allowFrom` (DM allowlist).
-- `whatsapp.mediaMaxMb` (inbound media save cap).
-- `whatsapp.ackReaction` (auto-reaction on message receipt: `{emoji, direct, group}`).
-- `whatsapp.accounts.<accountId>.*` (per-account settings + optional `authDir`).
-- `whatsapp.accounts.<accountId>.mediaMaxMb` (per-account inbound media cap).
-- `whatsapp.accounts.<accountId>.ackReaction` (per-account ack reaction override).
-- `whatsapp.groupAllowFrom` (group sender allowlist).
-- `whatsapp.groupPolicy` (group policy).
-- `whatsapp.historyLimit` / `whatsapp.accounts.<accountId>.historyLimit` (group history context; `0` disables).
-- `whatsapp.groups` (group allowlist + mention gating defaults; use `"*"` to allow all)
-- `whatsapp.actions.reactions` (gate WhatsApp tool reactions).
+- `channels.whatsapp.dmPolicy` (DM policy: pairing/allowlist/open/disabled).
+- `channels.whatsapp.selfChatMode` (same-phone setup; bot uses your personal WhatsApp number).
+- `channels.whatsapp.allowFrom` (DM allowlist).
+- `channels.whatsapp.mediaMaxMb` (inbound media save cap).
+- `channels.whatsapp.ackReaction` (auto-reaction on message receipt: `{emoji, direct, group}`).
+- `channels.whatsapp.accounts.<accountId>.*` (per-account settings + optional `authDir`).
+- `channels.whatsapp.accounts.<accountId>.mediaMaxMb` (per-account inbound media cap).
+- `channels.whatsapp.accounts.<accountId>.ackReaction` (per-account ack reaction override).
+- `channels.whatsapp.groupAllowFrom` (group sender allowlist).
+- `channels.whatsapp.groupPolicy` (group policy).
+- `channels.whatsapp.historyLimit` / `channels.whatsapp.accounts.<accountId>.historyLimit` (group history context; `0` disables).
+- `channels.whatsapp.dmHistoryLimit` (DM history limit in user turns). Per-user overrides: `channels.whatsapp.dms["<phone>"].historyLimit`.
+- `channels.whatsapp.groups` (group allowlist + mention gating defaults; use `"*"` to allow all)
+- `channels.whatsapp.actions.reactions` (gate WhatsApp tool reactions).
 - `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`)
 - `messages.groupChat.historyLimit`
-- `whatsapp.messagePrefix` (inbound prefix; per-account: `whatsapp.accounts.<accountId>.messagePrefix`; deprecated: `messages.messagePrefix`)
+- `channels.whatsapp.messagePrefix` (inbound prefix; per-account: `channels.whatsapp.accounts.<accountId>.messagePrefix`; deprecated: `messages.messagePrefix`)
 - `messages.responsePrefix` (outbound prefix)
 - `agents.defaults.mediaMaxMb`
 - `agents.defaults.heartbeat.every`
@@ -290,7 +331,7 @@ WhatsApp can automatically send emoji reactions to incoming messages immediately
 - `agents.defaults.heartbeat.target`
 - `agents.defaults.heartbeat.to`
 - `session.*` (scope, idle, store, mainKey)
-- `web.enabled` (disable provider startup when false)
+- `web.enabled` (disable channel startup when false)
 - `web.heartbeatSeconds`
 - `web.reconnect.*`
 
@@ -302,12 +343,13 @@ WhatsApp can automatically send emoji reactions to incoming messages immediately
 ## Troubleshooting (quick)
 
 **Not linked / QR login required**
-- Symptom: `providers status` shows `linked: false` or warns “Not linked”.
-- Fix: run `clawdbot providers login` on the gateway host and scan the QR (WhatsApp → Settings → Linked Devices).
+- Symptom: `channels status` shows `linked: false` or warns “Not linked”.
+- Fix: run `clawdbot channels login` on the gateway host and scan the QR (WhatsApp → Settings → Linked Devices).
 
 **Linked but disconnected / reconnect loop**
-- Symptom: `providers status` shows `running, disconnected` or warns “Linked but disconnected”.
-- Fix: `clawdbot doctor` (or restart the gateway). If it persists, relink via `providers login` and inspect `clawdbot logs --follow`.
+- Symptom: `channels status` shows `running, disconnected` or warns “Linked but disconnected”.
+- Fix: `clawdbot doctor` (or restart the gateway). If it persists, relink via `channels login` and inspect `clawdbot logs --follow`.
 
 **Bun runtime**
-- WhatsApp uses Baileys; run the gateway with **Node** for WhatsApp. (See Getting Started runtime note.)
+- Bun is **not recommended**. WhatsApp (Baileys) and Telegram are unreliable on Bun.
+  Run the gateway with **Node**. (See Getting Started runtime note.)

docs/channels/zalo.md

@@ -0,0 +1,165 @@
+---
+summary: "Zalo bot support status, capabilities, and configuration"
+read_when:
+  - Working on Zalo features or webhooks
+---
+# Zalo (Bot API)
+
+Status: experimental. Direct messages only; groups coming soon per Zalo docs.
+
+## Plugin required
+Zalo ships as a plugin and is not bundled with the core install.
+- Install via CLI: `clawdbot plugins install @clawdbot/zalo`
+- Or select **Zalo** during onboarding and confirm the install prompt
+- Details: [Plugins](/plugin)
+
+## Quick setup (beginner)
+1) Install the Zalo plugin:
+   - From a source checkout: `clawdbot plugins install ./extensions/zalo`
+   - From npm (if published): `clawdbot plugins install @clawdbot/zalo`
+   - Or pick **Zalo** in onboarding and confirm the install prompt
+2) Set the token:
+   - Env: `ZALO_BOT_TOKEN=...`
+   - Or config: `channels.zalo.botToken: "..."`.
+3) Restart the gateway (or finish onboarding).
+4) DM access is pairing by default; approve the pairing code on first contact.
+
+Minimal config:
+```json5
+{
+  channels: {
+    zalo: {
+      enabled: true,
+      botToken: "12345689:abc-xyz",
+      dmPolicy: "pairing"
+    }
+  }
+}
+```
+
+## What it is
+- A Zalo Bot API channel owned by the Gateway.
+- Deterministic routing: replies go back to Zalo; the model never chooses channels.
+- DMs share the agent's main session.
+- Groups are not yet supported (Zalo docs state "coming soon").
+
+## Setup (fast path)
+
+### 1) Create a bot token (Zalo Bot Platform)
+1) Go to **https://bot.zaloplatforms.com** and sign in.
+2) Create a new bot and configure its settings.
+3) Copy the bot token (format: `12345689:abc-xyz`).
+
+### 2) Configure the token (env or config)
+Example:
+
+```json5
+{
+  channels: {
+    zalo: {
+      enabled: true,
+      botToken: "12345689:abc-xyz",
+      dmPolicy: "pairing"
+    }
+  }
+}
+```
+
+Env option: `ZALO_BOT_TOKEN=...` (works for the default account only).
+
+Multi-account support: use `channels.zalo.accounts` with per-account tokens and optional `name`.
+
+3) Restart the gateway. Zalo starts when a token is resolved (env or config).
+4) DM access defaults to pairing. Approve the code when the bot is first contacted.
+
+## How it works (behavior)
+- Inbound messages are normalized into the shared channel envelope with media placeholders.
+- Replies always route back to the same Zalo chat.
+- Long-polling by default; webhook mode available with `channels.zalo.webhookUrl`.
+
+## Limits
+- Outbound text is chunked to 2000 characters (Zalo API limit).
+- Media downloads/uploads are capped by `channels.zalo.mediaMaxMb` (default 5).
+- Streaming is blocked by default due to the 2000 char limit making streaming less useful.
+
+## Access control (DMs)
+
+### DM access
+- Default: `channels.zalo.dmPolicy = "pairing"`. Unknown senders receive a pairing code; messages are ignored until approved (codes expire after 1 hour).
+- Approve via:
+  - `clawdbot pairing list zalo`
+  - `clawdbot pairing approve zalo <CODE>`
+- Pairing is the default token exchange. Details: [Pairing](/start/pairing)
+- `channels.zalo.allowFrom` accepts numeric user IDs.
+
+## Long-polling vs webhook
+- Default: long-polling (no public URL required).
+- Webhook mode: set `channels.zalo.webhookUrl` and `channels.zalo.webhookSecret`.
+  - The webhook secret must be 8-256 characters.
+  - Webhook URL must use HTTPS.
+  - Zalo sends events with `X-Bot-Api-Secret-Token` header for verification.
+  - Gateway HTTP handles webhook requests at `channels.zalo.webhookPath` (defaults to the webhook URL path).
+
+**Note:** getUpdates (polling) and webhook are mutually exclusive per Zalo API docs.
+
+## Supported message types
+- **Text messages**: Full support with 2000 character chunking.
+- **Image messages**: Download and process inbound images; send images via `sendPhoto`.
+- **Stickers**: Logged but not fully processed (no agent response).
+- **Unsupported types**: Logged (e.g., messages from protected users).
+
+## Capabilities
+| Feature | Status |
+|---------|--------|
+| Direct messages | ✅ Supported |
+| Groups | ❌ Coming soon (per Zalo docs) |
+| Media (images) | ✅ Supported |
+| Reactions | ❌ Not supported |
+| Threads | ❌ Not supported |
+| Polls | ❌ Not supported |
+| Native commands | ❌ Not supported |
+| Streaming | ⚠️ Blocked (2000 char limit) |
+
+## Delivery targets (CLI/cron)
+- Use a chat id as the target.
+- Example: `clawdbot message send --channel zalo --to 123456789 --message "hi"`.
+
+## Troubleshooting
+
+**Bot doesn't respond:**
+- Check that the token is valid: `clawdbot channels status --probe`
+- Verify the sender is approved (pairing or allowFrom)
+- Check gateway logs: `clawdbot logs --follow`
+
+**Webhook not receiving events:**
+- Ensure webhook URL uses HTTPS
+- Verify secret token is 8-256 characters
+- Confirm the gateway HTTP endpoint is reachable on the configured path
+- Check that getUpdates polling is not running (they're mutually exclusive)
+
+## Configuration reference (Zalo)
+Full configuration: [Configuration](/gateway/configuration)
+
+Provider options:
+- `channels.zalo.enabled`: enable/disable channel startup.
+- `channels.zalo.botToken`: bot token from Zalo Bot Platform.
+- `channels.zalo.tokenFile`: read token from file path.
+- `channels.zalo.dmPolicy`: `pairing | allowlist | open | disabled` (default: pairing).
+- `channels.zalo.allowFrom`: DM allowlist (user IDs). `open` requires `"*"`.
+- `channels.zalo.mediaMaxMb`: inbound/outbound media cap (MB, default 5).
+- `channels.zalo.webhookUrl`: enable webhook mode (HTTPS required).
+- `channels.zalo.webhookSecret`: webhook secret (8-256 chars).
+- `channels.zalo.webhookPath`: webhook path on the gateway HTTP server.
+- `channels.zalo.proxy`: proxy URL for API requests.
+
+Multi-account options:
+- `channels.zalo.accounts.<id>.botToken`: per-account token.
+- `channels.zalo.accounts.<id>.tokenFile`: per-account token file.
+- `channels.zalo.accounts.<id>.name`: display name.
+- `channels.zalo.accounts.<id>.enabled`: enable/disable account.
+- `channels.zalo.accounts.<id>.dmPolicy`: per-account DM policy.
+- `channels.zalo.accounts.<id>.allowFrom`: per-account allowlist.
+- `channels.zalo.accounts.<id>.webhookUrl`: per-account webhook URL.
+- `channels.zalo.accounts.<id>.webhookSecret`: per-account webhook secret.
+- `channels.zalo.accounts.<id>.webhookPath`: per-account webhook path.
+- `channels.zalo.accounts.<id>.proxy`: per-account proxy URL.

docs/cli/agent.md

@@ -0,0 +1,20 @@
+---
+summary: "CLI reference for `clawdbot agent` (send one agent turn via the Gateway)"
+read_when:
+  - You want to run one agent turn from scripts (optionally deliver reply)
+---
+
+# `clawdbot agent`
+
+Run an agent turn via the Gateway (use `--local` for embedded).
+
+Related:
+- Agent send tool: [Agent send](/tools/agent-send)
+
+## Examples
+
+```bash
+clawdbot agent --to +15555550123 --message "status update" --deliver
+clawdbot agent --session-id 1234 --message "Summarize inbox" --thinking medium
+```
+

docs/cli/agents.md

@@ -0,0 +1,22 @@
+---
+summary: "CLI reference for `clawdbot agents` (list/add/delete isolated agents)"
+read_when:
+  - You want multiple isolated agents (workspaces + routing + auth)
+---
+
+# `clawdbot agents`
+
+Manage isolated agents (workspaces + auth + routing).
+
+Related:
+- Multi-agent routing: [Multi-Agent Routing](/concepts/multi-agent)
+- Agent workspace: [Agent workspace](/concepts/agent-workspace)
+
+## Examples
+
+```bash
+clawdbot agents list
+clawdbot agents add work --workspace ~/clawd-work
+clawdbot agents delete work
+```
+

docs/cli/browser.md

@@ -0,0 +1,106 @@
+---
+summary: "CLI reference for `clawdbot browser` (profiles, tabs, actions, extension relay, remote serve)"
+read_when:
+  - You use `clawdbot browser` and want examples for common tasks
+  - You want to control a remote browser via `browser.controlUrl`
+  - You want to use the Chrome extension relay (attach/detach via toolbar button)
+---
+
+# `clawdbot browser`
+
+Manage Clawdbot’s browser control server and run browser actions (tabs, snapshots, screenshots, navigation, clicks, typing).
+
+Related:
+- Browser tool + API: [Browser tool](/tools/browser)
+- Chrome extension relay: [Chrome extension](/tools/chrome-extension)
+
+## Common flags
+
+- `--url <controlUrl>`: override `browser.controlUrl` for this command invocation.
+- `--browser-profile <name>`: choose a browser profile (default comes from config).
+- `--json`: machine-readable output (where supported).
+
+## Quick start (local)
+
+```bash
+clawdbot browser status
+clawdbot browser start
+clawdbot browser tabs
+clawdbot browser open https://example.com
+clawdbot browser snapshot
+```
+
+## Profiles
+
+Profiles are named browser instances with their own data directory and CDP settings.
+
+```bash
+clawdbot browser profiles
+clawdbot browser create-profile --name work --color "#FF5A36"
+clawdbot browser delete-profile --name work
+```
+
+Use a specific profile:
+
+```bash
+clawdbot browser --browser-profile work tabs
+```
+
+## Tabs
+
+```bash
+clawdbot browser tabs
+clawdbot browser open https://docs.clawd.bot
+clawdbot browser focus <targetId>
+clawdbot browser close <targetId>
+```
+
+## Snapshot / screenshot / actions
+
+Snapshot:
+
+```bash
+clawdbot browser snapshot
+```
+
+Screenshot:
+
+```bash
+clawdbot browser screenshot
+```
+
+Navigate/click/type (ref-based UI automation):
+
+```bash
+clawdbot browser navigate https://example.com
+clawdbot browser click <ref>
+clawdbot browser type <ref> "hello"
+```
+
+## Chrome extension relay (attach via toolbar button)
+
+This mode lets the agent control an existing Chrome tab that you attach manually (it does not auto-attach).
+
+Install the unpacked extension to a stable path:
+
+```bash
+clawdbot browser extension install
+clawdbot browser extension path
+```
+
+Then Chrome → `chrome://extensions` → enable “Developer mode” → “Load unpacked” → select the printed folder.
+
+Full guide: [Chrome extension](/tools/chrome-extension)
+
+## Remote browser control (`clawdbot browser serve`)
+
+If the Gateway runs on a different machine than the browser, run a standalone browser control server on the machine that runs Chrome:
+
+```bash
+clawdbot browser serve --bind 127.0.0.1 --port 18791 --token <token>
+```
+
+Then point the Gateway at it using `browser.controlUrl` + `browser.controlToken` (or `CLAWDBOT_BROWSER_CONTROL_TOKEN`).
+
+Security + TLS best-practices: [Browser tool](/tools/browser), [Tailscale](/gateway/tailscale), [Security](/gateway/security)
+

docs/cli/channels.md

@@ -0,0 +1,44 @@
+---
+summary: "CLI reference for `clawdbot channels` (accounts, status, login/logout, logs)"
+read_when:
+  - You want to add/remove channel accounts (WhatsApp/Telegram/Discord/Slack/Signal/iMessage)
+  - You want to check channel status or tail channel logs
+---
+
+# `clawdbot channels`
+
+Manage chat channel accounts and their runtime status on the Gateway.
+
+Related docs:
+- Channel guides: [Channels](/channels/index)
+- Gateway configuration: [Configuration](/gateway/configuration)
+
+## Common commands
+
+```bash
+clawdbot channels list
+clawdbot channels status
+clawdbot channels logs --channel all
+```
+
+## Add / remove accounts
+
+```bash
+clawdbot channels add --channel telegram --token <bot-token>
+clawdbot channels remove --channel telegram --delete
+```
+
+Tip: `clawdbot channels add --help` shows per-channel flags (token, app token, signal-cli paths, etc).
+
+## Login / logout (interactive)
+
+```bash
+clawdbot channels login --channel whatsapp
+clawdbot channels logout --channel whatsapp
+```
+
+## Troubleshooting
+
+- Run `clawdbot status --deep` for a broad probe.
+- Use `clawdbot doctor` for guided fixes.
+

docs/cli/configure.md

@@ -0,0 +1,20 @@
+---
+summary: "CLI reference for `clawdbot configure` / `clawdbot config` (interactive configuration prompts)"
+read_when:
+  - You want to tweak credentials, devices, or agent defaults interactively
+---
+
+# `clawdbot configure` (alias: `config`)
+
+Interactive prompt to set up credentials, devices, and agent defaults.
+
+Related:
+- Gateway configuration reference: [Configuration](/gateway/configuration)
+
+## Examples
+
+```bash
+clawdbot configure
+clawdbot configure --section models --section channels
+```
+

docs/cli/cron.md

@@ -0,0 +1,16 @@
+---
+summary: "CLI reference for `clawdbot cron` (schedule and run background jobs)"
+read_when:
+  - You want scheduled jobs and wakeups
+  - You’re debugging cron execution and logs
+---
+
+# `clawdbot cron`
+
+Manage cron jobs for the Gateway scheduler.
+
+Related:
+- Cron jobs: [Cron jobs](/automation/cron-jobs)
+
+Tip: run `clawdbot cron --help` for the full command surface.
+

docs/cli/daemon.md

@@ -0,0 +1,17 @@
+---
+summary: "CLI reference for `clawdbot daemon` (install/uninstall/status for the Gateway service)"
+read_when:
+  - You want to run the Gateway as a background service
+  - You’re debugging daemon install, status, or logs
+---
+
+# `clawdbot daemon`
+
+Manage the Gateway daemon (background service).
+
+Related:
+- Gateway CLI: [Gateway](/cli/gateway)
+- macOS platform notes: [macOS](/platforms/macos)
+
+Tip: run `clawdbot daemon --help` for platform-specific flags.
+

docs/cli/dashboard.md

@@ -0,0 +1,16 @@
+---
+summary: "CLI reference for `clawdbot dashboard` (open the Control UI)"
+read_when:
+  - You want to open the Control UI with your current token
+  - You want to print the URL without launching a browser
+---
+
+# `clawdbot dashboard`
+
+Open the Control UI using your current auth.
+
+```bash
+clawdbot dashboard
+clawdbot dashboard --no-open
+```
+

docs/cli/dns.md

@@ -0,0 +1,22 @@
+---
+summary: "CLI reference for `clawdbot dns` (wide-area discovery helpers)"
+read_when:
+  - You want wide-area discovery (DNS-SD) via Tailscale + CoreDNS
+  - You’re setting up split DNS for clawdbot.internal
+---
+
+# `clawdbot dns`
+
+DNS helpers for wide-area discovery (Tailscale + CoreDNS). Currently focused on macOS + Homebrew CoreDNS.
+
+Related:
+- Gateway discovery: [Discovery](/gateway/discovery)
+- Wide-area discovery config: [Configuration](/gateway/configuration)
+
+## Setup
+
+```bash
+clawdbot dns setup
+clawdbot dns setup --apply
+```
+

docs/cli/docs.md

@@ -0,0 +1,15 @@
+---
+summary: "CLI reference for `clawdbot docs` (search the live docs index)"
+read_when:
+  - You want to search the live Clawdbot docs from the terminal
+---
+
+# `clawdbot docs`
+
+Search the live docs index.
+
+```bash
+clawdbot docs browser extension
+clawdbot docs sandbox allowHostControl
+```
+

docs/cli/doctor.md

@@ -0,0 +1,23 @@
+---
+summary: "CLI reference for `clawdbot doctor` (health checks + guided repairs)"
+read_when:
+  - You have connectivity/auth issues and want guided fixes
+  - You updated and want a sanity check
+---
+
+# `clawdbot doctor`
+
+Health checks + quick fixes for the gateway and channels.
+
+Related:
+- Troubleshooting: [Troubleshooting](/gateway/troubleshooting)
+- Security audit: [Security](/gateway/security)
+
+## Examples
+
+```bash
+clawdbot doctor
+clawdbot doctor --repair
+clawdbot doctor --deep
+```
+

docs/cli/gateway.md

@@ -8,7 +8,7 @@ read_when:
 
 # Gateway CLI
 
-The Gateway is Clawdbot’s WebSocket server (providers, nodes, sessions, hooks).
+The Gateway is Clawdbot’s WebSocket server (channels, nodes, sessions, hooks).
 
 Subcommands in this page live under `clawdbot gateway …`.
 

docs/cli/health.md

@@ -0,0 +1,15 @@
+---
+summary: "CLI reference for `clawdbot health` (gateway health endpoint via RPC)"
+read_when:
+  - You want to quickly check the running Gateway’s health
+---
+
+# `clawdbot health`
+
+Fetch health from the running Gateway.
+
+```bash
+clawdbot health
+clawdbot health --json
+```
+

docs/cli/hooks.md

@@ -0,0 +1,22 @@
+---
+summary: "CLI reference for `clawdbot hooks` (Gmail Pub/Sub + webhook helpers)"
+read_when:
+  - You want to wire Gmail Pub/Sub events into Clawdbot hooks
+  - You want to run the gog watch service and renew loop
+---
+
+# `clawdbot hooks`
+
+Webhook helpers and hook-based integrations.
+
+Related:
+- Webhooks: [Webhook](/automation/webhook)
+- Gmail Pub/Sub: [Gmail Pub/Sub](/automation/gmail-pubsub)
+
+## Gmail
+
+```bash
+clawdbot hooks gmail setup --account you@example.com
+clawdbot hooks gmail run
+```
+

docs/cli/index.md

@@ -9,6 +9,43 @@ read_when:
 
 This page describes the current CLI behavior. If commands change, update this doc.
 
+## Command pages
+
+- [`setup`](/cli/setup)
+- [`onboard`](/cli/onboard)
+- [`configure`](/cli/configure) (alias: `config`)
+- [`doctor`](/cli/doctor)
+- [`dashboard`](/cli/dashboard)
+- [`reset`](/cli/reset)
+- [`uninstall`](/cli/uninstall)
+- [`update`](/cli/update)
+- [`message`](/cli/message)
+- [`agent`](/cli/agent)
+- [`agents`](/cli/agents)
+- [`status`](/cli/status)
+- [`health`](/cli/health)
+- [`sessions`](/cli/sessions)
+- [`gateway`](/cli/gateway)
+- [`daemon`](/cli/daemon)
+- [`logs`](/cli/logs)
+- [`models`](/cli/models)
+- [`memory`](/cli/memory)
+- [`nodes`](/cli/nodes)
+- [`sandbox`](/cli/sandbox)
+- [`tui`](/cli/tui)
+- [`browser`](/cli/browser)
+- [`wake`](/cli/wake)
+- [`cron`](/cli/cron)
+- [`dns`](/cli/dns)
+- [`docs`](/cli/docs)
+- [`hooks`](/cli/hooks)
+- [`pairing`](/cli/pairing)
+- [`plugins`](/cli/plugins) (plugin commands)
+- [`channels`](/cli/channels)
+- [`security`](/cli/security)
+- [`skills`](/cli/skills)
+- [`voicecall`](/cli/voicecall) (plugin; if installed)
+
 ## Global flags
 
 - `--dev`: isolate state under `~/.clawdbot-dev` and shift default ports.
@@ -29,7 +66,7 @@ This page describes the current CLI behavior. If commands change, update this do
 
 Clawdbot uses a lobster palette for CLI output.
 
-- `accent` (#FF5A2D): headings, provider labels, primary highlights.
+- `accent` (#FF5A2D): headings, labels, primary highlights.
 - `accentBright` (#FF7A3D): command names, emphasis.
 - `accentDim` (#D14A22): secondary highlight text.
 - `info` (#FF8A5B): informational values.
@@ -48,10 +85,12 @@ clawdbot [--dev] [--profile <name>] <command>
   onboard
   configure (alias: config)
   doctor
+  security
+    audit
   reset
   uninstall
   update
-  providers
+  channels
     list
     status
     logs
@@ -180,6 +219,12 @@ clawdbot [--dev] [--profile <name>] <command>
 
 Note: plugins can add additional top-level commands (for example `clawdbot voicecall`).
 
+## Security
+
+- `clawdbot security audit` — audit config + local state for common security foot-guns.
+- `clawdbot security audit --deep` — best-effort live Gateway probe.
+- `clawdbot security audit --fix` — tighten safe defaults and chmod state/config.
+
 ## Plugins
 
 Manage extensions and their config:
@@ -258,15 +303,15 @@ Options:
 - `--install-daemon`
 - `--no-install-daemon` (alias: `--skip-daemon`)
 - `--daemon-runtime <node|bun>`
-- `--skip-providers`
+- `--skip-channels`
 - `--skip-skills`
 - `--skip-health`
 - `--skip-ui`
-- `--node-manager <npm|pnpm|bun>`
+- `--node-manager <npm|pnpm|bun>` (pnpm recommended; bun not recommended for Gateway runtime)
 - `--json`
 
 ### `configure` / `config`
-Interactive configuration wizard (models, providers, skills, gateway).
+Interactive configuration wizard (models, channels, skills, gateway).
 
 ### `doctor`
 Health checks + quick fixes (config + gateway + legacy services).
@@ -277,41 +322,41 @@ Options:
 - `--non-interactive`: skip prompts; apply safe migrations only.
 - `--deep`: scan system services for extra gateway installs.
 
-## Provider helpers
+## Channel helpers
 
-### `providers`
-Manage chat provider accounts (WhatsApp/Telegram/Discord/Slack/Signal/iMessage/MS Teams).
+### `channels`
+Manage chat channel accounts (WhatsApp/Telegram/Discord/Slack/Signal/iMessage/MS Teams).
 
 Subcommands:
-- `providers list`: show configured chat providers and auth profiles (Claude Code + Codex CLI OAuth sync included).
-- `providers status`: check gateway reachability and provider health (`--probe` runs extra checks; use `clawdbot health` or `clawdbot status --deep` for gateway health probes).
-- Tip: `providers status` prints warnings with suggested fixes when it can detect common misconfigurations (then points you to `clawdbot doctor`).
-- `providers logs`: show recent provider logs from the gateway log file.
-- `providers add`: wizard-style setup when no flags are passed; flags switch to non-interactive mode.
-- `providers remove`: disable by default; pass `--delete` to remove config entries without prompts.
-- `providers login`: interactive provider login (WhatsApp Web only).
-- `providers logout`: log out of a provider session (if supported).
+- `channels list`: show configured channels and auth profiles (Claude Code + Codex CLI OAuth sync included).
+- `channels status`: check gateway reachability and channel health (`--probe` runs extra checks; use `clawdbot health` or `clawdbot status --deep` for gateway health probes).
+- Tip: `channels status` prints warnings with suggested fixes when it can detect common misconfigurations (then points you to `clawdbot doctor`).
+- `channels logs`: show recent channel logs from the gateway log file.
+- `channels add`: wizard-style setup when no flags are passed; flags switch to non-interactive mode.
+- `channels remove`: disable by default; pass `--delete` to remove config entries without prompts.
+- `channels login`: interactive channel login (WhatsApp Web only).
+- `channels logout`: log out of a channel session (if supported).
 
 Common options:
-- `--provider <name>`: `whatsapp|telegram|discord|slack|signal|imessage|msteams`
-- `--account <id>`: provider account id (default `default`)
+- `--channel <name>`: `whatsapp|telegram|discord|slack|signal|imessage|msteams`
+- `--account <id>`: channel account id (default `default`)
 - `--name <label>`: display name for the account
 
-`providers login` options:
-- `--provider <provider>` (default `whatsapp`; supports `whatsapp`/`web`)
+`channels login` options:
+- `--channel <channel>` (default `whatsapp`; supports `whatsapp`/`web`)
 - `--account <id>`
 - `--verbose`
 
-`providers logout` options:
-- `--provider <provider>` (default `whatsapp`)
+`channels logout` options:
+- `--channel <channel>` (default `whatsapp`)
 - `--account <id>`
 
-`providers list` options:
-- `--no-usage`: skip provider usage/quota snapshots (OAuth/API-backed only).
+`channels list` options:
+- `--no-usage`: skip model provider usage/quota snapshots (OAuth/API-backed only).
 - `--json`: output JSON (includes usage unless `--no-usage` is set).
 
-`providers logs` options:
-- `--provider <name|all>` (default `all`)
+`channels logs` options:
+- `--channel <name|all>` (default `all`)
 - `--lines <n>` (default `200`)
 - `--json`
 
@@ -325,10 +370,10 @@ More detail: [/concepts/oauth](/concepts/oauth)
 
 Examples:
 ```bash
-clawdbot providers add --provider telegram --account alerts --name "Alerts Bot" --token $TELEGRAM_BOT_TOKEN
-clawdbot providers add --provider discord --account work --name "Work Bot" --token $DISCORD_BOT_TOKEN
-clawdbot providers remove --provider discord --account work --delete
-clawdbot providers status --probe
+clawdbot channels add --channel telegram --account alerts --name "Alerts Bot" --token $TELEGRAM_BOT_TOKEN
+clawdbot channels add --channel discord --account work --name "Work Bot" --token $DISCORD_BOT_TOKEN
+clawdbot channels remove --channel discord --account work --delete
+clawdbot channels status --probe
 clawdbot status --deep
 ```
 
@@ -348,11 +393,11 @@ Options:
 Tip: use `npx clawdhub` to search, install, and sync skills.
 
 ### `pairing`
-Approve DM pairing requests across providers.
+Approve DM pairing requests across channels.
 
 Subcommands:
-- `pairing list <provider> [--json]`
-- `pairing approve <provider> <code> [--notify]`
+- `pairing list <channel> [--json]`
+- `pairing approve <channel> <code> [--notify]`
 
 ### `hooks gmail`
 Gmail Pub/Sub hook setup + runner. See [/automation/gmail-pubsub](/automation/gmail-pubsub).
@@ -370,7 +415,7 @@ Options:
 ## Messaging + agent
 
 ### `message`
-Unified outbound messaging + provider actions.
+Unified outbound messaging + channel actions.
 
 See: [/cli/message](/cli/message)
 
@@ -387,7 +432,7 @@ Subcommands:
 
 Examples:
 - `clawdbot message send --to +15555550123 --message "Hi"`
-- `clawdbot message poll --provider discord --to channel:123 --poll-question "Snack?" --poll-option Pizza --poll-option Sushi`
+- `clawdbot message poll --channel discord --to channel:123 --poll-question "Snack?" --poll-option Pizza --poll-option Sushi`
 
 ### `agent`
 Run one agent turn via the Gateway (or `--local` embedded).
@@ -400,7 +445,7 @@ Options:
 - `--session-id <id>`
 - `--thinking <off|minimal|low|medium|high|xhigh>` (GPT-5.2 + Codex models only)
 - `--verbose <on|off>`
-- `--provider <whatsapp|telegram|discord|slack|signal|imessage>`
+- `--channel <whatsapp|telegram|discord|slack|signal|imessage>`
 - `--local`
 - `--deliver`
 - `--json`
@@ -423,11 +468,11 @@ Options:
 - `--workspace <dir>`
 - `--model <id>`
 - `--agent-dir <dir>`
-- `--bind <provider[:accountId]>` (repeatable)
+- `--bind <channel[:accountId]>` (repeatable)
 - `--non-interactive`
 - `--json`
 
-Binding specs use `provider[:accountId]`. When `accountId` is omitted for WhatsApp, the default account id is used.
+Binding specs use `channel[:accountId]`. When `accountId` is omitted for WhatsApp, the default account id is used.
 
 #### `agents delete <id>`
 Delete an agent and prune its workspace + state.
@@ -442,8 +487,8 @@ Show linked session health and recent recipients.
 Options:
 - `--json`
 - `--all` (full diagnosis; read-only, pasteable)
-- `--deep` (probe providers)
-- `--usage` (show provider usage/quota)
+- `--deep` (probe channels)
+- `--usage` (show model provider usage/quota)
 - `--timeout <ms>`
 - `--verbose`
 - `--debug` (alias for `--verbose`)
@@ -549,7 +594,7 @@ Notes:
 - `daemon status` supports `--no-probe`, `--deep`, and `--json` for scripting.
 - `daemon status` also surfaces legacy or extra gateway services when it can detect them (`--deep` adds system-level scans). Profile-named Clawdbot services are treated as first-class and aren't flagged as "extra".
 - `daemon status` prints which config path the CLI uses vs which config the daemon likely uses (service env), plus the resolved probe target URL.
-- `daemon install` defaults to Node runtime; use `--runtime bun` only when WhatsApp is disabled.
+- `daemon install` defaults to Node runtime; bun is **not recommended** (WhatsApp/Telegram bugs).
 - `daemon install` options: `--port`, `--runtime`, `--token`, `--force`.
 
 ### `logs`
@@ -579,8 +624,12 @@ Subcommands:
 
 Common RPCs:
 - `config.apply` (validate + write config + restart + wake)
+- `config.patch` (merge a partial update without clobbering unrelated keys)
 - `update.run` (run update + restart + wake)
 
+Tip: when calling `config.set`/`config.apply`/`config.patch` directly, pass `baseHash` from
+`config.get` if a config already exists.
+
 ## Models
 
 See [/concepts/models](/concepts/models) for fallback behavior and scanning strategy.
@@ -736,7 +785,7 @@ Location:
 
 ## Browser
 
-Browser control CLI (dedicated Chrome/Chromium). See [/tools/browser](/tools/browser).
+Browser control CLI (dedicated Chrome/Chromium). See [`clawdbot browser`](/cli/browser) and the [Browser tool](/tools/browser).
 
 Common options:
 - `--url <controlUrl>`

docs/cli/logs.md

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

docs/cli/memory.md

@@ -0,0 +1,22 @@
+---
+summary: "CLI reference for `clawdbot memory` (status/index/search)"
+read_when:
+  - You want to index or search semantic memory
+  - You’re debugging memory availability or indexing
+---
+
+# `clawdbot memory`
+
+Memory search tools (semantic memory status/index/search).
+
+Related:
+- Memory concept: [Memory](/concepts/memory)
+
+## Examples
+
+```bash
+clawdbot memory status
+clawdbot memory index
+clawdbot memory search "release checklist"
+```
+

docs/cli/message.md

@@ -1,13 +1,13 @@
 ---
-summary: "CLI reference for `clawdbot message` (send + provider actions)"
+summary: "CLI reference for `clawdbot message` (send + channel actions)"
 read_when:
   - Adding or modifying message CLI actions
-  - Changing outbound provider behavior
+  - Changing outbound channel behavior
 ---
 
 # `clawdbot message`
 
-Single outbound command for sending messages and provider actions
+Single outbound command for sending messages and channel actions
 (Discord/Slack/Telegram/WhatsApp/Signal/iMessage/MS Teams).
 
 ## Usage
@@ -16,9 +16,9 @@ Single outbound command for sending messages and provider actions
 clawdbot message <subcommand> [flags]
 ```
 
-Provider selection:
-- `--provider` required if more than one provider is configured.
-- If exactly one provider is configured, it becomes the default.
+Channel selection:
+- `--channel` required if more than one channel is configured.
+- If exactly one channel is configured, it becomes the default.
 - Values: `whatsapp|telegram|discord|slack|signal|imessage|msteams`
 
 Target formats (`--to`):
@@ -32,7 +32,7 @@ Target formats (`--to`):
 
 ## Common flags
 
-- `--provider <name>`
+- `--channel <name>`
 - `--account <id>`
 - `--json`
 - `--dry-run`
@@ -43,82 +43,82 @@ Target formats (`--to`):
 ### Core
 
 - `send`
-  - Providers: WhatsApp/Telegram/Discord/Slack/Signal/iMessage/MS Teams
+  - Channels: WhatsApp/Telegram/Discord/Slack/Signal/iMessage/MS Teams
   - Required: `--to`, `--message`
   - Optional: `--media`, `--reply-to`, `--thread-id`, `--gif-playback`
-  - Telegram only: `--buttons` (requires `"inlineButtons"` in `telegram.capabilities` or `telegram.accounts.<id>.capabilities`)
+  - Telegram only: `--buttons` (requires `"inlineButtons"` in `channels.telegram.capabilities` or `channels.telegram.accounts.<id>.capabilities`)
   - Telegram only: `--thread-id` (forum topic id)
   - Slack only: `--thread-id` (thread timestamp; `--reply-to` uses the same field)
   - WhatsApp only: `--gif-playback`
 
 - `poll`
-  - Providers: WhatsApp/Discord/MS Teams
+  - Channels: WhatsApp/Discord/MS Teams
   - Required: `--to`, `--poll-question`, `--poll-option` (repeat)
   - Optional: `--poll-multi`
   - Discord only: `--poll-duration-hours`, `--message`
 
 - `react`
-  - Providers: Discord/Slack/Telegram/WhatsApp
+  - Channels: Discord/Slack/Telegram/WhatsApp
   - Required: `--message-id`, `--to` or `--channel-id`
   - Optional: `--emoji`, `--remove`, `--participant`, `--from-me`, `--channel-id`
   - Note: `--remove` requires `--emoji` (omit `--emoji` to clear own reactions where supported; see /tools/reactions)
   - WhatsApp only: `--participant`, `--from-me`
 
 - `reactions`
-  - Providers: Discord/Slack
+  - Channels: Discord/Slack
   - Required: `--message-id`, `--to` or `--channel-id`
   - Optional: `--limit`, `--channel-id`
 
 - `read`
-  - Providers: Discord/Slack
+  - Channels: Discord/Slack
   - Required: `--to` or `--channel-id`
   - Optional: `--limit`, `--before`, `--after`, `--channel-id`
   - Discord only: `--around`
 
 - `edit`
-  - Providers: Discord/Slack
+  - Channels: Discord/Slack
   - Required: `--message-id`, `--message`, `--to` or `--channel-id`
   - Optional: `--channel-id`
 
 - `delete`
-  - Providers: Discord/Slack
+  - Channels: Discord/Slack/Telegram
   - Required: `--message-id`, `--to` or `--channel-id`
   - Optional: `--channel-id`
 
 - `pin` / `unpin`
-  - Providers: Discord/Slack
+  - Channels: Discord/Slack
   - Required: `--message-id`, `--to` or `--channel-id`
   - Optional: `--channel-id`
 
 - `pins` (list)
-  - Providers: Discord/Slack
+  - Channels: Discord/Slack
   - Required: `--to` or `--channel-id`
   - Optional: `--channel-id`
 
 - `permissions`
-  - Providers: Discord
+  - Channels: Discord
   - Required: `--to` or `--channel-id`
   - Optional: `--channel-id`
 
 - `search`
-  - Providers: Discord
+  - Channels: Discord
   - Required: `--guild-id`, `--query`
   - Optional: `--channel-id`, `--channel-ids` (repeat), `--author-id`, `--author-ids` (repeat), `--limit`
 
 ### Threads
 
 - `thread create`
-  - Providers: Discord
+  - Channels: Discord
   - Required: `--thread-name`, `--to` (channel id) or `--channel-id`
   - Optional: `--message-id`, `--auto-archive-min`
 
 - `thread list`
-  - Providers: Discord
+  - Channels: Discord
   - Required: `--guild-id`
   - Optional: `--channel-id`, `--include-archived`, `--before`, `--limit`
 
 - `thread reply`
-  - Providers: Discord
+  - Channels: Discord
   - Required: `--to` (thread id), `--message`
   - Optional: `--media`, `--reply-to`
 
@@ -129,19 +129,19 @@ Target formats (`--to`):
   - Slack: no extra flags
 
 - `emoji upload`
-  - Providers: Discord
+  - Channels: Discord
   - Required: `--guild-id`, `--emoji-name`, `--media`
   - Optional: `--role-ids` (repeat)
 
 ### Stickers
 
 - `sticker send`
-  - Providers: Discord
+  - Channels: Discord
   - Required: `--to`, `--sticker-id` (repeat)
   - Optional: `--message`
 
 - `sticker upload`
-  - Providers: Discord
+  - Channels: Discord
   - Required: `--guild-id`, `--sticker-name`, `--sticker-desc`, `--sticker-tags`, `--media`
 
 ### Roles / Channels / Members / Voice
@@ -170,13 +170,13 @@ Target formats (`--to`):
 
 Send a Discord reply:
 ```
-clawdbot message send --provider discord \
+clawdbot message send --channel discord \
   --to channel:123 --message "hi" --reply-to 456
 ```
 
 Create a Discord poll:
 ```
-clawdbot message poll --provider discord \
+clawdbot message poll --channel discord \
   --to channel:123 \
   --poll-question "Snack?" \
   --poll-option Pizza --poll-option Sushi \
@@ -185,13 +185,13 @@ clawdbot message poll --provider discord \
 
 Send a Teams proactive message:
 ```
-clawdbot message send --provider msteams \
+clawdbot message send --channel msteams \
   --to conversation:19:abc@thread.tacv2 --message "hi"
 ```
 
 Create a Teams poll:
 ```
-clawdbot message poll --provider msteams \
+clawdbot message poll --channel msteams \
   --to conversation:19:abc@thread.tacv2 \
   --poll-question "Lunch?" \
   --poll-option Pizza --poll-option Sushi
@@ -199,12 +199,12 @@ clawdbot message poll --provider msteams \
 
 React in Slack:
 ```
-clawdbot message react --provider slack \
+clawdbot message react --channel slack \
   --to C123 --message-id 456 --emoji "✅"
 ```
 
 Send Telegram inline buttons:
 ```
-clawdbot message send --provider telegram --to @mychat --message "Choose:" \
+clawdbot message send --channel telegram --to @mychat --message "Choose:" \
   --buttons '[ [{"text":"Yes","callback_data":"cmd:yes"}], [{"text":"No","callback_data":"cmd:no"}] ]'
 ```

docs/cli/models.md

@@ -0,0 +1,39 @@
+---
+summary: "CLI reference for `clawdbot models` (status/list/set/scan, aliases, fallbacks, auth)"
+read_when:
+  - You want to change default models or view provider auth status
+  - You want to scan available models/providers and debug auth profiles
+---
+
+# `clawdbot models`
+
+Model discovery, scanning, and configuration (default model, fallbacks, auth profiles).
+
+Related:
+- Providers + models: [Models](/providers/models)
+- Provider auth setup: [Getting started](/start/getting-started)
+
+## Common commands
+
+```bash
+clawdbot models status
+clawdbot models list
+clawdbot models set <model-or-alias>
+clawdbot models scan
+```
+
+## Aliases + fallbacks
+
+```bash
+clawdbot models aliases list
+clawdbot models fallbacks list
+```
+
+## Auth profiles
+
+```bash
+clawdbot models auth add
+clawdbot models auth setup-token
+clawdbot models auth paste-token
+```
+

docs/cli/nodes.md

@@ -0,0 +1,32 @@
+---
+summary: "CLI reference for `clawdbot nodes` (list/status/approve/invoke, camera/canvas/screen)"
+read_when:
+  - You’re managing paired nodes (cameras, screen, canvas)
+  - You need to approve requests or invoke node commands
+---
+
+# `clawdbot nodes`
+
+Manage paired nodes (devices) and invoke node capabilities.
+
+Related:
+- Nodes overview: [Nodes](/nodes)
+- Camera: [Camera nodes](/nodes/camera)
+- Images: [Image nodes](/nodes/images)
+
+## Common commands
+
+```bash
+clawdbot nodes list
+clawdbot nodes pending
+clawdbot nodes approve <requestId>
+clawdbot nodes status
+```
+
+## Invoke / run
+
+```bash
+clawdbot nodes invoke --node <id|name|ip> --command <command> --params <json>
+clawdbot nodes run --node <id|name|ip> <command...>
+```
+

docs/cli/onboard.md

@@ -0,0 +1,21 @@
+---
+summary: "CLI reference for `clawdbot onboard` (interactive onboarding wizard)"
+read_when:
+  - You want guided setup for gateway, workspace, auth, channels, and skills
+---
+
+# `clawdbot onboard`
+
+Interactive onboarding wizard (local or remote Gateway setup).
+
+Related:
+- Wizard guide: [Onboarding](/start/onboarding)
+
+## Examples
+
+```bash
+clawdbot onboard
+clawdbot onboard --flow quickstart
+clawdbot onboard --mode remote --remote-url ws://gateway-host:18789
+```
+