chore: ignore local identity files (#1001) (thanks @gerardward2007)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.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"

.dockerignore

@@ -0,0 +1,48 @@
+.git
+.worktrees
+.bun-cache
+.bun
+.tmp
+**/.tmp
+.DS_Store
+**/.DS_Store
+*.png
+*.jpg
+*.jpeg
+*.webp
+*.gif
+*.mp4
+*.mov
+*.wav
+*.mp3
+node_modules
+**/node_modules
+.pnpm-store
+**/.pnpm-store
+.turbo
+**/.turbo
+.cache
+**/.cache
+.next
+**/.next
+coverage
+**/coverage
+*.log
+tmp
+**/tmp
+
+# build artifacts
+dist
+**/dist
+apps/macos/.build
+apps/ios/build
+**/*.trace
+
+# large app trees not needed for CLI build
+apps/
+assets/
+Peekaboo/
+Swabble/
+Core/
+Users/
+vendor/

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Report a problem or unexpected behavior in Clawdbot.
+title: "[Bug]: "
+labels: bug
+---
+
+## Summary
+What went wrong?
+
+## Steps to reproduce
+1.
+2.
+3.
+
+## Expected behavior
+What did you expect to happen?
+
+## Actual behavior
+What actually happened?
+
+## Environment
+- Clawdbot version:
+- OS:
+- Install method (pnpm/npx/docker/etc):
+
+## Logs or screenshots
+Paste relevant logs or add screenshots (redact secrets).

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Onboarding
+    url: https://discord.gg/clawd
+    about: New to Clawdbot? Join Discord for setup guidance from Krill in #help.
+  - name: Support
+    url: https://discord.gg/clawd
+    about: Get help from Krill and the community on Discord in #help.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: Feature request
+about: Suggest an idea or improvement for Clawdbot.
+title: "[Feature]: "
+labels: enhancement
+---
+
+## Summary
+Describe the problem you are trying to solve or the opportunity you see.
+
+## Proposed solution
+What would you like Clawdbot to do?
+
+## Alternatives considered
+Any other approaches you have considered?
+
+## Additional context
+Links, screenshots, or related issues.

.github/workflows/ci.yml

@@ -5,19 +5,281 @@ on:
   pull_request:
 
 jobs:
-  build:
-    runs-on: ubuntu-latest
+  install-check:
+    runs-on: blacksmith-4vcpu-ubuntu-2404
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Checkout submodules (retry)
+        run: |
+          set -euo pipefail
+          git submodule sync --recursive
+          for attempt in 1 2 3 4 5; do
+            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
+              exit 0
+            fi
+            echo "Submodule update failed (attempt $attempt/5). Retrying…"
+            sleep $((attempt * 10))
+          done
+          exit 1
 
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: 22.x
           check-latest: true
 
-      - name: Node version
+      - name: Runtime versions
+        run: |
+          node -v
+          npm -v
+
+      - name: Capture node path
+        run: echo "NODE_BIN=$(dirname \"$(node -p \"process.execPath\")\")" >> "$GITHUB_ENV"
+
+      - name: Enable corepack and pin pnpm
+        run: |
+          corepack enable
+          corepack prepare pnpm@10.23.0 --activate
+          pnpm -v
+
+      - name: Install dependencies (frozen)
+        env:
+          CI: true
+        run: |
+          export PATH="$NODE_BIN:$PATH"
+          which node
+          node -v
+          pnpm -v
+          pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true
+
+  checks:
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runtime: node
+            task: lint
+            command: pnpm lint
+          - runtime: node
+            task: test
+            command: pnpm test
+          - runtime: node
+            task: build
+            command: pnpm build
+          - runtime: node
+            task: protocol
+            command: pnpm protocol:check
+          - runtime: node
+            task: format
+            command: pnpm format
+          - runtime: bun
+            task: test
+            command: bunx vitest run
+          - runtime: bun
+            task: build
+            command: bunx tsc -p tsconfig.json
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Checkout submodules (retry)
+        run: |
+          set -euo pipefail
+          git submodule sync --recursive
+          for attempt in 1 2 3 4 5; do
+            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
+              exit 0
+            fi
+            echo "Submodule update failed (attempt $attempt/5). Retrying…"
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          check-latest: true
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Runtime versions
+        run: |
+          node -v
+          npm -v
+          bun -v
+
+      - name: Capture node path
+        run: echo "NODE_BIN=$(dirname \"$(node -p \"process.execPath\")\")" >> "$GITHUB_ENV"
+
+      - name: Enable corepack and pin pnpm
+        run: |
+          corepack enable
+          corepack prepare pnpm@10.23.0 --activate
+          pnpm -v
+
+      - name: Install dependencies
+        env:
+          CI: true
+        run: |
+          export PATH="$NODE_BIN:$PATH"
+          which node
+          node -v
+          pnpm -v
+          pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true || pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true
+
+      - 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:
+      run:
+        shell: bash
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runtime: node
+            task: lint
+            command: pnpm lint
+          - runtime: node
+            task: test
+            command: pnpm test
+          - runtime: node
+            task: build
+            command: pnpm build
+          - runtime: node
+            task: protocol
+            command: pnpm protocol:check
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Checkout submodules (retry)
+        run: |
+          set -euo pipefail
+          git submodule sync --recursive
+          for attempt in 1 2 3 4 5; do
+            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
+              exit 0
+            fi
+            echo "Submodule update failed (attempt $attempt/5). Retrying…"
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          check-latest: true
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Runtime versions
+        run: |
+          node -v
+          npm -v
+          bun -v
+
+      - name: Capture node path
+        run: echo "NODE_BIN=$(dirname \"$(node -p \"process.execPath\")\")" >> "$GITHUB_ENV"
+
+      - name: Enable corepack and pin pnpm
+        run: |
+          corepack enable
+          corepack prepare pnpm@10.23.0 --activate
+          pnpm -v
+
+      - name: Install dependencies
+        env:
+          CI: true
+        run: |
+          export PATH="$NODE_BIN:$PATH"
+          which node
+          node -v
+          pnpm -v
+          pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true || pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true
+
+      - name: Run ${{ matrix.task }} (${{ matrix.runtime }})
+        run: ${{ matrix.command }}
+
+  checks-macos:
+    if: github.event_name == 'pull_request'
+    runs-on: macos-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - task: test
+            command: pnpm test
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Checkout submodules (retry)
+        run: |
+          set -euo pipefail
+          git submodule sync --recursive
+          for attempt in 1 2 3 4 5; do
+            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
+              exit 0
+            fi
+            echo "Submodule update failed (attempt $attempt/5). Retrying…"
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.x
+          check-latest: true
+
+      - name: Runtime versions
         run: |
           node -v
           npm -v
@@ -39,13 +301,304 @@ jobs:
           which node
           node -v
           pnpm -v
-          pnpm install --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true || pnpm install --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true
+          pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true || pnpm install --frozen-lockfile --ignore-scripts=false --config.engine-strict=false --config.enable-pre-post-scripts=true
 
-      - name: Lint
-        run: pnpm lint
+      - name: Run ${{ matrix.task }}
+        run: ${{ matrix.command }}
 
-      - name: Test
-        run: pnpm test
+  macos-app:
+    if: github.event_name == 'pull_request'
+    runs-on: macos-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - task: lint
+            command: |
+              swiftlint --config .swiftlint.yml
+              swiftformat --lint apps/macos/Sources --config .swiftformat
+          - task: build
+            command: |
+              set -euo pipefail
+              for attempt in 1 2 3; do
+                if swift build --package-path apps/macos --configuration release; then
+                  exit 0
+                fi
+                echo "swift build failed (attempt $attempt/3). Retrying…"
+                sleep $((attempt * 20))
+              done
+              exit 1
+          - task: test
+            command: |
+              set -euo pipefail
+              for attempt in 1 2 3; do
+                if swift test --package-path apps/macos --parallel --enable-code-coverage --show-codecov-path; then
+                  exit 0
+                fi
+                echo "swift test failed (attempt $attempt/3). Retrying…"
+                sleep $((attempt * 20))
+              done
+              exit 1
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
 
-      - name: Build
-        run: pnpm build
+      - name: Checkout submodules (retry)
+        run: |
+          set -euo pipefail
+          git submodule sync --recursive
+          for attempt in 1 2 3 4 5; do
+            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
+              exit 0
+            fi
+            echo "Submodule update failed (attempt $attempt/5). Retrying…"
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Select Xcode 26.1
+        run: |
+          sudo xcode-select -s /Applications/Xcode_26.1.app
+          xcodebuild -version
+
+      - name: Install XcodeGen / SwiftLint / SwiftFormat
+        run: |
+          brew install xcodegen swiftlint swiftformat
+
+      - name: Show toolchain
+        run: |
+          sw_vers
+          xcodebuild -version
+          swift --version
+
+      - name: Run ${{ matrix.task }}
+        run: ${{ matrix.command }}
+  ios:
+    if: false # ignore iOS in CI for now
+    runs-on: macos-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Checkout submodules (retry)
+        run: |
+          set -euo pipefail
+          git submodule sync --recursive
+          for attempt in 1 2 3 4 5; do
+            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
+              exit 0
+            fi
+            echo "Submodule update failed (attempt $attempt/5). Retrying…"
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Select Xcode 26.1
+        run: |
+          sudo xcode-select -s /Applications/Xcode_26.1.app
+          xcodebuild -version
+
+      - name: Install XcodeGen
+        run: brew install xcodegen
+
+      - name: Install SwiftLint / SwiftFormat
+        run: brew install swiftlint swiftformat
+
+      - name: Show toolchain
+        run: |
+          sw_vers
+          xcodebuild -version
+          swift --version
+
+      - name: Generate iOS project
+        run: |
+          cd apps/ios
+          xcodegen generate
+
+      - name: iOS tests
+        run: |
+          set -euo pipefail
+          RESULT_BUNDLE_PATH="$RUNNER_TEMP/Clawdis-iOS.xcresult"
+          DEST_ID="$(
+            python3 - <<'PY'
+          import json
+          import subprocess
+          import sys
+          import uuid
+
+          def sh(args: list[str]) -> str:
+            return subprocess.check_output(args, text=True).strip()
+
+          # Prefer an already-created iPhone simulator if it exists.
+          devices = json.loads(sh(["xcrun", "simctl", "list", "devices", "-j"]))
+          candidates: list[tuple[str, str]] = []
+          for runtime, devs in (devices.get("devices") or {}).items():
+            for dev in devs or []:
+              if not dev.get("isAvailable"):
+                continue
+              name = str(dev.get("name") or "")
+              udid = str(dev.get("udid") or "")
+              if not udid or not name.startswith("iPhone"):
+                continue
+              candidates.append((name, udid))
+
+          candidates.sort(key=lambda it: (0 if "iPhone 16" in it[0] else 1, it[0]))
+          if candidates:
+            print(candidates[0][1])
+            sys.exit(0)
+
+          # Otherwise, create one from the newest available iOS runtime.
+          runtimes = json.loads(sh(["xcrun", "simctl", "list", "runtimes", "-j"])).get("runtimes") or []
+          ios = [rt for rt in runtimes if rt.get("platform") == "iOS" and rt.get("isAvailable")]
+          if not ios:
+            print("No available iOS runtimes found.", file=sys.stderr)
+            sys.exit(1)
+
+          def version_key(rt: dict) -> tuple[int, ...]:
+            parts: list[int] = []
+            for p in str(rt.get("version") or "0").split("."):
+              try:
+                parts.append(int(p))
+              except ValueError:
+                parts.append(0)
+            return tuple(parts)
+
+          ios.sort(key=version_key, reverse=True)
+          runtime = ios[0]
+          runtime_id = str(runtime.get("identifier") or "")
+          if not runtime_id:
+            print("Missing iOS runtime identifier.", file=sys.stderr)
+            sys.exit(1)
+
+          supported = runtime.get("supportedDeviceTypes") or []
+          iphones = [dt for dt in supported if dt.get("productFamily") == "iPhone"]
+          if not iphones:
+            print("No iPhone device types for iOS runtime.", file=sys.stderr)
+            sys.exit(1)
+
+          iphones.sort(
+            key=lambda dt: (
+              0 if "iPhone 16" in str(dt.get("name") or "") else 1,
+              str(dt.get("name") or ""),
+            )
+          )
+          device_type_id = str(iphones[0].get("identifier") or "")
+          if not device_type_id:
+            print("Missing iPhone device type identifier.", file=sys.stderr)
+            sys.exit(1)
+
+          sim_name = f"CI iPhone {uuid.uuid4().hex[:8]}"
+          udid = sh(["xcrun", "simctl", "create", sim_name, device_type_id, runtime_id])
+          if not udid:
+            print("Failed to create iPhone simulator.", file=sys.stderr)
+            sys.exit(1)
+          print(udid)
+          PY
+          )"
+          echo "Using iOS Simulator id: $DEST_ID"
+          xcodebuild test \
+            -project apps/ios/Clawdis.xcodeproj \
+            -scheme Clawdis \
+            -destination "platform=iOS Simulator,id=$DEST_ID" \
+            -resultBundlePath "$RESULT_BUNDLE_PATH" \
+            -enableCodeCoverage YES
+
+      - name: iOS coverage summary
+        run: |
+          set -euo pipefail
+          RESULT_BUNDLE_PATH="$RUNNER_TEMP/Clawdis-iOS.xcresult"
+          xcrun xccov view --report --only-targets "$RESULT_BUNDLE_PATH"
+
+      - name: iOS coverage gate (43%)
+        run: |
+          set -euo pipefail
+          RESULT_BUNDLE_PATH="$RUNNER_TEMP/Clawdis-iOS.xcresult"
+          RESULT_BUNDLE_PATH="$RESULT_BUNDLE_PATH" python3 - <<'PY'
+          import json
+          import os
+          import subprocess
+          import sys
+
+          target_name = "Clawdis.app"
+          minimum = 0.43
+
+          report = json.loads(
+            subprocess.check_output(
+              ["xcrun", "xccov", "view", "--report", "--json", os.environ["RESULT_BUNDLE_PATH"]],
+              text=True,
+            )
+          )
+
+          target_coverage = None
+          for target in report.get("targets", []):
+            if target.get("name") == target_name:
+              target_coverage = float(target["lineCoverage"])
+              break
+
+          if target_coverage is None:
+            print(f"Could not find coverage for target: {target_name}")
+            sys.exit(1)
+
+          print(f"{target_name} line coverage: {target_coverage * 100:.2f}% (min {minimum * 100:.2f}%)")
+          if target_coverage + 1e-12 < minimum:
+            sys.exit(1)
+          PY
+
+  android:
+    runs-on: blacksmith-4vcpu-ubuntu-2404
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - task: test
+            command: ./gradlew --no-daemon :app:testDebugUnitTest
+          - task: build
+            command: ./gradlew --no-daemon :app:assembleDebug
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Checkout submodules (retry)
+        run: |
+          set -euo pipefail
+          git submodule sync --recursive
+          for attempt in 1 2 3 4 5; do
+            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
+              exit 0
+            fi
+            echo "Submodule update failed (attempt $attempt/5). Retrying…"
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Setup Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 21
+
+      - name: Setup Android SDK
+        uses: android-actions/setup-android@v3
+        with:
+          accept-android-sdk-licenses: false
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Install Android SDK packages
+        run: |
+          yes | sdkmanager --licenses >/dev/null
+          sdkmanager --install \
+            "platform-tools" \
+            "platforms;android-36" \
+            "build-tools;36.0.0"
+
+      - name: Run Android ${{ matrix.task }}
+        working-directory: apps/android
+        run: ${{ matrix.command }}

.github/workflows/install-smoke.yml

@@ -0,0 +1,33 @@
+name: Install Smoke
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  install-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout CLI
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v3
+        with:
+          version: 10
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Install pnpm deps (minimal)
+        run: pnpm install --ignore-scripts --frozen-lockfile
+
+      - name: Run installer docker tests
+        env:
+          CLAWDBOT_INSTALL_URL: https://clawd.bot/install.sh
+          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

.github/workflows/workflow-sanity.yml

@@ -0,0 +1,37 @@
+name: Workflow Sanity
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  no-tabs:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Fail on tabs in workflow files
+        run: |
+          python - <<'PY'
+          from __future__ import annotations
+
+          import pathlib
+          import sys
+
+          root = pathlib.Path(".github/workflows")
+          bad: list[str] = []
+          for path in sorted(root.rglob("*.yml")):
+            if b"\t" in path.read_bytes():
+              bad.append(str(path))
+
+          for path in sorted(root.rglob("*.yaml")):
+            if b"\t" in path.read_bytes():
+              bad.append(str(path))
+
+          if bad:
+            print("Tabs found in workflow file(s):")
+            for path in bad:
+              print(f"- {path}")
+            sys.exit(1)
+          PY

.gitignore

@@ -1,6 +1,59 @@
 node_modules
 .env
+docker-compose.extra.yml
 dist
+*.bun-build
 pnpm-lock.yaml
+bun.lock
+bun.lockb
 coverage
 .pnpm-store
+.worktrees/
+.DS_Store
+**/.DS_Store
+ui/src/ui/__screenshots__/
+ui/playwright-report/
+ui/test-results/
+
+# Bun build artifacts
+*.bun-build
+apps/macos/.build/
+apps/shared/ClawdbotKit/.build/
+**/ModuleCache/
+bin/
+bin/clawdbot-mac
+bin/docs-list
+apps/macos/.build-local/
+apps/macos/.swiftpm/
+apps/shared/ClawdbotKit/.swiftpm/
+Core/
+apps/ios/*.xcodeproj/
+apps/ios/*.xcworkspace/
+apps/ios/.swiftpm/
+vendor/
+
+# Vendor build artifacts
+vendor/a2ui/renderers/lit/dist/
+.bundle.hash
+
+# fastlane (iOS)
+apps/ios/fastlane/README.md
+apps/ios/fastlane/report.xml
+apps/ios/fastlane/Preview.html
+apps/ios/fastlane/screenshots/
+apps/ios/fastlane/test_output/
+apps/ios/fastlane/logs/
+
+# fastlane build artifacts (local)
+apps/ios/*.ipa
+apps/ios/*.dSYM.zip
+
+# provisioning profiles (local)
+apps/ios/*.mobileprovision
+.env
+
+# Local untracked files
+.local/
+.vscode/
+IDENTITY.md
+USER.md

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "Peekaboo"]
+	path = Peekaboo
+	url = https://github.com/steipete/Peekaboo.git
+	branch = main

.npmrc

@@ -0,0 +1 @@
+allow-build-scripts=@whiskeysockets/baileys,sharp,esbuild,protobufjs,fs-ext,node-pty

.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"
+}

.swiftformat

@@ -0,0 +1,51 @@
+# SwiftFormat configuration adapted from Peekaboo defaults (Swift 6 friendly)
+
+--swiftversion 6.2
+
+# Self handling
+--self insert
+--selfrequired
+
+# Imports / extensions
+--importgrouping testable-bottom
+--extensionacl on-declarations
+
+# Indentation
+--indent 4
+--indentcase false
+--ifdef no-indent
+--xcodeindentation enabled
+
+# Line breaks
+--linebreaks lf
+--maxwidth 120
+
+# Whitespace
+--trimwhitespace always
+--emptybraces no-space
+--nospaceoperators ...,..< 
+--ranges no-space
+--someAny true
+--voidtype void
+
+# Wrapping
+--wraparguments before-first
+--wrapparameters before-first
+--wrapcollections before-first
+--closingparen same-line
+
+# Organization
+--organizetypes class,struct,enum,extension
+--extensionmark "MARK: - %t + %p"
+--marktypes always
+--markextensions always
+--structthreshold 0
+--enumthreshold 0
+
+# Other
+--stripunusedargs closure-only
+--header ignore
+--allman false
+
+# Exclusions
+--exclude .build,.swiftpm,DerivedData,node_modules,dist,coverage,xcuserdata,Peekaboo,Swabble,apps/android,apps/ios,apps/shared,apps/macos/Sources/ClawdisProtocol,apps/macos/Sources/ClawdbotProtocol

.swiftlint.yml

@@ -0,0 +1,148 @@
+# SwiftLint configuration adapted from Peekaboo defaults (Swift 6 friendly)
+
+included:
+  - apps/macos/Sources
+
+excluded:
+  - .build
+  - DerivedData
+  - "**/.build"
+  - "**/.swiftpm"
+  - "**/DerivedData"
+  - "**/Generated"
+  - "**/Resources"
+  - "**/Package.swift"
+  - "**/Tests/Resources"
+  - node_modules
+  - dist
+  - coverage
+  - "*.playground"
+  # Generated (protocol-gen-swift.ts)
+  - apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift
+
+analyzer_rules:
+  - unused_declaration
+  - unused_import
+
+opt_in_rules:
+  - array_init
+  - closure_spacing
+  - contains_over_first_not_nil
+  - empty_count
+  - empty_string
+  - explicit_init
+  - fallthrough
+  - fatal_error_message
+  - first_where
+  - joined_default_parameter
+  - last_where
+  - literal_expression_end_indentation
+  - multiline_arguments
+  - multiline_parameters
+  - operator_usage_whitespace
+  - overridden_super_call
+  - pattern_matching_keywords
+  - private_outlet
+  - prohibited_super_call
+  - redundant_nil_coalescing
+  - sorted_first_last
+  - switch_case_alignment
+  - unneeded_parentheses_in_closure_argument
+  - vertical_parameter_alignment_on_call
+
+disabled_rules:
+  # SwiftFormat handles these
+  - trailing_whitespace
+  - trailing_newline
+  - trailing_comma
+  - vertical_whitespace
+  - indentation_width
+
+  # Style exclusions
+  - explicit_self
+  - identifier_name
+  - file_header
+  - explicit_top_level_acl
+  - explicit_acl
+  - explicit_type_interface
+  - missing_docs
+  - required_deinit
+  - prefer_nimble
+  - quick_discouraged_call
+  - quick_discouraged_focused_test
+  - quick_discouraged_pending_test
+  - anonymous_argument_in_multiline_closure
+  - no_extension_access_modifier
+  - no_grouping_extension
+  - switch_case_on_newline
+  - strict_fileprivate
+  - extension_access_modifier
+  - convenience_type
+  - no_magic_numbers
+  - one_declaration_per_file
+  - vertical_whitespace_between_cases
+  - vertical_whitespace_closing_braces
+  - superfluous_else
+  - number_separator
+  - prefixed_toplevel_constant
+  - opening_brace
+  - trailing_closure
+  - contrasted_opening_brace
+  - sorted_imports
+  - redundant_type_annotation
+  - shorthand_optional_binding
+  - untyped_error_in_catch
+  - file_name
+  - todo
+
+force_cast: warning
+force_try: warning
+
+type_name:
+  min_length:
+    warning: 2
+    error: 1
+  max_length:
+    warning: 60
+    error: 80
+
+function_body_length:
+  warning: 150
+  error: 300
+
+function_parameter_count:
+  warning: 7
+  error: 10
+
+file_length:
+  warning: 1500
+  error: 2500
+  ignore_comment_only_lines: true
+
+type_body_length:
+  warning: 800
+  error: 1200
+
+cyclomatic_complexity:
+  warning: 20
+  error: 120
+
+large_tuple:
+  warning: 4
+  error: 5
+
+nesting:
+  type_level:
+    warning: 4
+    error: 6
+  function_level:
+    warning: 5
+    error: 7
+
+line_length:
+  warning: 120
+  error: 250
+  ignores_comments: true
+  ignores_urls: true
+
+reporter: "xcode"

AGENTS.md

@@ -1,37 +1,141 @@
 # Repository Guidelines
+- Repo: https://github.com/clawdbot/clawdbot
+- GitHub issues: use literal multiline strings or $'...' for newlines; avoid "\\n" escapes in `gh issue create/edit`.
 
 ## Project Structure & Module Organization
-- Source code: `src/` (CLI wiring in `src/cli`, commands in `src/commands`, Twilio in `src/twilio`, Web provider in `src/provider-web.ts`, infra in `src/infra`, media pipeline in `src/media`).
-- Tests: colocated `*.test.ts` plus e2e in `src/cli/relay.e2e.test.ts`.
-- Docs: `docs/` (images, queue, Claude config). Built output lives in `dist/`.
+- Source code: `src/` (CLI wiring in `src/cli`, commands in `src/commands`, web provider in `src/provider-web.ts`, infra in `src/infra`, media pipeline in `src/media`).
+- Tests: colocated `*.test.ts`.
+- Docs: `docs/` (images, queue, Pi config). Built output lives in `dist/`.
+- Plugins/extensions: live under `extensions/*` (workspace packages). Keep plugin-only deps in the extension `package.json`; do not add them to the root `package.json` unless core uses them.
+- Installers served from `https://clawd.bot/*`: live in the sibling repo `../clawd.bot` (`public/install.sh`, `public/install-cli.sh`, `public/install.ps1`).
+
+## Docs Linking (Mintlify)
+- Docs are hosted on Mintlify (docs.clawd.bot).
+- Internal doc links in `docs/**/*.md`: root-relative, no `.md`/`.mdx` (example: `[Config](/configuration)`).
+- Section cross-references: use anchors on root-relative paths (example: `[Hooks](/configuration#hooks)`).
+- When Peter asks for links, reply with full `https://docs.clawd.bot/...` URLs (not root-relative).
+- When you touch docs, end the reply with the `https://docs.clawd.bot/...` URLs you referenced.
+- README (GitHub): keep absolute docs URLs (`https://docs.clawd.bot/...`) so links work on GitHub.
+- Docs content must be generic: no personal device names/hostnames/paths; use placeholders like `user@gateway-host` and “gateway host”.
 
 ## Build, Test, and Development Commands
+- Runtime baseline: Node **22+** (keep Node + Bun paths working).
 - Install deps: `pnpm install`
-- Run CLI in dev: `pnpm warelay ...` (tsx entry) or `pnpm dev` for `src/index.ts`.
+- Also supported: `bun install` (keep `pnpm-lock.yaml` + Bun patching in sync when touching deps/patches).
+- Prefer Bun for TypeScript execution (scripts, dev, tests): `bun <file.ts>` / `bunx <tool>`.
+- 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.
+- Naming: use **Clawdbot** for product/app/docs headings; use `clawdbot` for CLI command, package/binary, paths, and config keys.
 
 ## Testing Guidelines
 - Framework: Vitest with V8 coverage thresholds (70% lines/branches/functions/statements).
 - Naming: match source names with `*.test.ts`; e2e in `*.e2e.test.ts`.
 - Run `pnpm test` (or `pnpm test:coverage`) before pushing when you touch logic.
+- Live tests (real keys): `CLAWDBOT_LIVE_TEST=1 pnpm test:live` (Clawdbot-only) or `LIVE=1 pnpm test:live` (includes provider live tests). Docker: `pnpm test:docker:live-models`, `pnpm test:docker:live-gateway`. Onboarding Docker E2E: `pnpm test:docker:onboard`.
+- Full kit + what’s covered: `docs/testing.md`.
+- Pure test additions/fixes generally do **not** need a changelog entry unless they alter user-facing behavior or the user asks for one.
+- Mobile: before using a simulator, check for connected real devices (iOS + Android) and prefer them when available.
 
 ## Commit & Pull Request Guidelines
+- Create commits with `scripts/committer "<msg>" <file...>`; avoid manual `git add`/`git commit` so staging stays scoped.
 - Follow concise, action-oriented commit messages (e.g., `CLI: add verbose flag to send`).
 - Group related changes; avoid bundling unrelated refactors.
+- Changelog workflow: keep latest released version at top (no `Unreleased`); after publishing, bump version and start a new top section.
 - PRs should summarize scope, note testing performed, and mention any user-facing changes or new flags.
+- PR review flow: when given a PR link, review via `gh pr view`/`gh pr diff` and do **not** change branches.
+- PR merge flow: create a temp branch from `main`, merge the PR branch into it (prefer squash unless commit history is important; use rebase/merge when it is). Always try to merge the PR unless it’s truly difficult, then use another approach. If we squash, add the PR author as a co-contributor. Apply fixes, add changelog entry (include PR # + thanks), run full gate before the final commit, commit, merge back to `main`, delete the temp branch, and end on `main`.
+- When working on a PR: add a changelog entry with the PR number and thank the contributor.
+- When working on an issue: reference the issue in the changelog entry.
+- When merging a PR: leave a PR comment that explains exactly what we did and include the SHA hashes.
+- When merging a PR from a new contributor: add their avatar to the README “Thanks to all clawtributors” thumbnail list.
+- After merging a PR: run `bun scripts/update-clawtributors.ts` if the contributor is missing, then commit the regenerated README.
+
+## Shorthand Commands
+- `sync up`: if working tree is dirty, commit all changes (pick a sensible Conventional Commit message), then `git pull --rebase`; if rebase conflicts and cannot resolve, stop; otherwise `git push`.
+
+### PR Workflow (Review vs Land)
+- **Review mode (PR link only):** read `gh pr view/diff`; **do not** switch branches; **do not** change code.
+- **Landing mode:** create an integration branch from `main`, bring in PR commits (**prefer rebase** for linear history; **merge allowed** when complexity/conflicts make it safer), apply fixes, add changelog (+ thanks + PR #), run full gate **locally before committing** (`pnpm lint && pnpm build && pnpm test`), commit, merge back to `main`, then `git switch main` (never stay on a topic branch after landing). Important: contributor needs to be in git graph after this!
 
 ## Security & Configuration Tips
-- Environment: copy `.env.example`; set Twilio creds and WhatsApp sender (`TWILIO_WHATSAPP_FROM`).
-- Web provider stores creds at `~/.warelay/credentials/`; rerun `warelay login` if logged out.
-- Media hosting relies on Tailscale Funnel when using Twilio; use `warelay webhook --ingress tailscale` or `--serve-media` for local hosting.
+- Web provider stores creds at `~/.clawdbot/credentials/`; rerun `clawdbot login` if logged out.
+- Pi sessions live under `~/.clawdbot/sessions/` by default; the base directory is not configurable.
+- Environment variables: see `~/.profile`.
+- 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 or legacy config/service warnings: run `clawdbot doctor` (see `docs/gateway/doctor.md`).
 
 ## Agent-Specific Notes
-- If the relay is running in tmux (`warelay-relay`), restart it after code changes: kill pane/session and run `pnpm warelay relay --verbose` inside tmux. Check tmux before editing; keep the watcher healthy if you start it.
-- Also read the shared guardrails at `~/Projects/oracle/AGENTS.md` and `~/Projects/agent-scripts/AGENTS.MD` before making changes; align with any cross-repo rules noted there.
+- Vocabulary: "makeup" = "mac app".
+- When working on a GitHub Issue or PR, print the full URL at the end of the task.
+- 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.**
+- macOS logs: use `./scripts/clawlog.sh` (aka `vtlog`) to query unified logs for the Clawdbot subsystem; it supports follow/tail/category filters and expects passwordless sudo for `/usr/bin/log`.
+- If shared guardrails are available locally, review them; otherwise follow this repo's guidance.
+- SwiftUI state management (iOS/macOS): prefer the `Observation` framework (`@Observable`, `@Bindable`) over `ObservableObject`/`@StateObject`; don’t introduce new `ObservableObject` unless required for compatibility, and migrate existing usages when touching related code.
+- Connection providers: when adding a new connection, update every UI surface and docs (macOS app, web UI, mobile if applicable, onboarding/overview docs) and add matching status + configuration forms so provider lists and settings stay in sync.
+- Version locations: `package.json` (CLI), `apps/android/app/build.gradle.kts` (versionName/versionCode), `apps/ios/Sources/Info.plist` + `apps/ios/Tests/Info.plist` (CFBundleShortVersionString/CFBundleVersion), `apps/macos/Sources/Clawdbot/Resources/Info.plist` (CFBundleShortVersionString/CFBundleVersion), `docs/install/updating.md` (pinned npm version), `docs/platforms/mac/release.md` (APP_VERSION/APP_BUILD examples), Peekaboo Xcode projects/Info.plists (MARKETING_VERSION/CURRENT_PROJECT_VERSION).
+- **Restart apps:** “restart iOS/Android apps” means rebuild (recompile/install) and relaunch, not just kill/launch.
+- **Device checks:** before testing, verify connected real devices (iOS/Android) before reaching for simulators/emulators.
+- iOS Team ID lookup: `security find-identity -p codesigning -v` → use Apple Development (…) TEAMID. Fallback: `defaults read com.apple.dt.Xcode IDEProvisioningTeamIdentifiers`.
+- A2UI bundle hash: `src/canvas-host/a2ui/.bundle.hash` is auto-generated; ignore unexpected changes, and only regenerate via `pnpm canvas:a2ui:bundle` (or `scripts/bundle-a2ui.sh`) when needed. Commit the hash as a separate commit.
+- Release signing/notary keys are managed outside the repo; follow internal release docs.
+- Notary auth env vars (`APP_STORE_CONNECT_ISSUER_ID`, `APP_STORE_CONNECT_KEY_ID`, `APP_STORE_CONNECT_API_KEY_P8`) are expected in your environment (per internal release docs).
+- **Multi-agent safety:** do **not** create/apply/drop `git stash` entries unless explicitly requested (this includes `git pull --rebase --autostash`). Assume other agents may be working; keep unrelated WIP untouched and avoid cross-cutting state changes.
+- **Multi-agent safety:** when the user says "push", you may `git pull --rebase` to integrate latest changes (never discard other agents' work). When the user says "commit", scope to your changes only. When the user says "commit all", commit everything in grouped chunks.
+- **Multi-agent safety:** do **not** create/remove/modify `git worktree` checkouts (or edit `.worktrees/*`) unless explicitly requested.
+- **Multi-agent safety:** do **not** switch branches / check out a different branch unless explicitly requested.
+- **Multi-agent safety:** running multiple agents is OK as long as each agent has its own session.
+- **Multi-agent safety:** when you see unrecognized files, keep going; focus on your changes and commit only those.
+- Lobster seam: use the shared CLI palette in `src/terminal/palette.ts` (no hardcoded colors); apply palette to onboarding/config prompts and other TTY UI output as needed.
+- **Multi-agent safety:** focus reports on your edits; avoid guard-rail disclaimers unless truly blocked; when multiple agents touch the same file, continue if safe; end with a brief “other files present” note only if relevant.
+- Bug investigations: read source code of relevant npm dependencies and all related local code before concluding; aim for high-confidence root cause.
+- Code style: add brief comments for tricky logic; keep files under ~500 LOC when feasible (split/refactor as needed).
+- Tool schema guardrails (google-antigravity): avoid `Type.Union` in tool input schemas; no `anyOf`/`oneOf`/`allOf`. Use `stringEnum`/`optionalStringEnum` (Type.Unsafe enum) for string lists, and `Type.Optional(...)` instead of `... | null`. Keep top-level tool schema as `type: "object"` with `properties`.
+- When asked to open a “session” file, open the Pi session logs under `~/.clawdbot/agents/main/sessions/*.jsonl` (newest unless a specific ID is given), not the default `sessions.json`. If logs are needed from another machine, SSH via Tailscale and read the same path there.
+- Menubar dimming + restart flow mirrors Trimmy: use `scripts/restart-mac.sh` (kills all Clawdbot variants, runs `swift build`, packages, relaunches). Icon dimming depends on MenuBarExtraAccess wiring in AppMain; keep `appearsDisabled` updates intact when touching the status item.
+- Do not rebuild the macOS app over SSH; rebuilds must be run directly on the Mac.
+- Never send streaming/partial replies to external messaging surfaces (WhatsApp, Telegram); only final replies should be delivered there. Streaming/tool events may still go to internal UIs/control channel.
+- Voice wake forwarding tips:
+  - Command template should stay `clawdbot-mac agent --message "${text}" --thinking low`; `VoiceWakeForwarder` already shell-escapes `${text}`. Don’t add extra quotes.
+  - launchd PATH is minimal; ensure the app’s launch agent PATH includes standard system paths plus your pnpm bin (typically `$HOME/Library/pnpm`) so `pnpm`/`clawdbot` binaries resolve when invoked via `clawdbot-mac`.
+- For manual `clawdbot message send` messages that include `!`, use the heredoc pattern noted below to avoid the Bash tool’s escaping.
+
+## NPM + 1Password (publish/verify)
+- Use the 1password skill; all `op` commands must run inside a fresh tmux session.
+- Sign in: `eval "$(op signin --account my.1password.com)"` (app unlocked + integration on).
+- OTP: `op read 'op://Private/Npmjs/one-time password?attribute=otp'`.
+- Publish: `npm publish --access public --otp="<otp>"` (run from the package dir).
+- Verify without local npmrc side effects: `npm view <pkg> version --userconfig "$(mktemp)"`.
+- Kill the tmux session after publish.
+
+## Exclamation Mark Escaping Workaround
+The Claude Code Bash tool escapes `!` to `\\!` in command arguments. When using `clawdbot message send` with messages containing exclamation marks, use heredoc syntax:
+
+```bash
+# WRONG - will send "Hello\\!" with backslash
+clawdbot message send --to "+1234" --message 'Hello!'
+
+# CORRECT - use heredoc to avoid escaping
+clawdbot message send --to "+1234" --message "$(cat <<'EOF'
+Hello!
+EOF
+)"
+```
+
+This is a Claude Code quirk, not a clawdbot bug.

CHANGELOG.md

@@ -1,69 +1,545 @@
 # Changelog
 
-## [Unreleased] 1.0.5
+## 2026.1.15 (unreleased)
 
-### Pending
-- (add entries here)
+### Highlights
+- Plugins: add provider auth registry + `clawdbot models auth login` for plugin-driven OAuth/API key flows.
+- Browser: improve remote CDP/Browserless support (auth passthrough, `wss` upgrade, timeouts, clearer errors).
+- Heartbeat: per-agent configuration + 24h duplicate suppression. (#980) — thanks @voidserf.
+- Security: audit warns on weak model tiers; app nodes store auth tokens encrypted (Keychain/SecurePrefs).
 
-## 1.0.4 — 2025-11-25
+### Breaking
+- **BREAKING:** iOS minimum version is now 18.0 to support Textual markdown rendering in native chat. (#702)
+- **BREAKING:** Microsoft Teams is now a plugin; install `@clawdbot/msteams` via `clawdbot plugins install @clawdbot/msteams`.
 
 ### Changes
-- Auto-replies now send a WhatsApp fallback message when a command/Claude run hits the timeout, including up to 800 chars of partial stdout so the user still sees progress.
-- Added tests covering the new timeout fallback behavior and partial-output truncation.
-- Web relay auto-reconnects after Baileys/WebSocket drops (with log-out detection) and exposes close events for monitoring; added tests for close propagation and reconnect loop.
+- CLI: set process titles to `clawdbot-<command>` for clearer process listings.
+- CLI/macOS: sync remote SSH target/identity to config and let `gateway status` auto-infer SSH targets (ssh-config aware).
+- Heartbeat: tighten prompt guidance + suppress duplicate alerts for 24h. (#980) — thanks @voidserf.
+- Repo: ignore local identity files to avoid accidental commits. (#1001) — thanks @gerardward2007.
+- Sessions/Security: add `session.dmScope` for multi-user DM isolation and audit warnings. (#948) — thanks @Alphonse-arianee.
+- Plugins: add provider auth registry + `clawdbot models auth login` for plugin-driven OAuth/API key flows.
+- Onboarding: switch channels setup to a single-select loop with per-channel actions and disabled hints in the picker.
+- TUI: show provider/model labels for the active session and default model.
+- Heartbeat: add per-agent heartbeat configuration and multi-agent docs example.
+- UI: show gateway auth guidance + doc link on unauthorized Control UI connections.
+- Security: warn on weak model tiers (Haiku, below GPT-5, below Claude 4.5) in `clawdbot security audit`.
+- Apps: store node auth tokens encrypted (Keychain/SecurePrefs).
+- Daemon: share profile/state-dir resolution across service helpers and honor `CLAWDBOT_STATE_DIR` for Windows task scripts.
+- Docs: clarify multi-gateway rescue bot guidance. (#969) — thanks @bjesuiter.
+- Agents: add Current Date & Time system prompt section with configurable time format (auto/12/24).
+- Tools: normalize Slack/Discord message timestamps with `timestampMs`/`timestampUtc` while keeping raw provider fields.
+- macOS: add `system.which` for prompt-free remote skill discovery (with gateway fallback to `system.run`).
+- Docs: add Date & Time guide and update prompt/timezone configuration docs.
+- Messages: debounce rapid inbound messages across channels with per-connector overrides. (#971) — thanks @juanpablodlc.
+- Messages: allow media-only sends (CLI/tool) and show Telegram voice recording status for voice notes. (#957) — thanks @rdev.
+- Auth/Status: keep auth profiles sticky per session (rotate on compaction/new), surface provider usage headers in `/status` and `clawdbot models status`, and update docs.
+- CLI: add `--json` output for `clawdbot daemon` lifecycle/install commands.
+- Memory: make `node-llama-cpp` an optional dependency (avoid Node 25 install failures) and improve local-embeddings fallback/errors.
+- Browser: add `snapshot refs=aria` (Playwright aria-ref ids) for self-resolving refs across `snapshot` → `act`.
+- Browser: `profile="chrome"` now defaults to host control and returns clearer “attach a tab” errors.
+- Browser: prefer stable Chrome for auto-detect, with Brave/Edge fallbacks and updated docs. (#983) — thanks @cpojer.
+- Browser: increase remote CDP reachability timeouts + add `remoteCdpTimeoutMs`/`remoteCdpHandshakeTimeoutMs`.
+- Browser: preserve auth/query tokens for remote CDP endpoints and pass Basic auth for CDP HTTP/WS. (#895) — thanks @mukhtharcm.
+- Telegram: add bidirectional reaction support with configurable notifications and agent guidance. (#964) — thanks @bohdanpodvirnyi.
+- Telegram: allow custom commands in the bot menu (merged with native; conflicts ignored). (#860) — thanks @nachoiacovino.
+- Discord: allow allowlisted guilds without channel lists to receive messages when `groupPolicy="allowlist"`. — thanks @thewilloftheshadow.
+- Discord: allow emoji/sticker uploads + channel actions in config defaults. (#870) — thanks @JDIVE.
 
-## 0.1.3 — 2025-11-25
+### Fixes
+- Fix: list model picker entries as provider/model pairs for explicit selection. (#970) — thanks @mcinteerj.
+- Fix: align OpenAI image-gen defaults with DALL-E 3 standard quality and document output formats. (#880) — thanks @mkbehr.
+- Fix: persist `gateway.mode=local` after selecting Local run mode in `clawdbot configure`, even if no other sections are chosen.
+- Daemon: fix profile-aware service label resolution (env-driven) and add coverage for launchd/systemd/schtasks. (#969) — thanks @bjesuiter.
+- Agents: avoid false positives when logging unsupported Google tool schema keywords.
+- Agents: skip Gemini history downgrades for google-antigravity to preserve tool calls. (#894) — thanks @mukhtharcm.
+- Status: restore usage summary line for current provider when no OAuth profiles exist.
+- Fix: guard model fallback against undefined provider/model values. (#954) — thanks @roshanasingh4.
+- Fix: refactor session store updates, add chat.inject, and harden subagent cleanup flow. (#944) — thanks @tyler6204.
+- Fix: clean up suspended CLI processes across backends. (#978) — thanks @Nachx639.
+- Fix: support MiniMax coding plan usage responses with `model_remains`/`current_interval_*` payloads.
+- Fix: suppress WhatsApp pairing replies for historical catch-up DMs on initial link. (#904)
+- Browser: extension mode recovers when only one tab is attached (stale targetId fallback).
+- Browser: fix `tab not found` for extension relay snapshots/actions when Playwright blocks `newCDPSession` (use the single available Page).
+- Browser: upgrade `ws` → `wss` when remote CDP uses `https` (fixes Browserless handshake).
+- Telegram: skip `message_thread_id=1` for General topic sends while keeping typing indicators. (#848) — thanks @azade-c.
+- Fix: sanitize user-facing error text + strip `<final>` tags across reply pipelines. (#975) — thanks @ThomsenDrake.
+- Fix: normalize pairing CLI aliases, allow extension channels, and harden Zalo webhook payload parsing. (#991) — thanks @longmaba.
+- Fix: allow local Tailscale Serve hostnames without treating tailnet clients as direct. (#885) — thanks @oswalpalash.
+- Fix: reset sessions after role-ordering conflicts to recover from consecutive user turns. (#998)
 
-### Features
-- Added `cwd` option to command reply config for setting the working directory where commands execute. Essential for Claude Code to have proper project context.
-- Added configurable file-based logging (default `/tmp/warelay/warelay.log`) with log level set via `logging.level` in `~/.warelay/warelay.json`; verbose still forces debug.
+## 2026.1.14-1
 
-### Developer notes
-- Command auto-replies now pass `{ timeoutMs, cwd }` into the command runner; custom runners/tests that stub `runCommandWithTimeout` should accept the options object as well as the legacy numeric timeout.
+### Highlights
+- Web search: `web_search`/`web_fetch` tools (Brave API) + first-time setup in onboarding/configure.
+- Browser control: Chrome extension relay takeover mode + remote browser control via `clawdbot browser serve`.
+- Plugins: channel plugins (gateway HTTP hooks) + Zalo plugin + onboarding install flow. (#854) — thanks @longmaba.
+- Security: expanded `clawdbot security audit` (+ `--fix`), detect-secrets CI scan, and a `SECURITY.md` reporting policy.
 
-## 0.1.2 — 2025-11-25
+### Changes
+- Docs: clarify per-agent auth stores, sandboxed skill binaries, and elevated semantics.
+- 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.
+- Channels: add Matrix plugin (external) with docs + onboarding hooks.
+- 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.
+- 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`.
 
-### CI/build fix
-- Fixed commander help configuration (`subcommandTerm`) so TypeScript builds pass in CI.
+### Fixes
+- Sessions: refactor session store updates to lock + mutate per-entry, add chat.inject, and harden subagent cleanup flow. (#944) — thanks @tyler6204.
+- Browser: add tests for snapshot labels/efficient query params and labeled image responses.
+- Google: downgrade unsigned thinking blocks before send to avoid missing signature errors.
+- 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: harden Antigravity Claude history/tool-call sanitization. (#968) — thanks @rdev.
+- 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).
 
-## 0.1.1 — 2025-11-25
+## 2026.1.14
 
-### CLI polish
-- Added a proper executable shim so `npx warelay@0.1.x --help` runs the CLI directly.
-- Help/version banner now uses the README tagline with color, and the help footer includes colored examples with short explanations.
-- `send` and `status` gained a `--verbose` flag for consistent noisy output when debugging.
-- Lowercased branding in docs/UA; web provider UA is `warelay/cli/0.1.1`.
+### 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.
+- TUI: show LLM error messages (rate limits, auth, etc.) instead of `(no output)`.
+- Gateway/Dev: ensure `pnpm gateway:dev` always uses the dev profile config + state (`~/.clawdbot-dev`).
+
+#### Agents / Auth / Tools / Sandbox
+- 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.
+- 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.
+- Auth: normalize Claude Code CLI profile mode to oauth and auto-migrate config. (#855) — thanks @sebslight.
+- Embedded runner: suppress raw API error payloads from replies. (#924) — thanks @grp06.
+- Logging: tolerate `EIO` from console writes to avoid gateway crashes. (#925, fixes #878) — thanks @grp06.
+- Sandbox: restore `docker.binds` config validation and preserve configured PATH for `docker exec`. (#873) — thanks @akonyer.
+- Google: downgrade unsigned thinking blocks before send to avoid missing signature errors.
+
+#### macOS / Apps
+- macOS: ensure launchd log directory exists with a test-only override. (#909) — thanks @roshanasingh4.
+- macOS: format ConnectionsStore config to satisfy SwiftFormat lint. (#852) — thanks @mneves75.
+- macOS: pass auth token/password to dashboard URL for authenticated access. (#918) — thanks @rahthakor.
+- macOS: reuse launchd gateway auth and skip wizard when gateway config already exists. (#917)
+- macOS: prefer the default bridge tunnel port in remote mode for node bridge connectivity; document macOS remote control + bridge tunnels. (#960, fixes #865) — thanks @kkarimi.
+- Apps: use canonical main session keys from gateway defaults across macOS/iOS/Android to avoid creating bare `main` sessions.
+- 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.
+- Agents: strip invalid Gemini thought signatures from OpenRouter history to avoid 400s. (#841, #845) — thanks @MatthieuBizien.
+
+## 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. (#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.
+- Testing: update Vitest + browser-playwright to 4.0.17.
+- Docs: add Amazon Bedrock provider notes and link from models/FAQ.
+
+## 2026.1.11
+
+### Highlights
+- Plugins are now first-class: loader + CLI management, plus the new Voice Call plugin.
+- Config: modular `$include` support for split config files. (#731) — thanks @pasogott.
+- Agents/Pi: reserve compaction headroom so pre-compaction memory writes can run before auto-compaction.
+- Agents: automatic pre-compaction memory flush turn to store durable memories before compaction.
+
+### Changes
+- CLI/Onboarding: simplify MiniMax auth choice to a single M2.1 option.
+- CLI: configure section selection now loops until Continue.
+- Docs: explain MiniMax vs MiniMax Lightning (speed vs cost) and restore LM Studio example.
+- Docs: add Cerebras GLM 4.6/4.7 config example (OpenAI-compatible endpoint).
+- Onboarding/CLI: group model/auth choice by provider and label Z.AI as GLM 4.7.
+- Onboarding/Docs: add Moonshot AI (Kimi K2) auth choice + config example.
+- CLI/Onboarding: prompt to reuse detected API keys for Moonshot/MiniMax/Z.AI/Gemini/Anthropic/OpenCode.
+- Auto-reply: add compact `/model` picker (models + available providers) and show provider endpoints in `/model status`.
+- Control UI: add Config tab model presets (MiniMax M2.1, GLM 4.7, Kimi) for one-click setup.
+- Plugins: add extension loader (tools/RPC/CLI/services), discovery paths, and config schema + Control UI labels (uiHints).
+- Plugins: add `clawdbot plugins install` (path/tgz/npm), plus `list|info|enable|disable|doctor` UX.
+- Plugins: voice-call plugin now real (Twilio/log), adds start/status RPC/CLI/tool + tests.
+- Docs: add plugins doc + cross-links from tools/skills/gateway config.
+- Docs: add beginner-friendly plugin quick start + expand Voice Call plugin docs.
+- Tests: add Docker plugin loader + tgz-install smoke test.
+- Tests: extend Docker plugin E2E to cover installing from local folders (`plugins.load.paths`) and `file:` npm specs.
+- Tests: add coverage for pre-compaction memory flush settings.
+- Tests: modernize live model smoke selection for current releases and enforce tools/images/thinking-high coverage. (#769) — thanks @steipete.
+- Agents/Tools: add `apply_patch` tool for multi-file edits (experimental; gated by tools.exec.applyPatch; OpenAI-only).
+- Agents/Tools: rename the bash tool to exec (config alias maintained). (#748) — thanks @myfunc.
+- Agents: add pre-compaction memory flush config (`agents.defaults.compaction.*`) with a soft threshold + system prompt.
+- Config: add `$include` directive for modular config files. (#731) — thanks @pasogott.
+- Build: set pnpm minimum release age to 2880 minutes (2 days). (#718) — thanks @dan-dr.
+- macOS: prompt to install the global `clawdbot` CLI when missing in local mode; install via `clawd.bot/install-cli.sh` (no onboarding) and use external launchd/CLI instead of the embedded gateway runtime.
+- Docs: add gog calendar event color IDs from `gog calendar colors`. (#715) — thanks @mjrussell.
+- Cron/CLI: add `--model` flag to cron add/edit commands. (#711) — thanks @mjrussell.
+- Cron/CLI: trim model overrides on cron edits and document main-session guidance. (#711) — thanks @mjrussell.
+- Skills: bundle `skill-creator` to guide creating and packaging skills.
+- Providers: add per-DM history limit overrides (`dmHistoryLimit`) with provider-level config. (#728) — thanks @pkrmf.
+- Discord: expose channel/category management actions in the message tool. (#730) — thanks @NicholasSpisak.
+- Docs: rename README “macOS app” section to “Apps”. (#733) — thanks @AbhisekBasu1.
+- Gateway: require `client.id` in WebSocket connect params; use `client.instanceId` for presence de-dupe; update docs/tests.
+- macOS: remove the attach-only gateway setting; local mode now always manages launchd while still attaching to an existing gateway if present.
+
+### Installer
+- Postinstall: replace `git apply` with builtin JS patcher (works npm/pnpm/bun; no git dependency) plus regression tests.
+- Postinstall: skip pnpm patch fallback when the new patcher is active.
+- Installer tests: add root+non-root docker smokes, CI workflow to fetch clawd.bot scripts and run install sh/cli with onboarding skipped.
+- Installer UX: support `CLAWDBOT_NO_ONBOARD=1` for non-interactive installs; fix npm prefix on Linux and auto-install git.
+- Installer UX: add `install.sh --help` with flags/env and git install hint.
+- Installer UX: add `--install-method git|npm` and auto-detect source checkouts (prompt to update git checkout vs migrate to npm).
+
+### Fixes
+- Models/Onboarding: configure MiniMax (minimax.io) via Anthropic-compatible `/anthropic` endpoint by default (keep `minimax-api` as a legacy alias).
+- Models: normalize Gemini 3 Pro/Flash IDs to preview names for live model lookups. (#769) — thanks @steipete.
+- CLI: fix guardCancel typing for configure prompts. (#769) — thanks @steipete.
+- Gateway/WebChat: include handshake validation details in the WebSocket close reason for easier debugging; preserve close codes.
+- Gateway/Auth: send invalid connect responses before closing the handshake; stabilize invalid-connect auth test.
+- Gateway: tighten gateway listener detection.
+- Control UI: hide onboarding chat when configured and guard the mobile chat sidebar overlay.
+- Auth: read Codex keychain credentials and make the lookup platform-aware.
+- macOS/Release: avoid bundling dist artifacts in relay builds and generate appcasts from zip-only sources.
+- Doctor: surface plugin diagnostics in the report.
+- Plugins: treat `plugins.load.paths` directory entries as package roots when they contain `package.json` + `clawdbot.extensions`; load plugin packages from config dirs; extract archives without system tar.
+- Config: expand `~` in `CLAWDBOT_CONFIG_PATH` and common path-like config fields (including `plugins.load.paths`); guard invalid `$include` paths. (#731) — thanks @pasogott.
+- Agents: stop pre-creating session transcripts so first user messages persist in JSONL history.
+- Agents: skip pre-compaction memory flush when the session workspace is read-only.
+- Auto-reply: ignore inline `/status` directives unless the message is directive-only.
+- Auto-reply: align `/think` default display with model reasoning defaults. (#751) — thanks @gabriel-trigo.
+- Auto-reply: flush block reply buffers on tool boundaries. (#750) — thanks @sebslight.
+- Auto-reply: allow sender fallback for command authorization when `SenderId` is empty (WhatsApp self-chat). (#755) — thanks @juanpablodlc.
+- Auto-reply: treat whitespace-only sender ids as missing for command authorization (WhatsApp self-chat). (#766) — thanks @steipete.
+- Heartbeat: refresh prompt text for updated defaults.
+- Agents/Tools: use PowerShell on Windows to capture system utility output. (#748) — thanks @myfunc.
+- Docker: tolerate unset optional env vars in docker-setup.sh under strict mode. (#725) — thanks @petradonka.
+- CLI/Update: preserve base environment when passing overrides to update subprocesses. (#713) — thanks @danielz1z.
+- Agents: treat message tool errors as failures so fallback replies still send; require `to` + `message` for `action=send`. (#717) — thanks @theglove44.
+- Agents: preserve reasoning items on tool-only turns.
+- Agents/Subagents: wait for completion before announcing, align wait timeout with run timeout, and make announce prompts more emphatic.
+- Agents: route subagent transcripts to the target agent sessions directory and add regression coverage. (#708) — thanks @xMikeMickelson.
+- Agents/Tools: preserve action enums when flattening tool schemas. (#708) — thanks @xMikeMickelson.
+- Gateway/Agents: canonicalize main session aliases for store writes and add regression coverage. (#709) — thanks @xMikeMickelson.
+- Agents: reset sessions and retry when auto-compaction overflows instead of crashing the gateway.
+- Providers/Telegram: normalize command mentions for consistent parsing. (#729) — thanks @obviyus.
+- Providers: skip DM history limit handling for non-DM sessions. (#728) — thanks @pkrmf.
+- Sandbox: fix non-main mode incorrectly sandboxing the main DM session and align `/status` runtime reporting with effective sandbox state.
+- Sandbox/Gateway: treat `agent:<id>:main` as a main-session alias when `session.mainKey` is customized (backwards compatible).
+- Auto-reply: fast-path allowlisted slash commands (inline `/help`/`/commands`/`/status`/`/whoami` stripped before model).
+
+## 2026.1.10
+
+### Highlights
+- CLI: `clawdbot status` now table-based + shows OS/update/gateway/daemon/agents/sessions; `status --all` adds a full read-only debug report (tables, log tails, Tailscale summary, and scan progress via OSC-9 + spinner).
+- CLI Backends: add Codex CLI fallback with resume support (text output) and JSONL parsing for new runs, plus a live CLI resume probe.
+- CLI: add `clawdbot update` (safe-ish git checkout update) + `--update` shorthand. (#673) — thanks @fm1randa.
+- Gateway: add OpenAI-compatible `/v1/chat/completions` HTTP endpoint (auth, SSE streaming, per-agent routing). (#680).
+
+### Changes
+- Onboarding/Models: add first-class Z.AI (GLM) auth choice (`zai-api-key`) + `--zai-api-key` flag.
+- CLI/Onboarding: add OpenRouter API key auth option in configure/onboard. (#703) — thanks @mteam88.
+- Agents: add human-delay pacing between block replies (modes: off/natural/custom, per-agent configurable). (#446) — thanks @tony-freedomology.
+- Agents/Browser: add `browser.target` (sandbox/host/custom) with sandbox host-control gating via `agents.defaults.sandbox.browser.allowHostControl`, allowlists for custom control URLs/hosts/ports, and expand browser tool docs (remote control, profiles, internals).
+- Onboarding/Models: add catalog-backed default model picker to onboarding + configure. (#611) — thanks @jonasjancarik.
+- Agents/OpenCode Zen: update fallback models + defaults, keep legacy alias mappings. (#669) — thanks @magimetal.
+- CLI: add `clawdbot reset` and `clawdbot uninstall` flows (interactive + non-interactive) plus docker cleanup smoke test.
+- Providers: move provider wiring to a plugin architecture. (#661).
+- Providers: unify group history context wrappers across providers with per-provider/per-account `historyLimit` overrides (fallback to `messages.groupChat.historyLimit`). Set `0` to disable. (#672).
+- Gateway/Heartbeat: optionally deliver heartbeat `Reasoning:` output (`agents.defaults.heartbeat.includeReasoning`). (#690)
+- Docker: allow optional home volume + extra bind mounts in `docker-setup.sh`. (#679) — thanks @gabriel-trigo.
+
+### Fixes
+- Auto-reply: suppress draft/typing streaming for `NO_REPLY` (silent system ops) so it doesn’t leak partial output.
+- CLI/Status: expand tables to full terminal width; clarify provider setup vs runtime warnings; richer per-provider detail; token previews in `status` while keeping `status --all` redacted; add troubleshooting link footer; keep log tails pasteable; show gateway auth used when reachable; surface provider runtime errors (Signal/iMessage/Slack); harden `tailscale status --json` parsing; make `status --all` scan progress determinate; and replace the footer with a 3-line “Next steps” recommendation (share/debug/probe).
+- CLI/Gateway: clarify that `clawdbot gateway status` reports RPC health (connect + RPC) and shows RPC failures separately from connect failures.
+- CLI/Update: gate progress spinner on stdout TTY and align clean-check step label. (#701) — thanks @bjesuiter.
+- Telegram: add `/whoami` + `/id` commands to reveal sender id for allowlists; allow `@username` and prefixed ids in `allowFrom` prompts (with stability warning).
+- Heartbeat: strip markup-wrapped `HEARTBEAT_OK` so acks don’t leak to external providers (e.g., Telegram).
+- Control UI: stop auto-writing `telegram.groups["*"]` and warn/confirm before enabling wildcard groups.
+- WhatsApp: send ack reactions only for handled messages and ignore legacy `messages.ackReaction` (doctor copies to `whatsapp.ackReaction`). (#629) — thanks @pasogott.
+- Sandbox/Skills: mirror skills into sandbox workspaces for read-only mounts so SKILL.md stays accessible.
+- Terminal/Table: ANSI-safe wrapping to prevent table clipping/color loss; add regression coverage.
+- Docker: allow optional apt packages during image build and document the build arg. (#697) — thanks @gabriel-trigo.
+- Gateway/Heartbeat: deliver reasoning even when the main heartbeat reply is `HEARTBEAT_OK`. (#694) — thanks @antons.
+- Agents/Pi: inject config `temperature`/`maxTokens` into streaming without replacing the session streamFn; cover with live maxTokens probe. (#732) — thanks @peschee.
+- macOS: clear unsigned launchd overrides on signed restarts and warn via doctor when attach-only/disable markers are set. (#695) — thanks @jeffersonwarrior.
+- Agents: enforce single-writer session locks and drop orphan tool results to prevent tool-call ID failures (MiniMax/Anthropic-compatible APIs).
+- Docs: make `clawdbot status` the first diagnostic step, clarify `status --deep` behavior, and document `/whoami` + `/id`.
+- Docs/Testing: clarify live tool+image probes and how to list your testable `provider/model` ids.
+- Tests/Live: make gateway bash+read probes resilient to provider formatting while still validating real tool calls.
+- WhatsApp: detect @lid mentions in groups using authDir reverse mapping + resolve self JID E.164 for mention gating. (#692) — thanks @peschee.
+- Gateway/Auth: default to token auth on loopback during onboarding, add doctor token generation flow, and tighten audio transcription config to Whisper-only.
+- Providers: dedupe inbound messages across providers to avoid duplicate LLM runs on redeliveries/reconnects. (#689) — thanks @adam91holt.
+- Agents: strip `<thought>`/`<antthinking>` tags from hidden reasoning output and cover tag variants in tests. (#688) — thanks @theglove44.
+- macOS: save model picker selections as normalized provider/model IDs and keep manual entries aligned. (#683) — thanks @benithors.
+- Agents: recognize "usage limit" errors as rate limits for failover. (#687) — thanks @evalexpr.
+- CLI: avoid success message when daemon restart is skipped. (#685) — thanks @carlulsoe.
+- Commands: disable `/config` + `/debug` by default; gate via `commands.config`/`commands.debug` and hide from native registration/help output.
+- Agents/System: clarify that sub-agents remain sandboxed and cannot use elevated host access.
+- Gateway: disable the OpenAI-compatible `/v1/chat/completions` endpoint by default; enable via `gateway.http.endpoints.chatCompletions.enabled=true`.
+- macOS: stabilize bridge tunnels, guard invoke senders on disconnect, and drain stdout/stderr to avoid deadlocks. (#676) — thanks @ngutman.
+- Agents/System: clarify sandboxed runtime in system prompt and surface elevated availability when sandboxed.
+- Auto-reply: prefer `RawBody` for command/directive parsing (WhatsApp + Discord) and prevent fallback runs from clobbering concurrent session updates. (#643) — thanks @mcinteerj.
+- WhatsApp: fix group reactions by preserving message IDs and sender JIDs in history; normalize participant phone numbers to JIDs in outbound reactions. (#640) — thanks @mcinteerj.
+- WhatsApp: expose group participant IDs to the model so reactions can target the right sender.
+- Cron: `wakeMode: "now"` waits for heartbeat completion (and retries when the main lane is busy). (#666) — thanks @roshanasingh4.
+- Agents/OpenAI: fix Responses tool-only → follow-up turn handling (avoid standalone `reasoning` items that trigger 400 “required following item”) and replay reasoning items in Responses/Codex Responses history for tool-call-only turns.
+- Sandbox: add `clawdbot sandbox explain` (effective policy inspector + fix-it keys); improve “sandbox jail” tool-policy/elevated errors with actionable config key paths; link to docs.
+- Hooks/Gmail: keep Tailscale serve path at `/` while preserving the public path. (#668) — thanks @antons.
+- Hooks/Gmail: allow Tailscale target URLs to preserve internal serve paths.
+- Auth: update Claude Code keychain credentials in-place during refresh sync; share JSON file helpers; add CLI fallback coverage.
+- Auth: throttle external CLI credential syncs (Claude/Codex), reduce Keychain reads, and skip sync when cached credentials are still fresh.
+- CLI: respect `CLAWDBOT_STATE_DIR` for node pairing + voice wake settings storage. (#664) — thanks @azade-c.
+- Onboarding/Gateway: persist non-interactive gateway token auth in config; add WS wizard + gateway tool-calling regression coverage.
+- Gateway/Control UI: make `chat.send` non-blocking, wire Stop to `chat.abort`, and treat `/stop` as an out-of-band abort. (#653)
+- Gateway/Control UI: allow `chat.abort` without `runId` (abort active runs), suppress post-abort chat streaming, and prune stuck chat runs. (#653)
+- Gateway/Control UI: sniff image attachments for chat.send, drop non-images, and log mismatches. (#670) — thanks @cristip73.
+- macOS: force `restart-mac.sh --sign` to require identities and keep bundled Node signed for relay verification. (#580) — thanks @jeffersonwarrior.
+- Gateway/Agent: accept image attachments on `agent` (multimodal message) and add live gateway image probe (`CLAWDBOT_LIVE_GATEWAY_IMAGE_PROBE=1`).
+- CLI: `clawdbot sessions` now includes `elev:*` + `usage:*` flags in the table output.
+- CLI/Pairing: accept positional provider for `pairing list|approve` (npm-run compatible); update docs/bot hints.
+- Branding: normalize user-facing “ClawdBot”/“CLAWDBOT” → “Clawdbot” (CLI, status, docs).
+- Auto-reply: fix native `/model` not updating the actual chat session (Telegram/Slack/Discord). (#646)
+- Doctor: offer to run `clawdbot update` first on git installs (keeps doctor output aligned with latest).
+- Doctor: avoid false legacy workspace warning when install dir is `~/clawdbot`. (#660)
+- iMessage: fix reasoning persistence across DMs; avoid partial/duplicate replies when reasoning is enabled. (#655) — thanks @antons.
+- Models/Auth: allow MiniMax API configs without `models.providers.minimax.apiKey` (auth profiles / `MINIMAX_API_KEY`). (#656) — thanks @mneves75.
+- Agents: avoid duplicate replies when the message tool sends. (#659) — thanks @mickahouan.
+- Agents: harden Cloud Code Assist tool ID sanitization (toolUse/toolCall/toolResult) and scrub extra JSON Schema constraints. (#665) — thanks @sebslight.
+- Agents: sanitize tool results + Cloud Code Assist tool IDs at context-build time (prevents mid-run strict-provider request rejects).
+- Agents/Tools: resolve workspace-relative Read/Write/Edit paths; align bash default cwd. (#642) — thanks @mukhtharcm.
+- Discord: include forwarded message snapshots in agent session context. (#667) — thanks @rubyrunsstuff.
+- Telegram: add `telegram.draftChunk` to tune draft streaming chunking for `streamMode: "block"`. (#667) — thanks @rubyrunsstuff.
+- Tests/Agents: add regression coverage for workspace tool path resolution and bash cwd defaults.
+- iOS/Android: enable stricter concurrency/lint checks; fix Swift 6 strict concurrency issues + Android lint errors (ExifInterface, obsolete SDK check). (#662) — thanks @KristijanJovanovski.
+- Auth: read Codex CLI keychain tokens on macOS before falling back to `~/.codex/auth.json`, preventing stale refresh tokens from breaking gateway live tests.
+- iOS/macOS: share `AsyncTimeout`, require explicit `bridgeStableID` on connect, and harden tool display defaults (avoids missing-resource label fallbacks).
+- Telegram: serialize media-group processing to avoid missed albums under load.
+- Signal: handle `dataMessage.reaction` events (signal-cli SSE) to avoid broken attachment errors. (#637) — thanks @neist.
+- Docs: showcase entries for ParentPay, R2 Upload, iOS TestFlight, and Oura Health. (#650) — thanks @henrino3.
+- Agents: repair session transcripts by dropping duplicate tool results across the whole history (unblocks Anthropic-compatible APIs after retries).
+- Tests/Live: reset the gateway session between model runs to avoid cross-provider transcript incompatibilities (notably OpenAI Responses reasoning replay rules).
 
 
-## 0.1.0 — 2025-11-25
+## 2026.1.9
 
-### CLI & Providers
-- Bundles a single `warelay` CLI with commands for `send`, `relay`, `status`, `webhook`, `login`, and tmux helpers `relay:tmux` / `relay:tmux:attach` (see `src/cli/program.ts`); `webhook` accepts `--ingress tailscale|none`.
-- Supports two messaging backends: **Twilio** (default) and **personal WhatsApp Web**; `relay --provider auto` selects Web when a cached login exists, otherwise falls back to Twilio polling (`provider-web.ts`, `cli/program.ts`).
-- `send` can target either provider, optionally wait for delivery status (Twilio only), output JSON, dry-run payloads, and attach media (`commands/send.ts`).
-- `status` merges inbound + outbound Twilio traffic with formatted lines or JSON output (`commands/status.ts`, `twilio/messages.ts`).
+### Highlights
+- Microsoft Teams provider: polling, attachments, outbound CLI send, per-channel policy.
+- Models/Auth expansion: OpenCode Zen + MiniMax API onboarding; token auth profiles + auth order; OAuth health in doctor/status.
+- CLI/Gateway UX: message subcommands, gateway discover/status/SSH, /config + /debug, sandbox CLI.
+- Provider reliability sweep: WhatsApp contact cards/targets, Telegram audio-as-voice + streaming, Signal reactions, Slack threading, Discord stability.
+- Auto-reply + status: block-streaming controls, reasoning handling, usage/cost reporting.
+- Control UI/TUI: queued messages, session links, reasoning view, mobile polish, logs UX.
 
-### Webhook, Funnel & Port Management
-- `webhook` starts an Express server for inbound Twilio callbacks, logs requests, and optionally auto-replies with static text or config-driven replies (`twilio/webhook.ts`, `commands/webhook.ts`).
-- `webhook --ingress tailscale` automates end-to-end webhook setup: ensures required binaries, enables Tailscale Funnel, starts the webhook on the chosen port/path, discovers the WhatsApp sender SID, and updates Twilio webhook URLs with multiple fallbacks (`commands/up.ts`, `infra/tailscale.ts`, `twilio/update-webhook.ts`, `twilio/senders.ts`).
-- Guardrails detect busy ports with helpful diagnostics and aborts when conflicts are found (`infra/ports.ts`).
+### Breaking
+- CLI: `clawdbot message` now subcommands (`message send|poll|...`) and requires `--provider` unless only one provider configured.
+- Commands/Tools: `/restart` and gateway restart tool disabled by default; enable with `commands.restart=true`.
 
-### Auto-Reply Engine
-- Configurable via `~/.warelay/warelay.json` (JSON5) with allowlist support, text or command-driven replies, templating (`{{Body}}`, `{{From}}`, `{{MediaPath}}`, etc.), optional body prefixes, and per-sender or global conversation sessions with `/new` resets and idle expiry (`auto-reply/reply.ts`, `config/config.ts`, `config/sessions.ts`, `auto-reply/templating.ts`).
-- Command replies run through a process-wide FIFO queue to avoid concurrent executions across webhook, poller, and web listener flows (`process/command-queue.ts`); verbose mode surfaces wait times.
-- Claude CLI integration auto-injects identity, output-format flags, session args, and parses JSON output while preserving metadata (`auto-reply/claude.ts`, `auto-reply/reply.ts`).
-- Typing indicators fire before replies for Twilio, and Web provider sends “composing/available” presence when possible (`twilio/typing.ts`, `provider-web.ts`).
+### New Features and Changes
+- Models/Auth: OpenCode Zen onboarding (#623) — thanks @magimetal; MiniMax Anthropic-compatible API + hosted onboarding (#590, #495) — thanks @mneves75, @tobiasbischoff.
+- Models/Auth: setup-token + token auth profiles; `clawdbot models auth order {get,set,clear}`; per-agent auth candidates in `/model status`; OAuth expiry checks in doctor/status.
+- Agent/System: claude-cli runner; `session_status` tool (and sandbox allow); adaptive context pruning default; system prompt messaging guidance + no auto self-update; eligible skills list injection; sub-agent context trimmed.
+- Commands: `/commands` list; `/models` alias; `/usage` alias; `/debug` runtime overrides + effective config view; `/config` chat updates + `/config get`; `config --section`.
+- CLI/Gateway: unified message tool + message subcommands; gateway discover (local + wide-area DNS-SD) with JSON/timeout; gateway status human-readable + JSON + SSH loopback; wide-area records include gatewayPort/sshPort/cliPath + tailnet DNS fallback.
+- CLI UX: logs output modes (pretty/plain/JSONL) + colorized health/daemon output; global `--no-color`; lobster palette in onboarding/config.
+- Dev ergonomics: gateway `--dev/--reset` + dev profile auto-config; C-3PO dev templates; dev gateway/TUI helper scripts.
+- Sandbox/Workspace: sandbox list/recreate commands; sync skills into sandbox workspace; sandbox browser auto-start.
+- Config/Onboarding: inline env vars; OpenAI API key flow to shared `~/.clawdbot/.env`; Opus 4.5 default prompt for Anthropic auth; QuickStart auto-install gateway (Node-only) + provider picker tweaks + skip-systemd flags; TUI bootstrap prompt (`tui --message`); remove Bun runtime choice.
+- Providers: Microsoft Teams provider (polling, attachments, outbound sends, requireMention, config reload/DM policy). (#404) — thanks @onutc
+- Providers: WhatsApp broadcast groups for multi-agent replies (#547) — thanks @pasogott; inbound media size cap configurable (#505) — thanks @koala73; identity-based message prefixes (#578) — thanks @p6l-richard.
+- Providers: Telegram inline keyboard buttons + callback payload routing (#491) — thanks @azade-c; cron topic delivery targets (#474/#478) — thanks @mitschabaude-bot, @nachoiacovino; `[[audio_as_voice]]` tag support (#490) — thanks @jarvis-medmatic.
+- Providers: Signal reactions + notifications with allowlist support.
+- Status/Usage: /status cost reporting + `/cost` lines; auth profile snippet; provider usage windows.
+- Control UI: mobile responsiveness (#558) — thanks @carlulsoe; queued messages + Enter-to-send (#527) — thanks @YuriNachos; session links (#471) — thanks @HazAT; reasoning view; skill install feedback (#445) — thanks @pkrmf; chat layout refresh (#475) — thanks @rahthakor; docs link + new session button; drop explicit `ui:install`.
+- TUI: agent picker + agents list RPC; improved status line.
+- Doctor/Daemon: audit/repair flows, permissions checks, supervisor config audits; provider status probes + warnings for Discord intents and Telegram privacy; last activity timestamps; gateway restart guidance.
+- Docs: Hetzner Docker VPS guide + cross-links (#556/#592) — thanks @Iamadig; Ansible guide (#545) — thanks @pasogott; provider troubleshooting index; hook parameter expansion (#532) — thanks @mcinteerj; model allowlist notes; OAuth deep dive; showcase refresh.
+- Apps/Branding: refreshed iOS/Android/macOS icons (#521) — thanks @fishfisher.
 
-### Media Pipeline
-- `send --media` works on both providers: Web accepts local paths or URLs; Twilio requires HTTPS and transparently hosts local files (≤5 MB) via the Funnel/webhook media endpoint, auto-spawning a short-lived media server when `--serve-media` is requested (`commands/send.ts`, `media/host.ts`, `media/server.ts`).
-- Auto-replies may include `mediaUrl` from config or command output (`MEDIA:` token extraction) and will host local media when needed before sending (`auto-reply/reply.ts`, `media/parse.ts`, `media/host.ts`).
-- Inbound media from Twilio or Web is downloaded to `~/.warelay/media` with TTL cleanup and passed to commands via `MediaPath`/`MediaType` for richer prompts (`twilio/webhook.ts`, `provider-web.ts`, `media/store.ts`).
+### Fixes
+- Packaging: include MS Teams send module in npm tarball.
+- Sandbox/Browser: auto-start CDP endpoint; proxy CDP out of container for attachOnly; relax Bun fetch typing; align sandbox list output with config images.
+- Agents/Runtime: gate heartbeat prompt to default sessions; /stop aborts between tool calls; require explicit system-event session keys; guard small context windows; fix model fallback stringification; sessions_spawn inherits provider; failover on billing/credits; respect auth cooldown ordering; restore Anthropic OAuth tool dispatch + tool-name bypass; avoid OpenAI invalid reasoning replay; harden Gmail hook model defaults.
+- Agent history/schema: strip/skip empty assistant/error blocks to prevent session corruption/Claude 400s; scrub unsupported JSON Schema keywords + sanitize tool call IDs for Cloud Code Assist; simplify Gemini-compatible tool/session schemas; require raw for config.apply.
+- Auto-reply/Streaming: default audioAsVoice false; preserve audio_as_voice propagation + buffer audio blocks + guard voice notes; block reply ordering (timeout) + forced-block fence-safe; avoid chunk splits inside parentheses + fence-close breaks + invalid UTF-16 truncation; preserve inline directive spacing + allow whitespace in reply tags; filter NO_REPLY prefixes + normalize routed replies; suppress <think> leakage with separate Reasoning; block streaming defaults (off by default, minChars/idle tuning) + coalesced blocks; dedupe followup queue; restore explicit responsePrefix default.
+- Status/Commands: provider prefix in /status model display; usage filtering + provider mapping; auth label + usage snapshots (claude-cli fallback + optional claude.ai); show Verbose/Elevated only when enabled; compact usage/cost line + restore emoji-rich status; /status in directive-only + multi-directive handling; mention-bypass elevated handling; surface provider usage errors; wire /usage to /status; restore hidden gateway-daemon alias; fallback /model list when catalog unavailable.
+- WhatsApp: vCard/contact cards (prefer FN, include numbers, show all contacts, keep summary counts, better empty summaries); preserve group JIDs + normalize targets; resolve @lid mappings/JIDs (Baileys/auth-dir) + inbound mapping; route queued replies to sender; improve web listener errors + remove provider name from errors; record outbound activity account id; fix web media fetch errors; broadcast group history consistency.
+- Telegram: keep streamMode draft-only; long-poll conflict retries + update dedupe; grammY fetch mismatch fixes + restrict native fetch to Bun; suppress getUpdates stack traces; include user id in pairing; audio_as_voice handling fixes.
+- Discord/Slack: thread context helpers + forum thread starters; avoid category parent overrides; gateway reconnect logs + HELLO timeout + stop provider after reconnect exhaustion; DM recipient parsing for numeric IDs; remove incorrect limited warning; reply threading + mrkdwn edge cases; remove ack reactions after reply; gateway debug event visibility.
+- Signal: reaction handling safety; own-reaction matching (uuid+phone); UUID-only senders accepted; ignore reaction-only messages.
+- MS Teams: download image attachments reliably; fix top-level replies; stop on shutdown + honor chunk limits; normalize poll providers/deps; pairing label fixes.
+- iMessage: isolate group-ish threads by chat_id.
+- Gateway/Daemon/Doctor: atomic config writes; repair gateway service entrypoint + install switches; non-interactive legacy migrations; systemd unit alignment + KillMode=process; node bridge keepalive/pings; Launch at Login persistence; bundle ClawdbotKit resources + Swift 6.2 compat dylib; relay version check + remove smoke test; regen Swift GatewayModels + keep agent provider string; cron jobId alias + channel alias migration + main session key normalization; heartbeat Telegram accountId resolution; avoid WhatsApp fallback for internal runs; gateway listener error wording; serveBaseUrl param; honor gateway --dev; fix wide-area discovery updates; align agents.defaults schema; provider account metadata in daemon status; refresh Carbon patch for gateway fixes; restore doctor prompter initialValue handling.
+- Control UI/TUI: persist per-session verbose off + hide tool cards; logs tab opens at bottom; relative asset paths + landing cleanup; session labels lookup/persistence; stop pinning main session in recents; start logs at bottom; TUI status bar refresh + timeout handling + hide reasoning label when off.
+- Onboarding/Configure: QuickStart single-select provider picker; avoid Codex CLI false-expiry warnings; clarify WhatsApp owner prompt; fix Minimax hosted onboarding (agents.defaults + msteams heartbeat target); remove configure Control UI prompt; honor gateway --dev flag.
 
-### Relay & Monitoring
-- `relay` polls Twilio on an interval with exponential-backoff resilience, auto-replying to inbound messages, or listens live via WhatsApp Web with automatic read receipts and presence updates (`cli/program.ts`, `twilio/monitor.ts`, `provider-web.ts`).
-- `send` + `waitForFinalStatus` polls Twilio until a terminal delivery state (delivered/read) or timeout, with clear failure surfaces (`twilio/send.ts`).
+### Maintenance
+- Dependencies: bump pi-* stack to 0.42.2.
+- Dependencies: Pi 0.40.0 bump (#543) — thanks @mcinteerj.
+- Build: Docker build cache layer (#605) — thanks @zknicker.
 
-### Developer & Ops Ergonomics
-- `relay:tmux` helper restarts/attaches to a dedicated `warelay-relay` tmux session for long-running relays (`cli/relay_tmux.ts`).
-- Environment validation enforces Twilio credentials early and supports either auth token or API key/secret pairs (`env.ts`).
-- Shared logging utilities, binary checks, and runtime abstractions keep CLI output consistent (`globals.ts`, `logger.ts`, `infra/binaries.ts`).
+- 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
+
+### Highlights
+- Security: DMs locked down by default across providers; pairing-first + allowlist guidance.
+- Sandbox: per-agent scope defaults + workspace access controls; tool/session isolation tuned.
+- Agent loop: compaction, pruning, streaming, and error handling hardened.
+- Providers: Telegram/WhatsApp/Discord/Slack reliability, threading, reactions, media, and retries improved.
+- Control UI: logs tab, streaming stability, focus mode, and large-output rendering fixes.
+- CLI/Gateway/Doctor: daemon/logs/status, auth migration, and diagnostics significantly expanded.
+
+### Breaking
+- **SECURITY (update ASAP):** inbound DMs are now **locked down by default** on Telegram/WhatsApp/Signal/iMessage/Discord/Slack.
+  - Previously, if you didn’t configure an allowlist, your bot could be **open to anyone** (especially discoverable Telegram bots).
+  - New default: DM pairing (`dmPolicy="pairing"` / `discord.dm.policy="pairing"` / `slack.dm.policy="pairing"`).
+  - To keep old “open to everyone” behavior: set `dmPolicy="open"` and include `"*"` in the relevant `allowFrom` (Discord/Slack: `discord.dm.allowFrom` / `slack.dm.allowFrom`).
+  - Approve requests via `clawdbot pairing list <provider>` + `clawdbot pairing approve <provider> <code>`.
+- Sandbox: default `agent.sandbox.scope` to `"agent"` (one container/workspace per agent). Use `"session"` for per-session isolation; `"shared"` disables cross-session isolation.
+- Timestamps in agent envelopes are now UTC (compact `YYYY-MM-DDTHH:mmZ`); removed `messages.timestampPrefix`. Add `agent.userTimezone` to tell the model the user’s local time (system prompt only).
+- Model config schema changes (auth profiles + model lists); doctor auto-migrates and the gateway rewrites legacy configs on startup.
+- Commands: gate all slash commands to authorized senders; add `/compact` to manually compact session context.
+- Groups: `whatsapp.groups`, `telegram.groups`, and `imessage.groups` now act as allowlists when set. Add `"*"` to keep allow-all behavior.
+- Auto-reply: removed `autoReply` from Discord/Slack/Telegram channel configs; use `requireMention` instead (Telegram topics now support `requireMention` overrides).
+- CLI: remove `update`, `gateway-daemon`, `gateway {install|uninstall|start|stop|restart|daemon status|wake|send|agent}`, and `telegram` commands; move `login/logout` to `providers login/logout` (top-level aliases hidden); use `daemon` for service control, `send`/`agent`/`wake` for RPC, and `nodes canvas` for canvas ops.
+
+### Fixes
+- **CLI/Gateway/Doctor:** daemon runtime selection + improved logs/status/health/errors; auth/password handling for local CLI; richer close/timeout details; auto-migrate legacy config/sessions/state; integrity checks + repair prompts; `--yes`/`--non-interactive`; `--deep` gateway scans; better restart/service hints.
+- **Agent loop + compaction:** compaction/pruning tuning, overflow handling, safer bootstrap context, and per-provider threading/confirmations; opt-in tool-result pruning + compact tracking.
+- **Sandbox + tools:** per-agent sandbox overrides, workspaceAccess controls, session tool visibility, tool policy overrides, process isolation, and tool schema/timeout/reaction unification.
+- **Providers (Telegram/WhatsApp/Discord/Slack/Signal/iMessage):** retry/backoff, threading, reactions, media groups/attachments, mention gating, typing behavior, and error/log stability; long polling + forum topic isolation for Telegram.
+- **Gateway/CLI UX:** `clawdbot logs`, cron list colors/aliases, docs search, agents list/add/delete flows, status usage snapshots, runtime/auth source display, and `/status`/commands auth unification.
+- **Control UI/Web:** logs tab, focus mode polish, config form resilience, streaming stability, tool output caps, windowed chat history, and reconnect/password URL auth.
+- **macOS/Android/TUI/Build:** macOS gateway races, QR bundling, JSON5 config safety, Voice Wake hardening; Android EXIF rotation + APK naming/versioning; TUI key handling; tooling/bundling fixes.
+- **Packaging/compat:** npm dist folder coverage, Node 25 qrcode-terminal import fixes, Bun/Playwright/WebSocket patches, and Docker Bun install.
+- **Docs:** new FAQ/ClawdHub/config examples/showcase entries and clarified auth, sandbox, and systemd docs.
+
+### Maintenance
+- Skills additions (Himalaya email, CodexBar, 1Password).
+- Dependency refreshes (pi-* stack, Slack SDK, discord-api-types, file-type, zod, Biome, Vite).
+- Refactors: centralized group allowlist/mention policy; lint/import cleanup; switch tsx → bun for TS execution.
+
+## 2026.1.5
+
+### Highlights
+- Models: add image-specific model config (`agent.imageModel` + fallbacks) and scan support.
+- Agent tools: new `image` tool routed to the image model (when configured).
+- Config: default model shorthands (`opus`, `sonnet`, `gpt`, `gpt-mini`, `gemini`, `gemini-flash`).
+- Docs: document built-in model shorthands + precedence (user config wins).
+- Bun: optional local install/build workflow without maintaining a Bun lockfile (see `docs/bun.md`).
+
+### Fixes
+- Control UI: render Markdown in tool result cards.
+- Control UI: prevent overlapping action buttons in Discord guild rules on narrow layouts.
+- Android: tapping the foreground service notification brings the app to the front. (#179) — thanks @Syhids
+- Cron tool uses `id` for update/remove/run/runs (aligns with gateway params). (#180) — thanks @adamgall
+- Control UI: chat view uses page scroll with sticky header/sidebar and fixed composer (no inner scroll frame).
+- macOS: treat location permission as always-only to avoid iOS-only enums. (#165) — thanks @Nachx639
+- macOS: make generated gateway protocol models `Sendable` for Swift 6 strict concurrency. (#195) — thanks @andranik-sahakyan
+- macOS: bundle QR code renderer modules so DMG gateway boot doesn't crash on missing qrcode-terminal vendor files.
+- macOS: parse JSON5 config safely to avoid wiping user settings when comments are present.
+- WhatsApp: suppress typing indicator during heartbeat background tasks. (#190) — thanks @mcinteerj
+- WhatsApp: mark offline history sync messages as read without auto-reply. (#193) — thanks @mcinteerj
+- Discord: avoid duplicate replies when a provider emits late streaming `text_end` events (OpenAI/GPT).
+- CLI: use tailnet IP for local gateway calls when bind is tailnet/auto (fixes #176).
+- Env: load global `$CLAWDBOT_STATE_DIR/.env` (`~/.clawdbot/.env`) as a fallback after CWD `.env`.
+- Env: optional login-shell env fallback (opt-in; imports expected keys without overriding existing env).
+- Agent tools: OpenAI-compatible tool JSON Schemas (fix `browser`, normalize union schemas).
+- Onboarding: when running from source, auto-build missing Control UI assets (`bun run ui:build`).
+- Discord/Slack: route reaction + system notifications to the correct session (no main-session bleed).
+- Agent tools: honor `agent.tools` allow/deny policy even when sandbox is off.
+- Discord: avoid duplicate replies when OpenAI emits repeated `message_end` events.
+- Commands: unify /status (inline) and command auth across providers; group bypass for authorized control commands; remove Discord /clawd slash handler.
+- CLI: run `clawdbot agent` via the Gateway by default; use `--local` to force embedded mode.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing to Clawdbot
+
+Welcome to the lobster tank! 🦞
+
+## Quick Links
+- **GitHub:** https://github.com/clawdbot/clawdbot
+- **Discord:** https://discord.gg/qkhbAGHRBT
+- **X/Twitter:** [@steipete](https://x.com/steipete) / [@clawdbot](https://x.com/clawdbot)
+
+## Maintainers
+
+- **Peter Steinberger** - Benevolent Dictator
+  - GitHub: [@steipete](https://github.com/steipete) · X: [@steipete](https://x.com/steipete)
+
+- **Shadow** - Discord + Slack subsystem
+  - 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)
+
+## How to Contribute
+1. **Bugs & small fixes** → Open a PR!
+2. **New features / architecture** → Start a [GitHub Discussion](https://github.com/clawdbot/clawdbot/discussions) or ask in Discord first
+3. **Questions** → Discord #setup-help
+
+## Before You PR
+- Test locally with your Clawdbot instance
+- Run linter: `npm run lint`
+- Keep PRs focused (one thing per PR)
+- Describe what & why
+
+## AI/Vibe-Coded PRs Welcome! 🤖
+
+Built with Codex, Claude, or other AI tools? **Awesome - just mark it!**
+
+Please include in your PR:
+- [ ] Mark as AI-assisted in the PR title or description
+- [ ] Note the degree of testing (untested / lightly tested / fully tested)
+- [ ] Include prompts or session logs if possible (super helpful!)
+- [ ] Confirm you understand what the code does
+
+AI PRs are first-class citizens here. We just want transparency so reviewers know what to look for.

Dockerfile

@@ -0,0 +1,33 @@
+FROM node:22-bookworm
+
+# Install Bun (required for build scripts)
+RUN curl -fsSL https://bun.sh/install | bash
+ENV PATH="/root/.bun/bin:${PATH}"
+
+RUN corepack enable
+
+WORKDIR /app
+
+ARG CLAWDBOT_DOCKER_APT_PACKAGES=""
+RUN if [ -n "$CLAWDBOT_DOCKER_APT_PACKAGES" ]; then \
+      apt-get update && \
+      DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends $CLAWDBOT_DOCKER_APT_PACKAGES && \
+      apt-get clean && \
+      rm -rf /var/lib/apt/lists/* /var/cache/apt/archives/*; \
+    fi
+
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
+COPY ui/package.json ./ui/package.json
+COPY patches ./patches
+COPY scripts ./scripts
+
+RUN pnpm install --frozen-lockfile
+
+COPY . .
+RUN pnpm build
+RUN pnpm ui:install
+RUN pnpm ui:build
+
+ENV NODE_ENV=production
+
+CMD ["node", "dist/index.js"]

Dockerfile.sandbox

@@ -0,0 +1,16 @@
+FROM debian:bookworm-slim
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends \
+    bash \
+    ca-certificates \
+    curl \
+    git \
+    jq \
+    python3 \
+    ripgrep \
+  && rm -rf /var/lib/apt/lists/*
+
+CMD ["sleep", "infinity"]

Dockerfile.sandbox-browser

@@ -0,0 +1,28 @@
+FROM debian:bookworm-slim
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends \
+    bash \
+    ca-certificates \
+    chromium \
+    curl \
+    fonts-liberation \
+    fonts-noto-color-emoji \
+    git \
+    jq \
+    novnc \
+    python3 \
+    socat \
+    websockify \
+    x11vnc \
+    xvfb \
+  && rm -rf /var/lib/apt/lists/*
+
+COPY scripts/sandbox-browser-entrypoint.sh /usr/local/bin/clawdbot-sandbox-browser
+RUN chmod +x /usr/local/bin/clawdbot-sandbox-browser
+
+EXPOSE 9222 5900 6080
+
+CMD ["clawdbot-sandbox-browser"]

README.md

@@ -1,151 +1,496 @@
-# 📡 warelay — Send, receive, and auto-reply on WhatsApp.
+# 🦞 Clawdbot — Personal AI Assistant
 
 <p align="center">
-  <img src="README-header.png" alt="warelay header" width="640">
+  <img src="https://raw.githubusercontent.com/clawdbot/clawdbot/main/docs/whatsapp-clawd.jpg" alt="Clawdbot" width="400">
 </p>
 
 <p align="center">
-  <a href="https://github.com/steipete/warelay/actions/workflows/ci.yml?branch=main"><img src="https://img.shields.io/github/actions/workflow/status/steipete/warelay/ci.yml?branch=main&style=for-the-badge" alt="CI status"></a>
-  <a href="https://www.npmjs.com/package/warelay"><img src="https://img.shields.io/npm/v/warelay.svg?style=for-the-badge" alt="npm version"></a>
+  <strong>EXFOLIATE! EXFOLIATE!</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/clawdbot/clawdbot/actions/workflows/ci.yml?branch=main"><img src="https://img.shields.io/github/actions/workflow/status/clawdbot/clawdbot/ci.yml?branch=main&style=for-the-badge" alt="CI status"></a>
+  <a href="https://github.com/clawdbot/clawdbot/releases"><img src="https://img.shields.io/github/v/release/clawdbot/clawdbot?include_prereleases&style=for-the-badge" alt="GitHub release"></a>
+  <a href="https://discord.gg/clawd"><img src="https://img.shields.io/discord/1456350064065904867?label=Discord&logo=discord&logoColor=white&color=5865F2&style=for-the-badge" alt="Discord"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge" alt="MIT License"></a>
 </p>
 
-Send, receive, auto-reply, and inspect WhatsApp messages over **Twilio** or your personal **WhatsApp Web** session. Ships with a one-command webhook setup (Tailscale Funnel + Twilio callback) and a configurable auto-reply engine (plain text or command/Claude driven).
+**Clawdbot** is a *personal AI assistant* you run on your own devices.
+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.
 
-## Quick Start (pick your engine)
-Install from npm (global): `npm install -g warelay` (Node 22+). Then choose **one** path:
+If you want a personal, single-user assistant that feels local, fast, and always-on, this is it.
 
-**A) Personal WhatsApp Web (preferred: no Twilio creds, fastest setup)**
-1. Link your account: `warelay login` (scan the QR).
-2. Send a message: `warelay send --to +12345550000 --message "Hi from warelay"` (add `--provider web` if you want to force the web session).
-3. Stay online & auto-reply: `warelay relay --verbose` (defaults to Web when logged in, falls back to Twilio otherwise).
+[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)
 
-**B) Twilio WhatsApp number (for delivery status + webhooks)**
-1. Copy `.env.example` → `.env`; set `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN` **or** `TWILIO_API_KEY`/`TWILIO_API_SECRET`, and `TWILIO_WHATSAPP_FROM=whatsapp:+19995550123` (optional `TWILIO_SENDER_SID`).
-2. Send a message: `warelay send --to +12345550000 --message "Hi from warelay"`.
-3. Receive replies:
-   - Polling (no ingress): `warelay relay --provider twilio --interval 5 --lookback 10`
-   - Webhook + public URL via Tailscale Funnel: `warelay webhook --ingress tailscale --port 42873 --path /webhook/whatsapp --verbose`
+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)
 
-> Already developing locally? You can still run `pnpm install` and `pnpm warelay ...` from the repo, but end users only need the npm package.
+**Subscriptions (OAuth):**
+- **[Anthropic](https://www.anthropic.com/)** (Claude Pro/Max)
+- **[OpenAI](https://openai.com/)** (ChatGPT/Codex)
 
-## Main Features
-- **Two providers:** Twilio (default) for reliable delivery + status; Web provider for quick personal sends/receives via QR login.
-- **Auto-replies:** Static templates or external commands (Claude-aware), with per-sender or global sessions and `/new` resets.
-- Claude setup guide: see `docs/claude-config.md` for the exact Claude CLI configuration we support.
-- **Webhook in one go:** `warelay webhook --ingress tailscale` enables Tailscale Funnel, runs the webhook server, and updates the Twilio sender callback URL.
-- **Polling fallback:** `relay` polls Twilio when webhooks aren’t available; works headless.
-- **Status + delivery tracking:** `status` shows recent inbound/outbound; `send` can wait for final Twilio status.
+Model note: while any model is supported, I strongly recommend **Anthropic Pro/Max (100/200) + Opus 4.5** for long‑context strength and better prompt‑injection resistance. See [Onboarding](https://docs.clawd.bot/start/onboarding).
 
-## Command Cheat Sheet
-| Command | What it does | Core flags |
-| --- | --- | --- |
-| `warelay send` | Send a WhatsApp message (Twilio or Web) | `--to <e164>` `--message <text>` `--wait <sec>` `--poll <sec>` `--provider twilio\|web` `--json` `--dry-run` `--verbose` |
-| `warelay relay` | Auto-reply loop (poll Twilio or listen on Web) | `--provider <auto\|twilio\|web>` `--interval <sec>` `--lookback <min>` `--verbose` |
-| `warelay status` | Show recent sent/received messages | `--limit <n>` `--lookback <min>` `--json` `--verbose` |
-| `warelay webhook` | Run inbound webhook (`ingress=tailscale` updates Twilio; `none` is local-only) | `--ingress tailscale\|none` `--port <port>` `--path <path>` `--reply <text>` `--verbose` `--yes` `--dry-run` |
-| `warelay login` | Link personal WhatsApp Web via QR | `--verbose` |
+## Models (selection + auth)
 
-### Sending images
-- Twilio: `warelay send --to +1... --message "Hi" --media ./pic.jpg --serve-media` (needs `warelay webhook --ingress tailscale` or `--serve-media` to auto-host via Funnel; max 5 MB).
-- Web: `warelay send --provider web --media ./pic.jpg --message "Hi"` (local path or URL; no hosting needed).
-- Auto-replies can attach `mediaUrl` in `~/.warelay/warelay.json` (used alongside `text` when present).
+- Models config + CLI: [Models](https://docs.clawd.bot/concepts/models)
+- Auth profile rotation (OAuth vs API keys) + fallbacks: [Model failover](https://docs.clawd.bot/concepts/model-failover)
 
-## Providers
-- **Twilio (default):** needs `.env` creds + WhatsApp-enabled number; supports delivery tracking, polling, webhooks, and auto-reply typing indicators.
-- **Web (`--provider web`):** uses your personal WhatsApp via Baileys; supports send/receive + auto-reply, but no delivery-status wait; cache lives in `~/.warelay/credentials/` (rerun `login` if logged out).
-- **Auto-select (`relay` only):** `--provider auto` uses Web when logged in, otherwise Twilio polling.
+## Install (recommended)
 
-Best practice: use a dedicated WhatsApp account (separate SIM/eSIM or business account) for automation instead of your primary personal account to avoid unexpected logouts or rate limits.
+Runtime: **Node ≥22**.
+
+```bash
+npm install -g clawdbot@latest
+# or: pnpm add -g clawdbot@latest
+
+clawdbot onboard --install-daemon
+```
+
+The wizard installs the Gateway daemon (launchd/systemd user service) so it stays running.
+
+## Quick start (TL;DR)
+
+Runtime: **Node ≥22**.
+
+Full beginner guide (auth, pairing, channels): [Getting started](https://docs.clawd.bot/start/getting-started)
+
+```bash
+clawdbot onboard --install-daemon
+
+clawdbot gateway --port 18789 --verbose
+
+# Send a message
+clawdbot message send --to +1234567890 --message "Hello from Clawdbot"
+
+# Talk to the assistant (optionally deliver back to WhatsApp/Telegram/Slack/Discord/Microsoft Teams)
+clawdbot agent --message "Ship checklist" --thinking high
+```
+
+Upgrading? [Updating guide](https://docs.clawd.bot/install/updating) (and run `clawdbot doctor`).
+
+## From source (development)
+
+Prefer `pnpm` for builds from source. Bun is optional for running TypeScript directly.
+
+```bash
+git clone https://github.com/clawdbot/clawdbot.git
+cd clawdbot
+
+pnpm install
+pnpm ui:build # auto-installs UI deps on first run
+pnpm build
+
+pnpm clawdbot onboard --install-daemon
+
+# Dev loop (auto-reload on TS changes)
+pnpm gateway:watch
+```
+
+Note: `pnpm clawdbot ...` runs TypeScript directly (via `tsx`). `pnpm build` produces `dist/` for running via Node / the packaged `clawdbot` binary.
+
+## Security defaults (DM access)
+
+Clawdbot connects to real messaging surfaces. Treat inbound DMs as **untrusted input**.
+
+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"` / `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, 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.
+- **[Companion apps](https://docs.clawd.bot/platforms/macos)** — macOS menu bar app + iOS/Android [nodes](https://docs.clawd.bot/nodes).
+- **[Onboarding](https://docs.clawd.bot/start/wizard) + [skills](https://docs.clawd.bot/tools/skills)** — wizard-driven setup with bundled/managed/workspace skills.
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=clawdbot/clawdbot&type=date&legend=top-left)](https://www.star-history.com/#clawdbot/clawdbot&type=date&legend=top-left)
+
+## Everything we built so far
+
+### Core platform
+- [Gateway WS control plane](https://docs.clawd.bot/gateway) with sessions, presence, config, cron, webhooks, [Control UI](https://docs.clawd.bot/web), and [Canvas host](https://docs.clawd.bot/platforms/mac/canvas#canvas-a2ui).
+- [CLI surface](https://docs.clawd.bot/tools/agent-send): gateway, agent, send, [wizard](https://docs.clawd.bot/start/wizard), and [doctor](https://docs.clawd.bot/gateway/doctor).
+- [Pi agent runtime](https://docs.clawd.bot/concepts/agent) in RPC mode with tool streaming and block streaming.
+- [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).
+
+### 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.
+- [iOS node](https://docs.clawd.bot/platforms/ios): [Canvas](https://docs.clawd.bot/platforms/mac/canvas), [Voice Wake](https://docs.clawd.bot/nodes/voicewake), [Talk Mode](https://docs.clawd.bot/nodes/talk), camera, screen recording, Bonjour pairing.
+- [Android node](https://docs.clawd.bot/platforms/android): [Canvas](https://docs.clawd.bot/platforms/mac/canvas), [Talk Mode](https://docs.clawd.bot/nodes/talk), camera, screen recording, optional SMS.
+- [macOS node mode](https://docs.clawd.bot/nodes): system.run/notify + canvas/camera exposure.
+
+### Tools + automation
+- [Browser control](https://docs.clawd.bot/tools/browser): dedicated clawd Chrome/Chromium, snapshots, actions, uploads, profiles.
+- [Canvas](https://docs.clawd.bot/platforms/mac/canvas): [A2UI](https://docs.clawd.bot/platforms/mac/canvas#canvas-a2ui) push/reset, eval, snapshot.
+- [Nodes](https://docs.clawd.bot/nodes): camera snap/clip, screen record, [location.get](https://docs.clawd.bot/nodes/location-command), notifications.
+- [Cron + wakeups](https://docs.clawd.bot/automation/cron-jobs); [webhooks](https://docs.clawd.bot/automation/webhook); [Gmail Pub/Sub](https://docs.clawd.bot/automation/gmail-pubsub).
+- [Skills platform](https://docs.clawd.bot/tools/skills): bundled, managed, and workspace skills with install gating + UI.
+
+### Runtime + safety
+- [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/channels/troubleshooting).
+
+### Ops + packaging
+- [Control UI](https://docs.clawd.bot/web) + [WebChat](https://docs.clawd.bot/web/webchat) served directly from the Gateway.
+- [Tailscale Serve/Funnel](https://docs.clawd.bot/gateway/tailscale) or [SSH tunnels](https://docs.clawd.bot/gateway/remote) with token/password auth.
+- [Nix mode](https://docs.clawd.bot/install/nix) for declarative config; [Docker](https://docs.clawd.bot/install/docker)-based installs.
+- [Doctor](https://docs.clawd.bot/gateway/doctor) migrations, [logging](https://docs.clawd.bot/logging).
+
+## How it works (short)
+
+```
+WhatsApp / Telegram / Slack / Discord / Signal / iMessage / Microsoft Teams / WebChat
+               │
+               ▼
+┌───────────────────────────────┐
+│            Gateway            │
+│       (control plane)         │
+│     ws://127.0.0.1:18789      │
+└──────────────┬────────────────┘
+               │
+               ├─ Pi agent (RPC)
+               ├─ CLI (clawdbot …)
+               ├─ WebChat UI
+               ├─ macOS app
+               └─ iOS / Android nodes
+```
+
+## Key subsystems
+
+- **[Gateway WebSocket network](https://docs.clawd.bot/concepts/architecture)** — single WS control plane for clients, tools, and events (plus ops: [Gateway runbook](https://docs.clawd.bot/gateway)).
+- **[Tailscale exposure](https://docs.clawd.bot/gateway/tailscale)** — Serve/Funnel for the Gateway dashboard + WS (remote access: [Remote](https://docs.clawd.bot/gateway/remote)).
+- **[Browser control](https://docs.clawd.bot/tools/browser)** — clawd‑managed Chrome/Chromium with CDP control.
+- **[Canvas + A2UI](https://docs.clawd.bot/platforms/mac/canvas)** — agent‑driven visual workspace (A2UI host: [Canvas/A2UI](https://docs.clawd.bot/platforms/mac/canvas#canvas-a2ui)).
+- **[Voice Wake](https://docs.clawd.bot/nodes/voicewake) + [Talk Mode](https://docs.clawd.bot/nodes/talk)** — always‑on speech and continuous conversation.
+- **[Nodes](https://docs.clawd.bot/nodes)** — Canvas, camera snap/clip, screen record, `location.get`, notifications, plus macOS‑only `system.run`/`system.notify`.
+
+## Tailscale access (Gateway dashboard)
+
+Clawdbot can auto-configure Tailscale **Serve** (tailnet-only) or **Funnel** (public) while the Gateway stays bound to loopback. Configure `gateway.tailscale.mode`:
+
+- `off`: no Tailscale automation (default).
+- `serve`: tailnet-only HTTPS via `tailscale serve` (uses Tailscale identity headers by default).
+- `funnel`: public HTTPS via `tailscale funnel` (requires shared password auth).
+
+Notes:
+- `gateway.bind` must stay `loopback` when Serve/Funnel is enabled (Clawdbot enforces this).
+- Serve can be forced to require a password by setting `gateway.auth.mode: "password"` or `gateway.auth.allowTailscale: false`.
+- Funnel refuses to start unless `gateway.auth.mode: "password"` is set.
+- Optional: `gateway.tailscale.resetOnExit` to undo Serve/Funnel on shutdown.
+
+Details: [Tailscale guide](https://docs.clawd.bot/gateway/tailscale) · [Web surfaces](https://docs.clawd.bot/web)
+
+## Remote Gateway (Linux is great)
+
+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 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.
+
+Details: [Remote access](https://docs.clawd.bot/gateway/remote) · [Nodes](https://docs.clawd.bot/nodes) · [Security](https://docs.clawd.bot/gateway/security)
+
+## macOS permissions via the Gateway protocol
+
+The macOS app can run in **node mode** and advertises its capabilities + permission map over the Gateway WebSocket (`node.list` / `node.describe`). Clients can then execute local actions via `node.invoke`:
+
+- `system.run` runs a local command and returns stdout/stderr/exit code; set `needsScreenRecording: true` to require screen-recording permission (otherwise you’ll get `PERMISSION_MISSING`).
+- `system.notify` posts a user notification and fails if notifications are denied.
+- `canvas.*`, `camera.*`, `screen.record`, and `location.get` are also routed via `node.invoke` and follow TCC permission status.
+
+Elevated bash (host permissions) is separate from macOS TCC:
+
+- Use `/elevated on|off` to toggle per‑session elevated access when enabled + allowlisted.
+- Gateway persists the per‑session toggle via `sessions.patch` (WS method) alongside `thinkingLevel`, `verboseLevel`, `model`, `sendPolicy`, and `groupActivation`.
+
+Details: [Nodes](https://docs.clawd.bot/nodes) · [macOS app](https://docs.clawd.bot/platforms/macos) · [Gateway protocol](https://docs.clawd.bot/concepts/architecture)
+
+## Agent to Agent (sessions_* tools)
+
+- Use these to coordinate work across sessions without jumping between chat surfaces.
+- `sessions_list` — discover active sessions (agents) and their metadata.
+- `sessions_history` — fetch transcript logs for a session.
+- `sessions_send` — message another session; optional reply‑back ping‑pong + announce step (`REPLY_SKIP`, `ANNOUNCE_SKIP`).
+
+Details: [Session tools](https://docs.clawd.bot/concepts/session-tool)
+
+## Skills registry (ClawdHub)
+
+ClawdHub is a minimal skill registry. With ClawdHub enabled, the agent can search for skills automatically and pull in new ones as needed.
+
+[ClawdHub](https://ClawdHub.com)
+
+## Chat commands
+
+Send these in WhatsApp/Telegram/Slack/Microsoft Teams/WebChat (group commands are owner-only):
+
+- `/status` — compact session status (model + tokens, cost when available)
+- `/new` or `/reset` — reset the session
+- `/compact` — compact session context (summary)
+- `/think <level>` — off|minimal|low|medium|high|xhigh (GPT-5.2 + Codex models only)
+- `/verbose on|off`
+- `/cost on|off` — append per-response token/cost usage lines
+- `/restart` — restart the gateway (owner-only in groups)
+- `/activation mention|always` — group activation toggle (groups only)
+
+## Apps (optional)
+
+The Gateway alone delivers a great experience. All apps are optional and add extra features.
+
+If you plan to build/run companion apps, initialize submodules first:
+
+```bash
+git submodule update --init --recursive
+./scripts/restart-mac.sh
+```
+
+### macOS (Clawdbot.app) (optional)
+
+- Menu bar control for the Gateway and health.
+- Voice Wake + push-to-talk overlay.
+- WebChat + debug tools.
+- Remote gateway control over SSH.
+
+Note: signed builds required for macOS permissions to stick across rebuilds (see `docs/mac/permissions.md`).
+
+### iOS node (optional)
+
+- Pairs as a node via the Bridge.
+- Voice trigger forwarding + Canvas surface.
+- Controlled via `clawdbot nodes …`.
+
+Runbook: [iOS connect](https://docs.clawd.bot/platforms/ios).
+
+### Android node (optional)
+
+- Pairs via the same Bridge + pairing flow as iOS.
+- Exposes Canvas, Camera, and Screen capture commands.
+- Runbook: [Android connect](https://docs.clawd.bot/platforms/android).
+
+## Agent workspace + skills
+
+- Workspace root: `~/clawd` (configurable via `agents.defaults.workspace`).
+- Injected prompt files: `AGENTS.md`, `SOUL.md`, `TOOLS.md`.
+- Skills: `~/clawd/skills/<skill>/SKILL.md`.
 
 ## Configuration
 
-### Environment (.env)
-| Variable | Required | Description |
-| --- | --- | --- |
-| `TWILIO_ACCOUNT_SID` | Yes (Twilio provider) | Twilio Account SID |
-| `TWILIO_AUTH_TOKEN` | Yes* | Auth token (or use API key/secret) |
-| `TWILIO_API_KEY` | Yes* | API key if not using auth token |
-| `TWILIO_API_SECRET` | Yes* | API secret paired with `TWILIO_API_KEY` |
-| `TWILIO_WHATSAPP_FROM` | Yes (Twilio provider) | WhatsApp-enabled sender, e.g. `whatsapp:+19995550123` |
-| `TWILIO_SENDER_SID` | Optional | Overrides auto-discovery of the sender SID |
-
-(*Provide either auth token OR api key/secret.)
-
-### Auto-reply config (`~/.warelay/warelay.json`, JSON5)
-- Controls who is allowed to trigger replies (`allowFrom`), reply mode (`text` or `command`), templates, and session behavior.
-- Example (Claude command):
+Minimal `~/.clawdbot/clawdbot.json` (model + defaults):
 
 ```json5
 {
-  inbound: {
-    allowFrom: ["+12345550000"],
-    reply: {
-      mode: "command",
-      bodyPrefix: "You are a concise WhatsApp assistant.\n\n",
-      command: ["claude", "--dangerously-skip-permissions", "{{BodyStripped}}"],
-      claudeOutputFormat: "text",
-      session: { scope: "per-sender", resetTriggers: ["/new"], idleMinutes: 60 }
+  agent: {
+    model: "anthropic/claude-opus-4-5"
+  }
+}
+```
+
+[Full configuration reference (all keys + examples).](https://docs.clawd.bot/gateway/configuration)
+
+## Security model (important)
+
+- **Default:** tools run on the host for the **main** session, so the agent has full access when it’s just you.
+- **Group/channel safety:** set `agents.defaults.sandbox.mode: "non-main"` to run **non‑main sessions** (groups/channels) inside per‑session Docker sandboxes; bash then runs in Docker for those sessions.
+- **Sandbox defaults:** allowlist `bash`, `process`, `read`, `write`, `edit`, `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`; denylist `browser`, `canvas`, `nodes`, `cron`, `discord`, `gateway`.
+
+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/channels/whatsapp)
+
+- 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/channels/telegram)
+
+- 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
+{
+  channels: {
+    telegram: {
+      botToken: "123456:ABCDEF"
     }
   }
 }
 ```
 
-### Logging (optional)
-- File logs are written to `/tmp/warelay/warelay.log` by default. Levels: `silent | fatal | error | warn | info | debug | trace` (CLI `--verbose` forces `debug`). Web-provider inbound/outbound entries include message bodies and auto-reply text for easier auditing.
-- Override in `~/.warelay/warelay.json`:
+### [Slack](https://docs.clawd.bot/channels/slack)
+
+- Set `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` (or `channels.slack.botToken` + `channels.slack.appToken`).
+
+### [Discord](https://docs.clawd.bot/channels/discord)
+
+- 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
 {
-  logging: {
-    level: "warn",
-    file: "/tmp/warelay/custom.log"
+  channels: {
+    discord: {
+      token: "1234abcd"
+    }
   }
 }
 ```
 
-### Claude CLI setup (how we run it)
-1) Install the official Claude CLI (e.g., `brew install anthropic-ai/cli/claude` or follow the Anthropic docs) and run `claude login` so it can read your API key.
-2) In `warelay.json`, set `reply.mode` to `"command"` and point `command[0]` to `"claude"`; set `claudeOutputFormat` to `"text"` (or `"json"`/`"stream-json"` if you want warelay to parse and trim the JSON output).
-3) (Optional) Add `bodyPrefix` to inject a system prompt and `session` settings to keep multi-turn context (`/new` resets by default).
-4) Run `pnpm warelay relay --provider auto` (or `--provider web|twilio`) and send a WhatsApp message; warelay will queue the Claude call, stream typing indicators (Twilio provider), parse the result, and send back the text.
+### [Signal](https://docs.clawd.bot/channels/signal)
 
-### Auto-reply parameter table (compact)
-| Key | Type & default | Notes |
-| --- | --- | --- |
-| `inbound.allowFrom` | `string[]` (default: empty) | E.164 numbers allowed to trigger auto-reply (no `whatsapp:`). |
-| `inbound.reply.mode` | `"text"` \| `"command"` (default: —) | Reply style. |
-| `inbound.reply.text` | `string` (default: —) | Used when `mode=text`; templating supported. |
-| `inbound.reply.command` | `string[]` (default: —) | Argv for `mode=command`; each element templated. Stdout (trimmed) is sent. |
-| `inbound.reply.template` | `string` (default: —) | Injected as argv[1] (prompt prefix) before the body. |
-| `inbound.reply.bodyPrefix` | `string` (default: —) | Prepended to `Body` before templating (great for system prompts). |
-| `inbound.reply.timeoutSeconds` | `number` (default: `600`) | Command timeout. |
-| `inbound.reply.claudeOutputFormat` | `"text"`\|`"json"`\|`"stream-json"` (default: —) | When command starts with `claude`, auto-adds `--output-format` + `-p/--print` and trims reply text. |
-| `inbound.reply.session.scope` | `"per-sender"`\|`"global"` (default: `per-sender`) | Session bucket for conversation memory. |
-| `inbound.reply.session.resetTriggers` | `string[]` (default: `["/new"]`) | Exact match or prefix (`/new hi`) resets session. |
-| `inbound.reply.session.idleMinutes` | `number` (default: `60`) | Session expires after idle period. |
-| `inbound.reply.session.store` | `string` (default: `~/.warelay/sessions.json`) | Custom session store path. |
-| `inbound.reply.session.sessionArgNew` | `string[]` (default: `["--session-id","{{SessionId}}"]`) | Args injected for a new session run. |
-| `inbound.reply.session.sessionArgResume` | `string[]` (default: `["--resume","{{SessionId}}"]`) | Args for resumed sessions. |
-| `inbound.reply.session.sessionArgBeforeBody` | `boolean` (default: `true`) | Place session args before final body arg. |
+- Requires `signal-cli` and a `channels.signal` config section.
 
-Templating tokens: `{{Body}}`, `{{BodyStripped}}`, `{{From}}`, `{{To}}`, `{{MessageSid}}`, plus `{{SessionId}}` and `{{IsNewSession}}` when sessions are enabled.
+### [iMessage](https://docs.clawd.bot/channels/imessage)
 
-## Webhook & Tailscale Flow
-- `warelay webhook --ingress none` starts the local Express server on your chosen port/path; add `--reply "Got it"` for a static reply when no config file is present.
-- `warelay webhook --ingress tailscale` enables Tailscale Funnel, prints the public URL (`https://<tailnet-host><path>`), starts the webhook, discovers the WhatsApp sender SID, and updates Twilio callbacks to the Funnel URL.
-- If Funnel is not allowed on your tailnet, the CLI exits with guidance; you can still use `relay --provider twilio` to poll without webhooks.
+- macOS only; Messages must be signed in.
+- If `channels.imessage.groups` is set, it becomes a group allowlist; include `"*"` to allow all.
 
-## Troubleshooting Tips
-- Send/receive issues: run `pnpm warelay status --limit 20 --lookback 240 --json` to inspect recent traffic.
-- Auto-reply not firing: ensure sender is in `allowFrom` (or unset), and confirm `.env` + `warelay.json` are loaded (reload shell after edits).
-- Web provider dropped: rerun `pnpm warelay login`; credentials live in `~/.warelay/credentials/`.
-- Tailscale Funnel errors: update tailscale/tailscaled; check admin console that Funnel is enabled for this device.
+### [Microsoft Teams](https://docs.clawd.bot/channels/msteams)
 
-## FAQ & Safety
-- Twilio errors: **63016 “permission to send an SMS has not been enabled”** → ensure your number is WhatsApp-enabled; **63007 template not approved** → send a free-form session message within 24h or use an approved template; **63112 policy violation** → adjust content, shorten to <1600 chars, avoid links that trigger spam filters. Re-run `pnpm warelay status` to see the exact Twilio response body.
-- Does this store my messages? warelay only writes `~/.warelay/warelay.json` (config), `~/.warelay/credentials/` (WhatsApp Web auth), and `~/.warelay/sessions.json` (session IDs + timestamps). It does **not** persist message bodies beyond the session store. Logs stream to stdout/stderr and also `/tmp/warelay/warelay.log` (configurable via `logging.file`).
-- Personal WhatsApp safety: Automation on personal accounts can be rate-limited or logged out by WhatsApp. Use `--provider web` sparingly, keep messages human-like, and re-run `login` if the session is dropped.
-- Limits to remember: WhatsApp text limit ~1600 chars; avoid rapid bursts—space sends by a few seconds; keep webhook replies under a couple seconds for good UX; command auto-replies time out after 600s by default.
-- Deploy / keep running: Use `tmux` or `screen` for ad-hoc (`tmux new -s warelay -- pnpm warelay relay --provider twilio`). For long-running hosts, wrap `pnpm warelay relay ...` or `pnpm warelay webhook --ingress tailscale ...` in a systemd service or macOS LaunchAgent; ensure environment variables are loaded in that context.
-- Rotating credentials: Update `.env` (Twilio keys), rerun your process; for Web provider, delete `~/.warelay/credentials/` and rerun `pnpm warelay login` to relink.
+- 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"`.
+
+### [WebChat](https://docs.clawd.bot/web/webchat)
+
+- Uses the Gateway WebSocket; no separate WebChat port/config.
+
+Browser control (optional):
+
+```json5
+{
+  browser: {
+    enabled: true,
+    controlUrl: "http://127.0.0.1:18791",
+    color: "#FF4500"
+  }
+}
+```
+
+## Docs
+
+Use these when you’re past the onboarding flow and want the deeper reference.
+- [Start with the docs index for navigation and “what’s where.”](https://docs.clawd.bot)
+- [Read the architecture overview for the gateway + protocol model.](https://docs.clawd.bot/concepts/architecture)
+- [Use the full configuration reference when you need every key and example.](https://docs.clawd.bot/gateway/configuration)
+- [Run the Gateway by the book with the operational runbook.](https://docs.clawd.bot/gateway)
+- [Learn how the Control UI/Web surfaces work and how to expose them safely.](https://docs.clawd.bot/web)
+- [Understand remote access over SSH tunnels or tailnets.](https://docs.clawd.bot/gateway/remote)
+- [Follow the onboarding wizard flow for a guided setup.](https://docs.clawd.bot/start/wizard)
+- [Wire external triggers via the webhook surface.](https://docs.clawd.bot/automation/webhook)
+- [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/channels/troubleshooting)
+- [Review security guidance before exposing anything.](https://docs.clawd.bot/gateway/security)
+
+## Advanced docs (discovery + control)
+
+- [Discovery + transports](https://docs.clawd.bot/gateway/discovery)
+- [Bonjour/mDNS](https://docs.clawd.bot/gateway/bonjour)
+- [Gateway pairing](https://docs.clawd.bot/gateway/pairing)
+- [Remote gateway README](https://docs.clawd.bot/gateway/remote-gateway-readme)
+- [Control UI](https://docs.clawd.bot/web/control-ui)
+- [Dashboard](https://docs.clawd.bot/web/dashboard)
+
+## Operations & troubleshooting
+
+- [Health checks](https://docs.clawd.bot/gateway/health)
+- [Gateway lock](https://docs.clawd.bot/gateway/gateway-lock)
+- [Background process](https://docs.clawd.bot/gateway/background-process)
+- [Browser troubleshooting (Linux)](https://docs.clawd.bot/tools/browser-linux-troubleshooting)
+- [Logging](https://docs.clawd.bot/logging)
+
+## Deep dives
+
+- [Agent loop](https://docs.clawd.bot/concepts/agent-loop)
+- [Presence](https://docs.clawd.bot/concepts/presence)
+- [TypeBox schemas](https://docs.clawd.bot/concepts/typebox)
+- [RPC adapters](https://docs.clawd.bot/reference/rpc)
+- [Queue](https://docs.clawd.bot/concepts/queue)
+
+## Workspace & skills
+
+- [Skills config](https://docs.clawd.bot/tools/skills-config)
+- [Default AGENTS](https://docs.clawd.bot/reference/AGENTS.default)
+- [Templates: AGENTS](https://docs.clawd.bot/reference/templates/AGENTS)
+- [Templates: BOOTSTRAP](https://docs.clawd.bot/reference/templates/BOOTSTRAP)
+- [Templates: IDENTITY](https://docs.clawd.bot/reference/templates/IDENTITY)
+- [Templates: SOUL](https://docs.clawd.bot/reference/templates/SOUL)
+- [Templates: TOOLS](https://docs.clawd.bot/reference/templates/TOOLS)
+- [Templates: USER](https://docs.clawd.bot/reference/templates/USER)
+
+## Platform internals
+
+- [macOS dev setup](https://docs.clawd.bot/platforms/mac/dev-setup)
+- [macOS menu bar](https://docs.clawd.bot/platforms/mac/menu-bar)
+- [macOS voice wake](https://docs.clawd.bot/platforms/mac/voicewake)
+- [iOS node](https://docs.clawd.bot/platforms/ios)
+- [Android node](https://docs.clawd.bot/platforms/android)
+- [Windows (WSL2)](https://docs.clawd.bot/platforms/windows)
+- [Linux app](https://docs.clawd.bot/platforms/linux)
+
+## Email hooks (Gmail)
+
+- [docs.clawd.bot/gmail-pubsub](https://docs.clawd.bot/automation/gmail-pubsub)
+
+## Clawd
+
+Clawdbot was built for **Clawd**, a space lobster AI assistant. 🦞  
+by Peter Steinberger and the community.
+
+- [clawd.me](https://clawd.me)
+- [soul.md](https://soul.md)
+- [steipete.me](https://steipete.me)
+
+## Community
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, maintainers, and how to submit PRs.  
+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/bohdanpodvirnyi"><img src="https://avatars.githubusercontent.com/u/31819391?v=4&s=48" width="48" height="48" alt="bohdanpodvirnyi" title="bohdanpodvirnyi"/></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/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/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/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/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/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/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/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/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/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/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/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/rdev"><img src="https://avatars.githubusercontent.com/u/8418866?v=4&s=48" width="48" height="48" alt="rdev" title="rdev"/></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/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/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/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/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/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/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/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/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/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/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/chrisrodz"><img src="https://avatars.githubusercontent.com/u/2967620?v=4&s=48" width="48" height="48" alt="chrisrodz" title="chrisrodz"/></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/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/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/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/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/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/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/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/voidserf"><img src="https://avatars.githubusercontent.com/u/477673?v=4&s=48" width="48" height="48" alt="voidserf" title="voidserf"/></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/Alphonse-arianee"><img src="https://avatars.githubusercontent.com/u/254457365?v=4&s=48" width="48" height="48" alt="Alphonse-arianee" title="Alphonse-arianee"/></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/longmaba"><img src="https://avatars.githubusercontent.com/u/9361500?v=4&s=48" width="48" height="48" alt="longmaba" title="longmaba"/></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/ronak-guliani"><img src="https://avatars.githubusercontent.com/u/23518228?v=4&s=48" width="48" height="48" alt="ronak-guliani" title="ronak-guliani"/></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/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  build-and-test:
+    runs-on: macos-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: swabble
+    steps:
+      - name: Checkout swabble
+        uses: actions/checkout@v4
+        with:
+          path: swabble
+
+      - name: Select Xcode 26.1 (prefer 26.1.1)
+        run: |
+          set -euo pipefail
+          # pick the newest installed 26.1.x, fallback to newest 26.x
+          CANDIDATE="$(ls -d /Applications/Xcode_26.1*.app 2>/dev/null | sort -V | tail -1 || true)"
+          if [[ -z "$CANDIDATE" ]]; then
+            CANDIDATE="$(ls -d /Applications/Xcode_26*.app 2>/dev/null | sort -V | tail -1 || true)"
+          fi
+          if [[ -z "$CANDIDATE" ]]; then
+            echo "No Xcode 26.x found on runner" >&2
+            exit 1
+          fi
+          echo "Selecting $CANDIDATE"
+          sudo xcode-select -s "$CANDIDATE"
+          xcodebuild -version
+
+      - name: Show Swift version
+        run: swift --version
+
+      - name: Install tooling
+        run: |
+          brew update
+          brew install swiftlint swiftformat
+
+      - name: Format check
+        run: |
+          ./scripts/format.sh
+          git diff --exit-code
+
+      - name: Lint
+        run: ./scripts/lint.sh
+
+      - name: Test
+        run: swift test --parallel

Swabble/.gitignore

@@ -0,0 +1,33 @@
+# macOS
+.DS_Store
+
+# SwiftPM / Build
+/.build
+/.swiftpm
+/DerivedData
+xcuserdata/
+*.xcuserstate
+
+# Editors
+/.vscode
+.idea/
+
+# Xcode artifacts
+*.hmap
+*.ipa
+*.dSYM.zip
+*.dSYM
+
+# Playgrounds
+*.xcplayground
+playground.xcworkspace
+timeline.xctimeline
+
+# Carthage
+Carthage/Build/
+
+# fastlane
+fastlane/report.xml
+fastlane/Preview.html
+fastlane/screenshots/**/*.png
+fastlane/test_output

Swabble/.swiftformat

@@ -0,0 +1,8 @@
+--swiftversion 6.2
+--indent 4
+--maxwidth 120
+--wraparguments before-first
+--wrapcollections before-first
+--stripunusedargs closure-only
+--self remove
+--header ""

Swabble/.swiftlint.yml

@@ -0,0 +1,43 @@
+# SwiftLint for swabble
+included:
+  - Sources
+excluded:
+  - .build
+  - DerivedData
+  - "**/.swiftpm"
+  - "**/.build"
+  - "**/DerivedData"
+  - "**/.DS_Store"
+opt_in_rules:
+  - array_init
+  - closure_spacing
+  - explicit_init
+  - fatal_error_message
+  - first_where
+  - joined_default_parameter
+  - last_where
+  - literal_expression_end_indentation
+  - multiline_arguments
+  - multiline_parameters
+  - operator_usage_whitespace
+  - redundant_nil_coalescing
+  - sorted_first_last
+  - switch_case_alignment
+  - vertical_parameter_alignment_on_call
+  - vertical_whitespace_opening_braces
+  - vertical_whitespace_closing_braces
+
+disabled_rules:
+  - trailing_whitespace
+  - trailing_newline
+  - indentation_width
+  - identifier_name
+  - explicit_self
+  - file_header
+  - todo
+
+line_length:
+  warning: 140
+  error: 180
+
+reporter: "xcode"

Swabble/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.2.0 — 2025-12-23
+
+### Highlights
+- Added `SwabbleKit` (multi-platform wake-word gate utilities with segment-aware gap detection).
+- Swabble package now supports iOS + macOS consumers; CLI remains macOS 26-only.
+
+### Changes
+- CLI wake-word matching/stripping routed through `SwabbleKit` helpers.
+- Speech pipeline types now explicitly gated to macOS 26 / iOS 26 availability.

Swabble/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Peter Steinberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Swabble/Package.resolved

@@ -0,0 +1,33 @@
+{
+  "originHash" : "5d29ee82825e0764775562242cfa1ff4dc79584797dd638f76c9876545454748",
+  "pins" : [
+    {
+      "identity" : "elevenlabskit",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/steipete/ElevenLabsKit",
+      "state" : {
+        "revision" : "c8679fbd37416a8780fe43be88a497ff16209e2d",
+        "version" : "0.1.0"
+      }
+    },
+    {
+      "identity" : "swift-syntax",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/swiftlang/swift-syntax.git",
+      "state" : {
+        "revision" : "0687f71944021d616d34d922343dcef086855920",
+        "version" : "600.0.1"
+      }
+    },
+    {
+      "identity" : "swift-testing",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/apple/swift-testing",
+      "state" : {
+        "revision" : "399f76dcd91e4c688ca2301fa24a8cc6d9927211",
+        "version" : "0.99.0"
+      }
+    }
+  ],
+  "version" : 3
+}

Swabble/Package.swift

@@ -0,0 +1,55 @@
+// swift-tools-version: 6.2
+import PackageDescription
+
+let package = Package(
+    name: "swabble",
+    platforms: [
+        .macOS(.v15),
+        .iOS(.v17),
+    ],
+    products: [
+        .library(name: "Swabble", targets: ["Swabble"]),
+        .library(name: "SwabbleKit", targets: ["SwabbleKit"]),
+        .executable(name: "swabble", targets: ["SwabbleCLI"]),
+    ],
+    dependencies: [
+        .package(path: "../Peekaboo/Commander"),
+        .package(url: "https://github.com/apple/swift-testing", from: "0.99.0"),
+    ],
+    targets: [
+        .target(
+            name: "Swabble",
+            path: "Sources/SwabbleCore",
+            swiftSettings: []),
+        .target(
+            name: "SwabbleKit",
+            path: "Sources/SwabbleKit",
+            swiftSettings: [
+                .enableUpcomingFeature("StrictConcurrency"),
+            ]),
+        .executableTarget(
+            name: "SwabbleCLI",
+            dependencies: [
+                "Swabble",
+                "SwabbleKit",
+                .product(name: "Commander", package: "Commander"),
+            ],
+            path: "Sources/swabble"),
+        .testTarget(
+            name: "SwabbleKitTests",
+            dependencies: [
+                "SwabbleKit",
+                .product(name: "Testing", package: "swift-testing"),
+            ],
+            swiftSettings: [
+                .enableUpcomingFeature("StrictConcurrency"),
+                .enableExperimentalFeature("SwiftTesting"),
+            ]),
+        .testTarget(
+            name: "swabbleTests",
+            dependencies: [
+                "Swabble",
+                .product(name: "Testing", package: "swift-testing"),
+            ]),
+    ],
+    swiftLanguageModes: [.v6])

Swabble/README.md

@@ -0,0 +1,111 @@
+# 🎙️ swabble — Speech.framework wake-word hook daemon (macOS 26)
+
+swabble is a Swift 6.2 wake-word hook daemon. The CLI targets macOS 26 (SpeechAnalyzer + SpeechTranscriber). The shared `SwabbleKit` target is multi-platform and exposes wake-word gating utilities for iOS/macOS apps.
+
+- **Local-only**: Speech.framework on-device models; zero network usage.
+- **Wake word**: Default `clawd` (aliases `claude`), optional `--no-wake` bypass.
+- **SwabbleKit**: Shared wake gate utilities (gap-based gating when you provide speech segments).
+- **Hooks**: Run any command with prefix/env, cooldown, min_chars, timeout.
+- **Services**: launchd helper stubs for start/stop/install.
+- **File transcribe**: TXT or SRT with time ranges (using AttributedString splits).
+
+## Quick start
+```bash
+# Install deps
+brew install swiftformat swiftlint
+
+# Build
+swift build
+
+# Write default config (~/.config/swabble/config.json)
+swift run swabble setup
+
+# Run foreground daemon
+swift run swabble serve
+
+# Test your hook
+swift run swabble test-hook "hello world"
+
+# Transcribe a file to SRT
+swift run swabble transcribe /path/to/audio.m4a --format srt --output out.srt
+```
+
+## Use as a library
+Add swabble as a SwiftPM dependency and import the `Swabble` or `SwabbleKit` product:
+
+```swift
+// Package.swift
+dependencies: [
+    .package(url: "https://github.com/steipete/swabble.git", branch: "main"),
+],
+targets: [
+    .target(name: "MyApp", dependencies: [
+        .product(name: "Swabble", package: "swabble"),     // Speech pipeline (macOS 26+ / iOS 26+)
+        .product(name: "SwabbleKit", package: "swabble"),  // Wake-word gate utilities (iOS 17+ / macOS 15+)
+    ]),
+]
+```
+
+## CLI
+- `serve` — foreground loop (mic → wake → hook)
+- `transcribe <file>` — offline transcription (txt|srt)
+- `test-hook "text"` — invoke configured hook
+- `mic list|set <index>` — enumerate/select input device
+- `setup` — write default config JSON
+- `doctor` — check Speech auth & device availability
+- `health` — prints `ok`
+- `tail-log` — last 10 transcripts
+- `status` — show wake state + recent transcripts
+- `service install|uninstall|status` — user launchd plist (stub: prints launchctl commands)
+- `start|stop|restart` — placeholders until full launchd wiring
+
+All commands accept Commander runtime flags (`-v/--verbose`, `--json-output`, `--log-level`), plus `--config` where applicable.
+
+## Config
+`~/.config/swabble/config.json` (auto-created by `setup`):
+```json
+{
+  "audio": {"deviceName": "", "deviceIndex": -1, "sampleRate": 16000, "channels": 1},
+  "wake": {"enabled": true, "word": "clawd", "aliases": ["claude"]},
+  "hook": {
+    "command": "",
+    "args": [],
+    "prefix": "Voice swabble from ${hostname}: ",
+    "cooldownSeconds": 1,
+    "minCharacters": 24,
+    "timeoutSeconds": 5,
+    "env": {}
+  },
+  "logging": {"level": "info", "format": "text"},
+  "transcripts": {"enabled": true, "maxEntries": 50},
+  "speech": {"localeIdentifier": "en_US", "etiquetteReplacements": false}
+}
+```
+
+- Config path override: `--config /path/to/config.json` on relevant commands.
+- Transcripts persist to `~/Library/Application Support/swabble/transcripts.log`.
+
+## Hook protocol
+When a wake-gated transcript passes min_chars & cooldown, swabble runs:
+```
+<command> <args...> "<prefix><text>"
+```
+Environment variables:
+- `SWABBLE_TEXT` — stripped transcript (wake word removed)
+- `SWABBLE_PREFIX` — rendered prefix (hostname substituted)
+- plus any `hook.env` key/values
+
+## Speech pipeline
+- `AVAudioEngine` tap → `BufferConverter` → `AnalyzerInput` → `SpeechAnalyzer` with a `SpeechTranscriber` module.
+- Requests volatile + final results; the CLI uses text-only wake gating today.
+- Authorization requested at first start; requires macOS 26 + new Speech.framework APIs.
+
+## Development
+- Format: `./scripts/format.sh` (uses ../peekaboo/.swiftformat if present)
+- Lint: `./scripts/lint.sh` (uses ../peekaboo/.swiftlint.yml if present)
+- Tests: `swift test` (uses swift-testing package)
+
+## Roadmap
+- launchd control (load/bootout, PID + status socket)
+- JSON logging + PII redaction toggle
+- Stronger wake-word detection and control socket status/health

Swabble/Sources/SwabbleCore/Config/Config.swift

@@ -0,0 +1,77 @@
+import Foundation
+
+public struct SwabbleConfig: Codable, Sendable {
+    public struct Audio: Codable, Sendable {
+        public var deviceName: String = ""
+        public var deviceIndex: Int = -1
+        public var sampleRate: Double = 16000
+        public var channels: Int = 1
+    }
+
+    public struct Wake: Codable, Sendable {
+        public var enabled: Bool = true
+        public var word: String = "clawd"
+        public var aliases: [String] = ["claude"]
+    }
+
+    public struct Hook: Codable, Sendable {
+        public var command: String = ""
+        public var args: [String] = []
+        public var prefix: String = "Voice swabble from ${hostname}: "
+        public var cooldownSeconds: Double = 1
+        public var minCharacters: Int = 24
+        public var timeoutSeconds: Double = 5
+        public var env: [String: String] = [:]
+    }
+
+    public struct Logging: Codable, Sendable {
+        public var level: String = "info"
+        public var format: String = "text" // text|json placeholder
+    }
+
+    public struct Transcripts: Codable, Sendable {
+        public var enabled: Bool = true
+        public var maxEntries: Int = 50
+    }
+
+    public struct Speech: Codable, Sendable {
+        public var localeIdentifier: String = Locale.current.identifier
+        public var etiquetteReplacements: Bool = false
+    }
+
+    public var audio = Audio()
+    public var wake = Wake()
+    public var hook = Hook()
+    public var logging = Logging()
+    public var transcripts = Transcripts()
+    public var speech = Speech()
+
+    public static let defaultPath = FileManager.default
+        .homeDirectoryForCurrentUser
+        .appendingPathComponent(".config/swabble/config.json")
+
+    public init() {}
+}
+
+public enum ConfigError: Error {
+    case missingConfig
+}
+
+public enum ConfigLoader {
+    public static func load(at path: URL?) throws -> SwabbleConfig {
+        let url = path ?? SwabbleConfig.defaultPath
+        if !FileManager.default.fileExists(atPath: url.path) {
+            throw ConfigError.missingConfig
+        }
+        let data = try Data(contentsOf: url)
+        return try JSONDecoder().decode(SwabbleConfig.self, from: data)
+    }
+
+    public static func save(_ config: SwabbleConfig, at path: URL?) throws {
+        let url = path ?? SwabbleConfig.defaultPath
+        let dir = url.deletingLastPathComponent()
+        try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+        let data = try JSONEncoder().encode(config)
+        try data.write(to: url)
+    }
+}

Swabble/Sources/SwabbleCore/Hooks/HookExecutor.swift

@@ -0,0 +1,75 @@
+import Foundation
+
+public struct HookJob: Sendable {
+    public let text: String
+    public let timestamp: Date
+
+    public init(text: String, timestamp: Date) {
+        self.text = text
+        self.timestamp = timestamp
+    }
+}
+
+public actor HookExecutor {
+    private let config: SwabbleConfig
+    private var lastRun: Date?
+    private let hostname: String
+
+    public init(config: SwabbleConfig) {
+        self.config = config
+        hostname = Host.current().localizedName ?? "host"
+    }
+
+    public func shouldRun() -> Bool {
+        guard config.hook.cooldownSeconds > 0 else { return true }
+        if let lastRun, Date().timeIntervalSince(lastRun) < config.hook.cooldownSeconds {
+            return false
+        }
+        return true
+    }
+
+    public func run(job: HookJob) async throws {
+        guard shouldRun() else { return }
+        guard !config.hook.command.isEmpty else { throw NSError(
+            domain: "Hook",
+            code: 1,
+            userInfo: [NSLocalizedDescriptionKey: "hook command not set"]) }
+
+        let prefix = config.hook.prefix.replacingOccurrences(of: "${hostname}", with: hostname)
+        let payload = prefix + job.text
+
+        let process = Process()
+        process.executableURL = URL(fileURLWithPath: config.hook.command)
+        process.arguments = config.hook.args + [payload]
+
+        var env = ProcessInfo.processInfo.environment
+        env["SWABBLE_TEXT"] = job.text
+        env["SWABBLE_PREFIX"] = prefix
+        for (k, v) in config.hook.env {
+            env[k] = v
+        }
+        process.environment = env
+
+        let pipe = Pipe()
+        process.standardOutput = pipe
+        process.standardError = pipe
+
+        try process.run()
+
+        let timeoutNanos = UInt64(max(config.hook.timeoutSeconds, 0.1) * 1_000_000_000)
+        try await withThrowingTaskGroup(of: Void.self) { group in
+            group.addTask {
+                process.waitUntilExit()
+            }
+            group.addTask {
+                try await Task.sleep(nanoseconds: timeoutNanos)
+                if process.isRunning {
+                    process.terminate()
+                }
+            }
+            try await group.next()
+            group.cancelAll()
+        }
+        lastRun = Date()
+    }
+}

Swabble/Sources/SwabbleCore/Speech/BufferConverter.swift

@@ -0,0 +1,50 @@
+@preconcurrency import AVFoundation
+import Foundation
+
+final class BufferConverter {
+    private final class Box<T>: @unchecked Sendable { var value: T; init(_ value: T) { self.value = value } }
+    enum ConverterError: Swift.Error {
+        case failedToCreateConverter
+        case failedToCreateConversionBuffer
+        case conversionFailed(NSError?)
+    }
+
+    private var converter: AVAudioConverter?
+
+    func convert(_ buffer: AVAudioPCMBuffer, to format: AVAudioFormat) throws -> AVAudioPCMBuffer {
+        let inputFormat = buffer.format
+        if inputFormat == format {
+            return buffer
+        }
+        if converter == nil || converter?.outputFormat != format {
+            converter = AVAudioConverter(from: inputFormat, to: format)
+            converter?.primeMethod = .none
+        }
+        guard let converter else { throw ConverterError.failedToCreateConverter }
+
+        let sampleRateRatio = converter.outputFormat.sampleRate / converter.inputFormat.sampleRate
+        let scaledInputFrameLength = Double(buffer.frameLength) * sampleRateRatio
+        let frameCapacity = AVAudioFrameCount(scaledInputFrameLength.rounded(.up))
+        guard let conversionBuffer = AVAudioPCMBuffer(pcmFormat: converter.outputFormat, frameCapacity: frameCapacity)
+        else {
+            throw ConverterError.failedToCreateConversionBuffer
+        }
+
+        var nsError: NSError?
+        let consumed = Box(false)
+        let inputBuffer = buffer
+        let status = converter.convert(to: conversionBuffer, error: &nsError) { _, statusPtr in
+            if consumed.value {
+                statusPtr.pointee = .noDataNow
+                return nil
+            }
+            consumed.value = true
+            statusPtr.pointee = .haveData
+            return inputBuffer
+        }
+        if status == .error {
+            throw ConverterError.conversionFailed(nsError)
+        }
+        return conversionBuffer
+    }
+}

Swabble/Sources/SwabbleCore/Speech/SpeechPipeline.swift

@@ -0,0 +1,114 @@
+import AVFoundation
+import Foundation
+import Speech
+
+@available(macOS 26.0, iOS 26.0, *)
+public struct SpeechSegment: Sendable {
+    public let text: String
+    public let isFinal: Bool
+}
+
+@available(macOS 26.0, iOS 26.0, *)
+public enum SpeechPipelineError: Error {
+    case authorizationDenied
+    case analyzerFormatUnavailable
+    case transcriberUnavailable
+}
+
+/// Live microphone → SpeechAnalyzer → SpeechTranscriber pipeline.
+@available(macOS 26.0, iOS 26.0, *)
+public actor SpeechPipeline {
+    private struct UnsafeBuffer: @unchecked Sendable { let buffer: AVAudioPCMBuffer }
+
+    private var engine = AVAudioEngine()
+    private var transcriber: SpeechTranscriber?
+    private var analyzer: SpeechAnalyzer?
+    private var inputContinuation: AsyncStream<AnalyzerInput>.Continuation?
+    private var resultTask: Task<Void, Never>?
+    private let converter = BufferConverter()
+
+    public init() {}
+
+    public func start(localeIdentifier: String, etiquette: Bool) async throws -> AsyncStream<SpeechSegment> {
+        let auth = await requestAuthorizationIfNeeded()
+        guard auth == .authorized else { throw SpeechPipelineError.authorizationDenied }
+
+        let transcriberModule = SpeechTranscriber(
+            locale: Locale(identifier: localeIdentifier),
+            transcriptionOptions: etiquette ? [.etiquetteReplacements] : [],
+            reportingOptions: [.volatileResults],
+            attributeOptions: [])
+        transcriber = transcriberModule
+
+        guard let analyzerFormat = await SpeechAnalyzer.bestAvailableAudioFormat(compatibleWith: [transcriberModule])
+        else {
+            throw SpeechPipelineError.analyzerFormatUnavailable
+        }
+
+        analyzer = SpeechAnalyzer(modules: [transcriberModule])
+        let (stream, continuation) = AsyncStream<AnalyzerInput>.makeStream()
+        inputContinuation = continuation
+
+        let inputNode = engine.inputNode
+        let inputFormat = inputNode.outputFormat(forBus: 0)
+        inputNode.removeTap(onBus: 0)
+        inputNode.installTap(onBus: 0, bufferSize: 2048, format: inputFormat) { [weak self] buffer, _ in
+            guard let self else { return }
+            let boxed = UnsafeBuffer(buffer: buffer)
+            Task { await self.handleBuffer(boxed.buffer, targetFormat: analyzerFormat) }
+        }
+
+        engine.prepare()
+        try engine.start()
+        try await analyzer?.start(inputSequence: stream)
+
+        guard let transcriberForStream = transcriber else {
+            throw SpeechPipelineError.transcriberUnavailable
+        }
+
+        return AsyncStream { continuation in
+            self.resultTask = Task {
+                do {
+                    for try await result in transcriberForStream.results {
+                        let seg = SpeechSegment(text: String(result.text.characters), isFinal: result.isFinal)
+                        continuation.yield(seg)
+                    }
+                } catch {
+                    // swallow errors and finish
+                }
+                continuation.finish()
+            }
+            continuation.onTermination = { _ in
+                Task { await self.stop() }
+            }
+        }
+    }
+
+    public func stop() async {
+        resultTask?.cancel()
+        inputContinuation?.finish()
+        engine.inputNode.removeTap(onBus: 0)
+        engine.stop()
+        try? await analyzer?.finalizeAndFinishThroughEndOfInput()
+    }
+
+    private func handleBuffer(_ buffer: AVAudioPCMBuffer, targetFormat: AVAudioFormat) async {
+        do {
+            let converted = try converter.convert(buffer, to: targetFormat)
+            let input = AnalyzerInput(buffer: converted)
+            inputContinuation?.yield(input)
+        } catch {
+            // drop on conversion failure
+        }
+    }
+
+    private func requestAuthorizationIfNeeded() async -> SFSpeechRecognizerAuthorizationStatus {
+        let current = SFSpeechRecognizer.authorizationStatus()
+        guard current == .notDetermined else { return current }
+        return await withCheckedContinuation { continuation in
+            SFSpeechRecognizer.requestAuthorization { status in
+                continuation.resume(returning: status)
+            }
+        }
+    }
+}

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

@@ -0,0 +1,62 @@
+import CoreMedia
+import Foundation
+import NaturalLanguage
+
+extension AttributedString {
+    public func sentences(maxLength: Int? = nil) -> [AttributedString] {
+        let tokenizer = NLTokenizer(unit: .sentence)
+        let string = String(characters)
+        tokenizer.string = string
+        let sentenceRanges = tokenizer.tokens(for: string.startIndex..<string.endIndex).map {
+            (
+                $0,
+                AttributedString.Index($0.lowerBound, within: self)!
+                    ..<
+                    AttributedString.Index($0.upperBound, within: self)!)
+        }
+        let ranges = sentenceRanges.flatMap { sentenceStringRange, sentenceRange in
+            let sentence = self[sentenceRange]
+            guard let maxLength, sentence.characters.count > maxLength else {
+                return [sentenceRange]
+            }
+
+            let wordTokenizer = NLTokenizer(unit: .word)
+            wordTokenizer.string = string
+            var wordRanges = wordTokenizer.tokens(for: sentenceStringRange).map {
+                AttributedString.Index($0.lowerBound, within: self)!
+                    ..<
+                    AttributedString.Index($0.upperBound, within: self)!
+            }
+            guard !wordRanges.isEmpty else { return [sentenceRange] }
+            wordRanges[0] = sentenceRange.lowerBound..<wordRanges[0].upperBound
+            wordRanges[wordRanges.count - 1] = wordRanges[wordRanges.count - 1].lowerBound..<sentenceRange.upperBound
+
+            var ranges: [Range<AttributedString.Index>] = []
+            for wordRange in wordRanges {
+                if let lastRange = ranges.last,
+                   self[lastRange].characters.count + self[wordRange].characters.count <= maxLength {
+                    ranges[ranges.count - 1] = lastRange.lowerBound..<wordRange.upperBound
+                } else {
+                    ranges.append(wordRange)
+                }
+            }
+
+            return ranges
+        }
+
+        return ranges.compactMap { range in
+            let audioTimeRanges = self[range].runs.filter {
+                !String(self[$0.range].characters)
+                    .trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+            }.compactMap(\.audioTimeRange)
+            guard !audioTimeRanges.isEmpty else { return nil }
+            let start = audioTimeRanges.first!.start
+            let end = audioTimeRanges.last!.end
+            var attributes = AttributeContainer()
+            attributes[AttributeScopes.SpeechAttributes.TimeRangeAttribute.self] = CMTimeRange(
+                start: start,
+                end: end)
+            return AttributedString(self[range].characters, attributes: attributes)
+        }
+    }
+}

Swabble/Sources/SwabbleCore/Support/Logging.swift

@@ -0,0 +1,41 @@
+import Foundation
+
+public enum LogLevel: String, Comparable, CaseIterable, Sendable {
+    case trace, debug, info, warn, error
+
+    var rank: Int {
+        switch self {
+        case .trace: 0
+        case .debug: 1
+        case .info: 2
+        case .warn: 3
+        case .error: 4
+        }
+    }
+
+    public static func < (lhs: LogLevel, rhs: LogLevel) -> Bool { lhs.rank < rhs.rank }
+}
+
+public struct Logger: Sendable {
+    public let level: LogLevel
+
+    public init(level: LogLevel) { self.level = level }
+
+    public func log(_ level: LogLevel, _ message: String) {
+        guard level >= self.level else { return }
+        let ts = ISO8601DateFormatter().string(from: Date())
+        print("[\(level.rawValue.uppercased())] \(ts) | \(message)")
+    }
+
+    public func trace(_ msg: String) { log(.trace, msg) }
+    public func debug(_ msg: String) { log(.debug, msg) }
+    public func info(_ msg: String) { log(.info, msg) }
+    public func warn(_ msg: String) { log(.warn, msg) }
+    public func error(_ msg: String) { log(.error, msg) }
+}
+
+extension LogLevel {
+    public init?(configValue: String) {
+        self.init(rawValue: configValue.lowercased())
+    }
+}

Swabble/Sources/SwabbleCore/Support/OutputFormat.swift

@@ -0,0 +1,45 @@
+import CoreMedia
+import Foundation
+
+public enum OutputFormat: String {
+    case txt
+    case srt
+
+    public var needsAudioTimeRange: Bool {
+        switch self {
+        case .srt: true
+        default: false
+        }
+    }
+
+    public func text(for transcript: AttributedString, maxLength: Int) -> String {
+        switch self {
+        case .txt:
+            return String(transcript.characters)
+        case .srt:
+            func format(_ timeInterval: TimeInterval) -> String {
+                let ms = Int(timeInterval.truncatingRemainder(dividingBy: 1) * 1000)
+                let s = Int(timeInterval) % 60
+                let m = (Int(timeInterval) / 60) % 60
+                let h = Int(timeInterval) / 60 / 60
+                return String(format: "%0.2d:%0.2d:%0.2d,%0.3d", h, m, s, ms)
+            }
+
+            return transcript.sentences(maxLength: maxLength).compactMap { (sentence: AttributedString) -> (
+                CMTimeRange,
+                String)? in
+                guard let timeRange = sentence.audioTimeRange else { return nil }
+                return (timeRange, String(sentence.characters))
+            }.enumerated().map { index, run in
+                let (timeRange, text) = run
+                return """
+
+                \(index + 1)
+                \(format(timeRange.start.seconds)) --> \(format(timeRange.end.seconds))
+                \(text.trimmingCharacters(in: .whitespacesAndNewlines))
+
+                """
+            }.joined().trimmingCharacters(in: .whitespacesAndNewlines)
+        }
+    }
+}

Swabble/Sources/SwabbleCore/Support/TranscriptsStore.swift

@@ -0,0 +1,45 @@
+import Foundation
+
+public actor TranscriptsStore {
+    public static let shared = TranscriptsStore()
+
+    private var entries: [String] = []
+    private let limit = 100
+    private let fileURL: URL
+
+    public init() {
+        let dir = FileManager.default.homeDirectoryForCurrentUser
+            .appendingPathComponent("Library/Application Support/swabble", isDirectory: true)
+        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) {
+            entries = text.split(separator: "\n").map(String.init).suffix(limit)
+        }
+    }
+
+    public func append(text: String) {
+        entries.append(text)
+        if entries.count > limit {
+            entries.removeFirst(entries.count - limit)
+        }
+        let body = entries.joined(separator: "\n")
+        try? body.write(to: fileURL, atomically: false, encoding: .utf8)
+    }
+
+    public func latest() -> [String] { entries }
+}
+
+extension String {
+    private func appendLine(to url: URL) throws {
+        let data = (self + "\n").data(using: .utf8) ?? Data()
+        if FileManager.default.fileExists(atPath: url.path) {
+            let handle = try FileHandle(forWritingTo: url)
+            try handle.seekToEnd()
+            try handle.write(contentsOf: data)
+            try handle.close()
+        } else {
+            try data.write(to: url)
+        }
+    }
+}

Swabble/Sources/SwabbleKit/WakeWordGate.swift

@@ -0,0 +1,197 @@
+import Foundation
+
+public struct WakeWordSegment: Sendable, Equatable {
+    public let text: String
+    public let start: TimeInterval
+    public let duration: TimeInterval
+    public let range: Range<String.Index>?
+
+    public init(text: String, start: TimeInterval, duration: TimeInterval, range: Range<String.Index>? = nil) {
+        self.text = text
+        self.start = start
+        self.duration = duration
+        self.range = range
+    }
+
+    public var end: TimeInterval { start + duration }
+}
+
+public struct WakeWordGateConfig: Sendable, Equatable {
+    public var triggers: [String]
+    public var minPostTriggerGap: TimeInterval
+    public var minCommandLength: Int
+
+    public init(
+        triggers: [String],
+        minPostTriggerGap: TimeInterval = 0.45,
+        minCommandLength: Int = 1) {
+        self.triggers = triggers
+        self.minPostTriggerGap = minPostTriggerGap
+        self.minCommandLength = minCommandLength
+    }
+}
+
+public struct WakeWordGateMatch: Sendable, Equatable {
+    public let triggerEndTime: TimeInterval
+    public let postGap: TimeInterval
+    public let command: String
+
+    public init(triggerEndTime: TimeInterval, postGap: TimeInterval, command: String) {
+        self.triggerEndTime = triggerEndTime
+        self.postGap = postGap
+        self.command = command
+    }
+}
+
+public enum WakeWordGate {
+    private struct Token {
+        let normalized: String
+        let start: TimeInterval
+        let end: TimeInterval
+        let range: Range<String.Index>?
+        let text: String
+    }
+
+    private struct TriggerTokens {
+        let tokens: [String]
+    }
+
+    private struct MatchCandidate {
+        let index: Int
+        let triggerEnd: TimeInterval
+        let gap: TimeInterval
+    }
+
+    public static func match(
+        transcript: String,
+        segments: [WakeWordSegment],
+        config: WakeWordGateConfig)
+    -> WakeWordGateMatch? {
+        let triggerTokens = normalizeTriggers(config.triggers)
+        guard !triggerTokens.isEmpty else { return nil }
+
+        let tokens = normalizeSegments(segments)
+        guard !tokens.isEmpty else { return nil }
+
+        var best: MatchCandidate?
+
+        for trigger in triggerTokens {
+            let count = trigger.tokens.count
+            guard count > 0, tokens.count > count else { continue }
+            for i in 0...(tokens.count - count - 1) {
+                let matched = (0..<count).allSatisfy { tokens[i + $0].normalized == trigger.tokens[$0] }
+                if !matched { continue }
+
+                let triggerEnd = tokens[i + count - 1].end
+                let nextToken = tokens[i + count]
+                let gap = nextToken.start - triggerEnd
+                if gap < config.minPostTriggerGap { continue }
+
+                if let best, i <= best.index { continue }
+
+                best = MatchCandidate(index: i, triggerEnd: triggerEnd, gap: gap)
+            }
+        }
+
+        guard let best else { return nil }
+        let command = commandText(transcript: transcript, segments: segments, triggerEndTime: best.triggerEnd)
+            .trimmingCharacters(in: Self.whitespaceAndPunctuation)
+        guard command.count >= config.minCommandLength else { return nil }
+        return WakeWordGateMatch(triggerEndTime: best.triggerEnd, postGap: best.gap, command: command)
+    }
+
+    public static func commandText(
+        transcript: String,
+        segments: [WakeWordSegment],
+        triggerEndTime: TimeInterval)
+    -> String {
+        let threshold = triggerEndTime + 0.001
+        for segment in segments where segment.start >= threshold {
+            if normalizeToken(segment.text).isEmpty { continue }
+            if let range = segment.range {
+                let slice = transcript[range.lowerBound...]
+                return String(slice).trimmingCharacters(in: Self.whitespaceAndPunctuation)
+            }
+            break
+        }
+
+        let text = segments
+            .filter { $0.start >= threshold && !normalizeToken($0.text).isEmpty }
+            .map(\.text)
+            .joined(separator: " ")
+        return text.trimmingCharacters(in: Self.whitespaceAndPunctuation)
+    }
+
+    public static func matchesTextOnly(text: String, triggers: [String]) -> Bool {
+        guard !text.isEmpty else { return false }
+        let normalized = text.lowercased()
+        for trigger in triggers {
+            let token = trigger.trimmingCharacters(in: whitespaceAndPunctuation).lowercased()
+            if token.isEmpty { continue }
+            if normalized.contains(token) { return true }
+        }
+        return false
+    }
+
+    public static func stripWake(text: String, triggers: [String]) -> String {
+        var out = text
+        for trigger in triggers {
+            let token = trigger.trimmingCharacters(in: whitespaceAndPunctuation)
+            guard !token.isEmpty else { continue }
+            out = out.replacingOccurrences(of: token, with: "", options: [.caseInsensitive])
+        }
+        return out.trimmingCharacters(in: whitespaceAndPunctuation)
+    }
+
+    private static func normalizeTriggers(_ triggers: [String]) -> [TriggerTokens] {
+        var output: [TriggerTokens] = []
+        for trigger in triggers {
+            let tokens = trigger
+                .split(whereSeparator: { $0.isWhitespace })
+                .map { normalizeToken(String($0)) }
+                .filter { !$0.isEmpty }
+            if tokens.isEmpty { continue }
+            output.append(TriggerTokens(tokens: tokens))
+        }
+        return output
+    }
+
+    private static func normalizeSegments(_ segments: [WakeWordSegment]) -> [Token] {
+        segments.compactMap { segment in
+            let normalized = normalizeToken(segment.text)
+            guard !normalized.isEmpty else { return nil }
+            return Token(
+                normalized: normalized,
+                start: segment.start,
+                end: segment.end,
+                range: segment.range,
+                text: segment.text)
+        }
+    }
+
+    private static func normalizeToken(_ token: String) -> String {
+        token
+            .trimmingCharacters(in: whitespaceAndPunctuation)
+            .lowercased()
+    }
+
+    private static let whitespaceAndPunctuation = CharacterSet.whitespacesAndNewlines
+        .union(.punctuationCharacters)
+}
+
+#if canImport(Speech)
+import Speech
+
+public enum WakeWordSpeechSegments {
+    public static func from(transcription: SFTranscription, transcript: String) -> [WakeWordSegment] {
+        transcription.segments.map { segment in
+            let range = Range(segment.substringRange, in: transcript)
+            return WakeWordSegment(
+                text: segment.substring,
+                start: segment.timestamp,
+                duration: segment.duration,
+                range: range)
+        }
+    }
+}
+#endif

Swabble/Sources/swabble/CLI/CLIRegistry.swift

@@ -0,0 +1,71 @@
+import Commander
+import Foundation
+
+@available(macOS 26.0, *)
+@MainActor
+enum CLIRegistry {
+    static var descriptors: [CommandDescriptor] {
+        let serveDesc = descriptor(for: ServeCommand.self)
+        let transcribeDesc = descriptor(for: TranscribeCommand.self)
+        let testHookDesc = descriptor(for: TestHookCommand.self)
+        let micList = descriptor(for: MicList.self)
+        let micSet = descriptor(for: MicSet.self)
+        let micRoot = CommandDescriptor(
+            name: "mic",
+            abstract: "Microphone management",
+            discussion: nil,
+            signature: CommandSignature(),
+            subcommands: [micList, micSet])
+        let serviceRoot = CommandDescriptor(
+            name: "service",
+            abstract: "launchd helper",
+            discussion: nil,
+            signature: CommandSignature(),
+            subcommands: [
+                descriptor(for: ServiceInstall.self),
+                descriptor(for: ServiceUninstall.self),
+                descriptor(for: ServiceStatus.self)
+            ])
+        let doctorDesc = descriptor(for: DoctorCommand.self)
+        let setupDesc = descriptor(for: SetupCommand.self)
+        let healthDesc = descriptor(for: HealthCommand.self)
+        let tailLogDesc = descriptor(for: TailLogCommand.self)
+        let startDesc = descriptor(for: StartCommand.self)
+        let stopDesc = descriptor(for: StopCommand.self)
+        let restartDesc = descriptor(for: RestartCommand.self)
+        let statusDesc = descriptor(for: StatusCommand.self)
+
+        let rootSignature = CommandSignature().withStandardRuntimeFlags()
+        let root = CommandDescriptor(
+            name: "swabble",
+            abstract: "Speech hook daemon",
+            discussion: "Local wake-word → SpeechTranscriber → hook",
+            signature: rootSignature,
+            subcommands: [
+                serveDesc,
+                transcribeDesc,
+                testHookDesc,
+                micRoot,
+                serviceRoot,
+                doctorDesc,
+                setupDesc,
+                healthDesc,
+                tailLogDesc,
+                startDesc,
+                stopDesc,
+                restartDesc,
+                statusDesc
+            ])
+        return [root]
+    }
+
+    private static func descriptor(for type: any ParsableCommand.Type) -> CommandDescriptor {
+        let sig = CommandSignature.describe(type.init()).withStandardRuntimeFlags()
+        return CommandDescriptor(
+            name: type.commandDescription.commandName ?? "",
+            abstract: type.commandDescription.abstract,
+            discussion: type.commandDescription.discussion,
+            signature: sig,
+            subcommands: [])
+    }
+}

Swabble/Sources/swabble/Commands/DoctorCommand.swift

@@ -0,0 +1,37 @@
+import Commander
+import Foundation
+import Speech
+import Swabble
+
+@MainActor
+struct DoctorCommand: ParsableCommand {
+    static var commandDescription: CommandDescription {
+        CommandDescription(commandName: "doctor", abstract: "Check Speech permission and config")
+    }
+
+    @Option(name: .long("config"), help: "Path to config JSON") var configPath: String?
+
+    init() {}
+    init(parsed: ParsedValues) {
+        self.init()
+        if let cfg = parsed.options["config"]?.last { configPath = cfg }
+    }
+
+    mutating func run() async throws {
+        let auth = await SFSpeechRecognizer.authorizationStatus()
+        print("Speech auth: \(auth)")
+        do {
+            _ = try ConfigLoader.load(at: configURL)
+            print("Config: OK")
+        } catch {
+            print("Config missing or invalid; run setup")
+        }
+        let session = AVCaptureDevice.DiscoverySession(
+            deviceTypes: [.microphone, .external],
+            mediaType: .audio,
+            position: .unspecified)
+        print("Mics found: \(session.devices.count)")
+    }
+
+    private var configURL: URL? { configPath.map { URL(fileURLWithPath: $0) } }
+}

Swabble/Sources/swabble/Commands/HealthCommand.swift

@@ -0,0 +1,16 @@
+import Commander
+import Foundation
+
+@MainActor
+struct HealthCommand: ParsableCommand {
+    static var commandDescription: CommandDescription {
+        CommandDescription(commandName: "health", abstract: "Health probe")
+    }
+
+    init() {}
+    init(parsed: ParsedValues) {}
+
+    mutating func run() async throws {
+        print("ok")
+    }
+}

Swabble/Sources/swabble/Commands/MicCommands.swift

@@ -0,0 +1,62 @@
+import AVFoundation
+import Commander
+import Foundation
+import Swabble
+
+@MainActor
+struct MicCommand: ParsableCommand {
+    static var commandDescription: CommandDescription {
+        CommandDescription(
+            commandName: "mic",
+            abstract: "Microphone management",
+            subcommands: [MicList.self, MicSet.self])
+    }
+}
+
+@MainActor
+struct MicList: ParsableCommand {
+    static var commandDescription: CommandDescription {
+        CommandDescription(commandName: "list", abstract: "List input devices")
+    }
+
+    init() {}
+    init(parsed: ParsedValues) {}
+
+    mutating func run() async throws {
+        let session = AVCaptureDevice.DiscoverySession(
+            deviceTypes: [.microphone, .external],
+            mediaType: .audio,
+            position: .unspecified)
+        let devices = session.devices
+        if devices.isEmpty { print("no audio inputs found"); return }
+        for (idx, device) in devices.enumerated() {
+            print("[\(idx)] \(device.localizedName)")
+        }
+    }
+}
+
+@MainActor
+struct MicSet: ParsableCommand {
+    @Argument(help: "Device index from list") var index: Int = 0
+    @Option(name: .long("config"), help: "Path to config JSON") var configPath: String?
+
+    static var commandDescription: CommandDescription {
+        CommandDescription(commandName: "set", abstract: "Set default input device index")
+    }
+
+    init() {}
+    init(parsed: ParsedValues) {
+        self.init()
+        if let value = parsed.positional.first, let intVal = Int(value) { index = intVal }
+        if let cfg = parsed.options["config"]?.last { configPath = cfg }
+    }
+
+    mutating func run() async throws {
+        var cfg = try ConfigLoader.load(at: configURL)
+        cfg.audio.deviceIndex = index
+        try ConfigLoader.save(cfg, at: configURL)
+        print("saved device index \(index)")
+    }
+
+    private var configURL: URL? { configPath.map { URL(fileURLWithPath: $0) } }
+}

Swabble/Sources/swabble/Commands/ServeCommand.swift

@@ -0,0 +1,81 @@
+import Commander
+import Foundation
+import Swabble
+import SwabbleKit
+
+@available(macOS 26.0, *)
+@MainActor
+struct ServeCommand: ParsableCommand {
+    @Option(name: .long("config"), help: "Path to config JSON") var configPath: String?
+    @Flag(name: .long("no-wake"), help: "Disable wake word") var noWake: Bool = false
+
+    static var commandDescription: CommandDescription {
+        CommandDescription(
+            commandName: "serve",
+            abstract: "Run swabble in the foreground")
+    }
+
+    init() {}
+
+    init(parsed: ParsedValues) {
+        self.init()
+        if parsed.flags.contains("noWake") { noWake = true }
+        if let cfg = parsed.options["config"]?.last { configPath = cfg }
+    }
+
+    mutating func run() async throws {
+        var cfg: SwabbleConfig
+        do {
+            cfg = try ConfigLoader.load(at: configURL)
+        } catch {
+            cfg = SwabbleConfig()
+            try ConfigLoader.save(cfg, at: configURL)
+        }
+        if noWake {
+            cfg.wake.enabled = false
+        }
+
+        let logger = Logger(level: LogLevel(configValue: cfg.logging.level) ?? .info)
+        logger.info("swabble serve starting (wake: \(cfg.wake.enabled ? cfg.wake.word : "disabled"))")
+        let pipeline = SpeechPipeline()
+        do {
+            let stream = try await pipeline.start(
+                localeIdentifier: cfg.speech.localeIdentifier,
+                etiquette: cfg.speech.etiquetteReplacements)
+            for await seg in stream {
+                if cfg.wake.enabled {
+                    guard Self.matchesWake(text: seg.text, cfg: cfg) else { continue }
+                }
+                let stripped = Self.stripWake(text: seg.text, cfg: cfg)
+                let job = HookJob(text: stripped, timestamp: Date())
+                let executor = HookExecutor(config: cfg)
+                try await executor.run(job: job)
+                if cfg.transcripts.enabled {
+                    await TranscriptsStore.shared.append(text: stripped)
+                }
+                if seg.isFinal {
+                    logger.info("final: \(stripped)")
+                } else {
+                    logger.debug("partial: \(stripped)")
+                }
+            }
+        } catch {
+            logger.error("serve error: \(error)")
+            throw error
+        }
+    }
+
+    private var configURL: URL? {
+        configPath.map { URL(fileURLWithPath: $0) }
+    }
+
+    private static func matchesWake(text: String, cfg: SwabbleConfig) -> Bool {
+        let triggers = [cfg.wake.word] + cfg.wake.aliases
+        return WakeWordGate.matchesTextOnly(text: text, triggers: triggers)
+    }
+
+    private static func stripWake(text: String, cfg: SwabbleConfig) -> String {
+        let triggers = [cfg.wake.word] + cfg.wake.aliases
+        return WakeWordGate.stripWake(text: text, triggers: triggers)
+    }
+}

Swabble/Sources/swabble/Commands/ServiceCommands.swift

@@ -0,0 +1,77 @@
+import Commander
+import Foundation
+
+@MainActor
+struct ServiceRootCommand: ParsableCommand {
+    static var commandDescription: CommandDescription {
+        CommandDescription(
+            commandName: "service",
+            abstract: "Manage launchd agent",
+            subcommands: [ServiceInstall.self, ServiceUninstall.self, ServiceStatus.self])
+    }
+}
+
+private enum LaunchdHelper {
+    static let label = "com.swabble.agent"
+
+    static var plistURL: URL {
+        FileManager.default
+            .homeDirectoryForCurrentUser
+            .appendingPathComponent("Library/LaunchAgents/\(label).plist")
+    }
+
+    static func writePlist(executable: String) throws {
+        let plist: [String: Any] = [
+            "Label": label,
+            "ProgramArguments": [executable, "serve"],
+            "RunAtLoad": true,
+            "KeepAlive": true
+        ]
+        let data = try PropertyListSerialization.data(fromPropertyList: plist, format: .xml, options: 0)
+        try data.write(to: plistURL)
+    }
+
+    static func removePlist() throws {
+        try? FileManager.default.removeItem(at: plistURL)
+    }
+}
+
+@MainActor
+struct ServiceInstall: ParsableCommand {
+    static var commandDescription: CommandDescription {
+        CommandDescription(commandName: "install", abstract: "Install user launch agent")
+    }
+
+    mutating func run() async throws {
+        let exe = CommandLine.arguments.first ?? "/usr/local/bin/swabble"
+        try LaunchdHelper.writePlist(executable: exe)
+        print("launchctl load -w \(LaunchdHelper.plistURL.path)")
+    }
+}
+
+@MainActor
+struct ServiceUninstall: ParsableCommand {
+    static var commandDescription: CommandDescription {
+        CommandDescription(commandName: "uninstall", abstract: "Remove launch agent")
+    }
+
+    mutating func run() async throws {
+        try LaunchdHelper.removePlist()
+        print("launchctl bootout gui/$(id -u)/\(LaunchdHelper.label)")
+    }
+}
+
+@MainActor
+struct ServiceStatus: ParsableCommand {
+    static var commandDescription: CommandDescription {
+        CommandDescription(commandName: "status", abstract: "Show launch agent status")
+    }
+
+    mutating func run() async throws {
+        if FileManager.default.fileExists(atPath: LaunchdHelper.plistURL.path) {
+            print("plist present at \(LaunchdHelper.plistURL.path)")
+        } else {
+            print("launchd plist not installed")
+        }
+    }
+}

Swabble/Sources/swabble/Commands/SetupCommand.swift

@@ -0,0 +1,26 @@
+import Commander
+import Foundation
+import Swabble
+
+@MainActor
+struct SetupCommand: ParsableCommand {
+    static var commandDescription: CommandDescription {
+        CommandDescription(commandName: "setup", abstract: "Write default config")
+    }
+
+    @Option(name: .long("config"), help: "Path to config JSON") var configPath: String?
+
+    init() {}
+    init(parsed: ParsedValues) {
+        self.init()
+        if let cfg = parsed.options["config"]?.last { configPath = cfg }
+    }
+
+    mutating func run() async throws {
+        let cfg = SwabbleConfig()
+        try ConfigLoader.save(cfg, at: configURL)
+        print("wrote config to \(configURL?.path ?? SwabbleConfig.defaultPath.path)")
+    }
+
+    private var configURL: URL? { configPath.map { URL(fileURLWithPath: $0) } }
+}

Swabble/Sources/swabble/Commands/StartStopCommands.swift

@@ -0,0 +1,35 @@
+import Commander
+import Foundation
+
+@MainActor
+struct StartCommand: ParsableCommand {
+    static var commandDescription: CommandDescription {
+        CommandDescription(commandName: "start", abstract: "Start swabble (foreground placeholder)")
+    }
+
+    mutating func run() async throws {
+        print("start: launchd helper not implemented; run 'swabble serve' instead")
+    }
+}
+
+@MainActor
+struct StopCommand: ParsableCommand {
+    static var commandDescription: CommandDescription {
+        CommandDescription(commandName: "stop", abstract: "Stop swabble (placeholder)")
+    }
+
+    mutating func run() async throws {
+        print("stop: launchd helper not implemented yet")
+    }
+}
+
+@MainActor
+struct RestartCommand: ParsableCommand {
+    static var commandDescription: CommandDescription {
+        CommandDescription(commandName: "restart", abstract: "Restart swabble (placeholder)")
+    }
+
+    mutating func run() async throws {
+        print("restart: launchd helper not implemented yet")
+    }
+}

Swabble/Sources/swabble/Commands/StatusCommand.swift

@@ -0,0 +1,34 @@
+import Commander
+import Foundation
+import Swabble
+
+@MainActor
+struct StatusCommand: ParsableCommand {
+    static var commandDescription: CommandDescription {
+        CommandDescription(commandName: "status", abstract: "Show daemon state")
+    }
+
+    @Option(name: .long("config"), help: "Path to config JSON") var configPath: String?
+
+    init() {}
+    init(parsed: ParsedValues) {
+        self.init()
+        if let cfg = parsed.options["config"]?.last { configPath = cfg }
+    }
+
+    mutating func run() async throws {
+        let cfg = try? ConfigLoader.load(at: configURL)
+        let wake = cfg?.wake.word ?? "clawd"
+        let wakeEnabled = cfg?.wake.enabled ?? false
+        let latest = await TranscriptsStore.shared.latest().suffix(3)
+        print("wake: \(wakeEnabled ? wake : "disabled")")
+        if latest.isEmpty {
+            print("transcripts: (none yet)")
+        } else {
+            print("last transcripts:")
+            latest.forEach { print("- \($0)") }
+        }
+    }
+
+    private var configURL: URL? { configPath.map { URL(fileURLWithPath: $0) } }
+}

Swabble/Sources/swabble/Commands/TailLogCommand.swift

@@ -0,0 +1,20 @@
+import Commander
+import Foundation
+import Swabble
+
+@MainActor
+struct TailLogCommand: ParsableCommand {
+    static var commandDescription: CommandDescription {
+        CommandDescription(commandName: "tail-log", abstract: "Tail recent transcripts")
+    }
+
+    init() {}
+    init(parsed: ParsedValues) {}
+
+    mutating func run() async throws {
+        let latest = await TranscriptsStore.shared.latest()
+        for line in latest.suffix(10) {
+            print(line)
+        }
+    }
+}

Swabble/Sources/swabble/Commands/TestHookCommand.swift

@@ -0,0 +1,30 @@
+import Commander
+import Foundation
+import Swabble
+
+@MainActor
+struct TestHookCommand: ParsableCommand {
+    @Argument(help: "Text to send to hook") var text: String
+    @Option(name: .long("config"), help: "Path to config JSON") var configPath: String?
+
+    static var commandDescription: CommandDescription {
+        CommandDescription(commandName: "test-hook", abstract: "Invoke the configured hook with text")
+    }
+
+    init() {}
+
+    init(parsed: ParsedValues) {
+        self.init()
+        if let positional = parsed.positional.first { text = positional }
+        if let cfg = parsed.options["config"]?.last { configPath = cfg }
+    }
+
+    mutating func run() async throws {
+        let cfg = try ConfigLoader.load(at: configURL)
+        let executor = HookExecutor(config: cfg)
+        try await executor.run(job: HookJob(text: text, timestamp: Date()))
+        print("hook invoked")
+    }
+
+    private var configURL: URL? { configPath.map { URL(fileURLWithPath: $0) } }
+}

Swabble/Sources/swabble/Commands/TranscribeCommand.swift

@@ -0,0 +1,61 @@
+import AVFoundation
+import Commander
+import Foundation
+import Speech
+import Swabble
+
+@MainActor
+struct TranscribeCommand: ParsableCommand {
+    @Argument(help: "Path to audio/video file") var inputFile: String = ""
+    @Option(name: .long("locale"), help: "Locale identifier", parsing: .singleValue) var locale: String = Locale.current
+        .identifier
+    @Flag(help: "Censor etiquette-sensitive content") var censor: Bool = false
+    @Option(name: .long("output"), help: "Output file path") var outputFile: String?
+    @Option(name: .long("format"), help: "Output format txt|srt") var format: String = "txt"
+    @Option(name: .long("max-length"), help: "Max sentence length for srt") var maxLength: Int = 40
+
+    static var commandDescription: CommandDescription {
+        CommandDescription(
+            commandName: "transcribe",
+            abstract: "Transcribe a media file locally")
+    }
+
+    init() {}
+
+    init(parsed: ParsedValues) {
+        self.init()
+        if let positional = parsed.positional.first { inputFile = positional }
+        if let loc = parsed.options["locale"]?.last { locale = loc }
+        if parsed.flags.contains("censor") { censor = true }
+        if let out = parsed.options["output"]?.last { outputFile = out }
+        if let fmt = parsed.options["format"]?.last { format = fmt }
+        if let len = parsed.options["maxLength"]?.last, let intVal = Int(len) { maxLength = intVal }
+    }
+
+    mutating func run() async throws {
+        let fileURL = URL(fileURLWithPath: inputFile)
+        let audioFile = try AVAudioFile(forReading: fileURL)
+
+        let outputFormat = OutputFormat(rawValue: format) ?? .txt
+
+        let transcriber = SpeechTranscriber(
+            locale: Locale(identifier: locale),
+            transcriptionOptions: censor ? [.etiquetteReplacements] : [],
+            reportingOptions: [],
+            attributeOptions: outputFormat.needsAudioTimeRange ? [.audioTimeRange] : [])
+        let analyzer = SpeechAnalyzer(modules: [transcriber])
+        try await analyzer.start(inputAudioFile: audioFile, finishAfterFile: true)
+
+        var transcript: AttributedString = ""
+        for try await result in transcriber.results {
+            transcript += result.text
+        }
+
+        let output = outputFormat.text(for: transcript, maxLength: maxLength)
+        if let path = outputFile {
+            try output.write(to: URL(fileURLWithPath: path), atomically: false, encoding: .utf8)
+        } else {
+            print(output)
+        }
+    }
+}

Swabble/Sources/swabble/main.swift

@@ -0,0 +1,151 @@
+import Commander
+import Foundation
+
+@available(macOS 26.0, *)
+@MainActor
+private func runCLI() async -> Int32 {
+    do {
+        let descriptors = CLIRegistry.descriptors
+        let program = Program(descriptors: descriptors)
+        let invocation = try program.resolve(argv: CommandLine.arguments)
+        try await dispatch(invocation: invocation)
+        return 0
+    } catch {
+        fputs("error: \(error)\n", stderr)
+        return 1
+    }
+}
+
+@available(macOS 26.0, *)
+@MainActor
+private func dispatch(invocation: CommandInvocation) async throws {
+    let parsed = invocation.parsedValues
+    let path = invocation.path
+    guard let first = path.first else { throw CommanderProgramError.missingCommand }
+
+    switch first {
+    case "swabble":
+        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)
+} else {
+    fputs("error: swabble requires macOS 26 or newer\n", stderr)
+    exit(1)
+}

Swabble/Tests/SwabbleKitTests/WakeWordGateTests.swift

@@ -0,0 +1,63 @@
+import Foundation
+import SwabbleKit
+import Testing
+
+@Suite struct WakeWordGateTests {
+    @Test func matchRequiresGapAfterTrigger() {
+        let transcript = "hey clawd do thing"
+        let segments = makeSegments(
+            transcript: transcript,
+            words: [
+                ("hey", 0.0, 0.1),
+                ("clawd", 0.2, 0.1),
+                ("do", 0.35, 0.1),
+                ("thing", 0.5, 0.1),
+            ])
+        let config = WakeWordGateConfig(triggers: ["clawd"], minPostTriggerGap: 0.3)
+        #expect(WakeWordGate.match(transcript: transcript, segments: segments, config: config) == nil)
+    }
+
+    @Test func matchAllowsGapAndExtractsCommand() {
+        let transcript = "hey clawd do thing"
+        let segments = makeSegments(
+            transcript: transcript,
+            words: [
+                ("hey", 0.0, 0.1),
+                ("clawd", 0.2, 0.1),
+                ("do", 0.9, 0.1),
+                ("thing", 1.1, 0.1),
+            ])
+        let config = WakeWordGateConfig(triggers: ["clawd"], minPostTriggerGap: 0.3)
+        let match = WakeWordGate.match(transcript: transcript, segments: segments, config: config)
+        #expect(match?.command == "do thing")
+    }
+
+    @Test func matchHandlesMultiWordTriggers() {
+        let transcript = "hey clawd do it"
+        let segments = makeSegments(
+            transcript: transcript,
+            words: [
+                ("hey", 0.0, 0.1),
+                ("clawd", 0.2, 0.1),
+                ("do", 0.8, 0.1),
+                ("it", 1.0, 0.1),
+            ])
+        let config = WakeWordGateConfig(triggers: ["hey clawd"], minPostTriggerGap: 0.3)
+        let match = WakeWordGate.match(transcript: transcript, segments: segments, config: config)
+        #expect(match?.command == "do it")
+    }
+}
+
+private func makeSegments(
+    transcript: String,
+    words: [(String, TimeInterval, TimeInterval)])
+-> [WakeWordSegment] {
+    var searchStart = transcript.startIndex
+    var output: [WakeWordSegment] = []
+    for (word, start, duration) in words {
+        let range = transcript.range(of: word, range: searchStart..<transcript.endIndex)
+        output.append(WakeWordSegment(text: word, start: start, duration: duration, range: range))
+        if let range { searchStart = range.upperBound }
+    }
+    return output
+}

Swabble/Tests/swabbleTests/ConfigTests.swift

@@ -0,0 +1,23 @@
+import Foundation
+import Testing
+@testable import Swabble
+
+@Test
+func configRoundTrip() throws {
+    var cfg = SwabbleConfig()
+    cfg.wake.word = "robot"
+    let url = FileManager.default.temporaryDirectory.appendingPathComponent(UUID().uuidString + ".json")
+    defer { try? FileManager.default.removeItem(at: url) }
+
+    try ConfigLoader.save(cfg, at: url)
+    let loaded = try ConfigLoader.load(at: url)
+    #expect(loaded.wake.word == "robot")
+    #expect(loaded.hook.prefix.contains("Voice swabble"))
+}
+
+@Test
+func configMissingThrows() {
+    #expect(throws: ConfigError.missingConfig) {
+        _ = try ConfigLoader.load(at: FileManager.default.temporaryDirectory.appendingPathComponent("nope.json"))
+    }
+}

Swabble/docs/spec.md

@@ -0,0 +1,33 @@
+# swabble — macOS 26 speech hook daemon (Swift 6.2)
+
+Goal: brabble-style always-on voice hook for macOS 26 using Apple Speech.framework (SpeechAnalyzer + SpeechTranscriber) instead of whisper.cpp. Local-only, wake word gated, dispatches a shell hook with the transcript. Shared wake-gate utilities live in `SwabbleKit` for reuse by other apps (iOS/macOS).
+
+## Requirements
+- macOS 26+, Swift 6.2, Speech.framework with on-device assets.
+- Local only; no network calls during transcription.
+- Wake word gating (default "clawd" plus aliases) with bypass flag `--no-wake`.
+- `SwabbleKit` target (multi-platform) providing wake-word gating helpers that can use speech segment timing to require a post-trigger gap.
+- Hook execution with cooldown, min_chars, timeout, prefix, env vars.
+- Simple config at `~/.config/swabble/config.json` (JSON, Codable) — no TOML.
+- CLI implemented with Commander (SwiftPM package `steipete/Commander`); core types are available via the SwiftPM library product `Swabble` for embedding.
+- Foreground `serve`; later launchd helper for start/stop/restart.
+- File transcription command emitting txt or srt.
+- Basic status/health surfaces and mic selection stubs.
+
+## Architecture
+- **CLI layer (Commander)**: Root command `swabble` with subcommands `serve`, `transcribe`, `test-hook`, `mic list|set`, `doctor`, `health`, `tail-log`. Runtime flags from Commander (`-v/--verbose`, `--json-output`, `--log-level`). Custom `--config` path applies everywhere.
+- **Config**: `SwabbleConfig` Codable. Fields: audio device name/index, wake (enabled/word/aliases/sensitivity placeholder), hook (command/args/prefix/cooldown/min_chars/timeout/env), logging (level, format), transcripts (enabled, max kept), speech (locale, enableEtiquetteReplacements flag). Stored JSON; default written by `setup`.
+- **Audio + Speech pipeline**: `SpeechPipeline` wraps `AVAudioEngine` input → `SpeechAnalyzer` with `SpeechTranscriber` module. Emits partial/final transcripts via async stream. Requests `.audioTimeRange` when transcripts enabled. Handles Speech permission and asset download prompts ahead of capture.
+- **Wake gate**: CLI currently uses text-only keyword match; shared `SwabbleKit` gate can enforce a minimum pause between the wake word and the next token when speech segments are available. `--no-wake` disables gating.
+- **Hook executor**: async `HookExecutor` spawns `Process` with configured args, prefix substitution `${hostname}`. Enforces cooldown + timeout; injects env `SWABBLE_TEXT`, `SWABBLE_PREFIX` plus user env map.
+- **Transcripts store**: in-memory ring buffer; optional persisted JSON lines under `~/Library/Application Support/swabble/transcripts.log`.
+- **Logging**: simple structured logger to stderr; respects log level.
+
+## Out of scope (initial cut)
+- Model management (Speech handles assets).
+- Launchd helper (planned follow-up).
+- Advanced wake-word detector (segment-aware gate now lives in `SwabbleKit`; CLI still text-only until segment timing is plumbed through).
+
+## Open decisions
+- Whether to expose a UNIX control socket for `status`/`health` (currently planned as stdin/out direct calls).
+- Hook redaction (PII) parity with brabble — placeholder boolean, no implementation yet.

Swabble/scripts/format.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PEEKABOO_ROOT="${ROOT}/../peekaboo"
+if [ -f "${PEEKABOO_ROOT}/.swiftformat" ]; then
+  CONFIG="${PEEKABOO_ROOT}/.swiftformat"
+else
+  CONFIG="${ROOT}/.swiftformat"
+fi
+swiftformat --config "$CONFIG" "$ROOT/Sources"

Swabble/scripts/lint.sh

@@ -0,0 +1,14 @@
+#!/bin/bash
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PEEKABOO_ROOT="${ROOT}/../peekaboo"
+if [ -f "${PEEKABOO_ROOT}/.swiftlint.yml" ]; then
+  CONFIG="${PEEKABOO_ROOT}/.swiftlint.yml"
+else
+  CONFIG="$ROOT/.swiftlint.yml"
+fi
+if ! command -v swiftlint >/dev/null; then
+  echo "swiftlint not installed" >&2
+  exit 1
+fi
+swiftlint --config "$CONFIG"

appcast.xml

@@ -0,0 +1,211 @@
+<?xml version="1.0" standalone="yes"?>
+<rss xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle" version="2.0">
+    <channel>
+        <title>Clawdbot</title>
+        <item>
+            <title>2026.1.14-1</title>
+            <pubDate>Thu, 15 Jan 2026 11:14:40 +0000</pubDate>
+            <link>https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml</link>
+            <sparkle:version>5825</sparkle:version>
+            <sparkle:shortVersionString>2026.1.14-1</sparkle:shortVersionString>
+            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+            <description><![CDATA[<h2>Clawdbot 2026.1.14-1</h2>
+<h3>Highlights</h3>
+<ul>
+<li>Web search: <code>web_search</code>/<code>web_fetch</code> tools (Brave API) + first-time setup in onboarding/configure.</li>
+<li>Browser control: Chrome extension relay takeover mode + remote browser control via <code>clawdbot browser serve</code>.</li>
+<li>Plugins: channel plugins (gateway HTTP hooks) + Zalo plugin + onboarding install flow. (#854) — thanks @longmaba.</li>
+<li>Security: expanded <code>clawdbot security audit</code> (+ <code>--fix</code>), detect-secrets CI scan, and a <code>SECURITY.md</code> reporting policy.</li>
+</ul>
+<h3>Changes</h3>
+<h4>Web Tools</h4>
+<ul>
+<li>Tools: add <code>web_search</code>/<code>web_fetch</code> (Brave API), including helpful setup hints when the key is missing.</li>
+<li>Tools: enable <code>web_fetch</code> by default (unless explicitly disabled in config).</li>
+<li>CLI/Docs: add <code>clawdbot configure --section web</code> for storing Brave API keys and update onboarding tips.</li>
+</ul>
+<h4>Browser / Control UI</h4>
+<ul>
+<li>Browser: add Chrome extension relay takeover mode (toolbar button) + <code>clawdbot browser serve</code> remote control + <code>browser.controlToken</code>.</li>
+<li>Browser: ship a built-in <code>chrome</code> profile for extension relay and start the relay automatically when running locally.</li>
+<li>Browser: default <code>browser.defaultProfile</code> to <code>chrome</code> (existing Chrome takeover mode).</li>
+<li>Browser: add <code>clawdbot browser extension install/path</code> and copy extension path to clipboard.</li>
+<li>Browser: add <code>snapshot refs=aria</code> (Playwright aria-ref ids) for self-resolving refs across <code>snapshot</code> → <code>act</code>.</li>
+<li>Browser: <code>profile="chrome"</code> now defaults to host control and returns clearer “attach a tab” errors.</li>
+<li>Browser: extension mode recovers when only one tab is attached (stale targetId fallback).</li>
+<li>Control UI: show raw any-map entries in config views; move Docs link into the left nav.</li>
+</ul>
+<h4>Plugins</h4>
+<ul>
+<li>Plugins: add plugin HTTP hooks + loader updates to support channel plugins. (#854) — thanks @longmaba.</li>
+<li>Plugins: add onboarding plugin install flow. (#854) — thanks @longmaba.</li>
+<li>Channels: add Matrix plugin (external) with docs + onboarding hooks.</li>
+<li>Voice Call: add Plivo provider (no SDK dependency). (#846) — thanks @vrknetha.</li>
+</ul>
+<h4>Security</h4>
+<ul>
+<li>Security: expand <code>clawdbot security audit</code> checks and publish a <code>SECURITY.md</code> reporting policy.</li>
+<li>Security: extend <code>clawdbot security audit --fix</code> to tighten more sensitive state paths.</li>
+<li>Security: add detect-secrets CI scan and baseline guidance. (#227) — thanks @Hyaxia.</li>
+</ul>
+<h4>Onboarding / Daemon</h4>
+<ul>
+<li>Onboarding: add a security checkpoint prompt (docs link + sandboxing hint); require <code>--accept-risk</code> for <code>--non-interactive</code>.</li>
+<li>Daemon: support profile-aware service names for multi-gateway setups. (#671) — thanks @bjesuiter.</li>
+</ul>
+<h4>Auth / Usage / Config</h4>
+<ul>
+<li>Usage: add MiniMax coding plan usage tracking.</li>
+<li>Auth: label Claude Code CLI auth options. (#915) — thanks @SeanZoR.</li>
+<li>Agents: add optional auth-profile copy prompt on <code>agents add</code> and improve auth error messaging.</li>
+<li>Auth: add dynamic template variables to <code>messages.responsePrefix</code>. (#928) — thanks @sebslight.</li>
+<li>Config: add <code>channels.<provider>.configWrites</code> gating for channel-initiated config writes; migrate Slack channel IDs.</li>
+</ul>
+<h4>Channels</h4>
+<ul>
+<li>Telegram: add message delete action in the message tool. (#903) — thanks @sleontenko.</li>
+<li>WhatsApp: add <code>channels.whatsapp.sendReadReceipts</code> to disable auto read receipts. (#882) — thanks @chrisrodz.</li>
+</ul>
+<h4>Docs</h4>
+<ul>
+<li>Docs: clarify per-agent auth stores, sandboxed skill binaries, and elevated semantics.</li>
+<li>Docs: add FAQ entries for missing provider auth after adding agents and Gemini thinking signature errors.</li>
+<li>Docs: expand gateway security hardening guidance and incident response checklist.</li>
+<li>Docs: document DM history limits for channel DMs. (#883) — thanks @pkrmf.</li>
+<li>Docs: standardize Claude Code CLI naming across docs and prompts. (follow-up to #915)</li>
+<li>Docs: add per-command CLI doc pages and link them from <code>clawdbot <command> --help</code>.</li>
+<li>Docs: add multi-gateway guide (sidebar + nav).</li>
+</ul>
+<h3>Fixes</h3>
+<h4>Gateway / Daemon / Sessions</h4>
+<ul>
+<li>Gateway: forward termination signals to respawned CLI child processes to avoid orphaned systemd runs. (#933) — thanks @roshanasingh4.</li>
+<li>Gateway/UI: ship session defaults in the hello snapshot so the Control UI canonicalizes main session keys (no bare <code>main</code> alias).</li>
+<li>Agents: skip thinking/final tag stripping inside Markdown code spans. (#939) — thanks @ngutman.</li>
+<li>Browser: add tests for snapshot labels/efficient query params and labeled image responses.</li>
+<li>Browser: persist role snapshot refs per CDP target so <code>snapshot</code> → <code>act</code> clicks work even if Playwright returns a different Page instance.</li>
+<li>macOS: ensure launchd log directory exists with a test-only override. (#909) — thanks @roshanasingh4.</li>
+<li>macOS: format ConnectionsStore config to satisfy SwiftFormat lint. (#852) — thanks @mneves75.</li>
+<li>Packaging: run <code>pnpm build</code> on <code>prepack</code> so npm publishes include fresh <code>dist/</code> output.</li>
+<li>Telegram: register dock native commands with underscores to avoid <code>BOT_COMMAND_INVALID</code> (#929, fixes #901) — thanks @grp06.</li>
+<li>Google: downgrade unsigned thinking blocks before send to avoid missing signature errors.</li>
+<li>Agents: make user time zone and 24-hour time explicit in the system prompt. (#859) — thanks @CashWilliams.</li>
+<li>Agents: strip downgraded tool call text without eating adjacent replies and filter thinking-tag leaks. (#905) — thanks @erikpr1994.</li>
+<li>Agents: cap tool call IDs for OpenAI/OpenRouter to avoid request rejections. (#875) — thanks @j1philli.</li>
+<li>Doctor: avoid re-adding WhatsApp config when only legacy ack reactions are set. (#927, fixes #900) — thanks @grp06.</li>
+<li>Agents: scrub tuple <code>items</code> schemas for Gemini tool calls. (#926, fixes #746) — thanks @grp06.</li>
+<li>Agents: stabilize sub-agent announce status from runtime outcomes and normalize Result/Notes. (#835) — thanks @roshanasingh4.</li>
+<li>Apps: use canonical main session keys from gateway defaults across macOS/iOS/Android to avoid creating bare <code>main</code> sessions.</li>
+<li>Embedded runner: suppress raw API error payloads from replies. (#924) — thanks @grp06.</li>
+<li>Auth: normalize Claude Code CLI profile mode to oauth and auto-migrate config. (#855) — thanks @sebslight.</li>
+<li>Daemon: clear persisted launchd disabled state before bootstrap (fixes <code>daemon install</code> after uninstall). (#849) — thanks @ndraiman.</li>
+<li>Sessions: return deep clones (<code>structuredClone</code>) so cached session entries can't be mutated. (#934) — thanks @ronak-guliani.</li>
+<li>Heartbeat: keep <code>updatedAt</code> monotonic when restoring heartbeat sessions. (#934) — thanks @ronak-guliani.</li>
+<li>Agent: clear run context after CLI runs (<code>clearAgentRunContext</code>) to avoid runaway contexts. (#934) — thanks @ronak-guliani.</li>
+<li>Gateway/Dev: ensure <code>pnpm gateway:dev</code> always uses the dev profile config + state (<code>~/.clawdbot-dev</code>).</li>
+</ul>
+<h4>CLI / Onboarding</h4>
+<ul>
+<li>Onboarding: show web search setup at the end (not the beginning).</li>
+<li>Onboarding: show daemon install/restart progress (avoid “blinking cursor”) and fix daemon install output formatting.</li>
+<li>Health: colorize “not configured” provider lines for easier scanning.</li>
+</ul>
+<h4>Control UI / TUI</h4>
+<ul>
+<li>Control UI: load cron run history on job selection and clarify empty-state messaging. (#866)</li>
+<li>UI: use application-defined WebSocket close code and fix dashboard auth query items. (#918) — thanks @rahthakor.</li>
+<li>UI: always apply <code>?token=</code> from URL (fixes unauthorized after re-onboard).</li>
+<li>Browser: add tests for snapshot labels/efficient query params and labeled image responses.</li>
+<li>TUI: render picker overlays via the overlay stack so /models and /settings display. (#921) — thanks @grizzdank.</li>
+<li>TUI: add a bright spinner + elapsed time in the status line for send/stream/run states.</li>
+<li>TUI: show LLM error messages (rate limits, auth, etc.) instead of <code>(no output)</code>.</li>
+</ul>
+<h4>Agents / Auth / Tools / Sandbox</h4>
+<ul>
+<li>Agents: make user time zone and 24-hour time explicit in the system prompt. (#859) — thanks @CashWilliams.</li>
+<li>Agents: strip downgraded tool call text without eating adjacent replies and filter thinking-tag leaks. (#905) — thanks @erikpr1994.</li>
+<li>Agents: cap tool call IDs for OpenAI/OpenRouter to avoid request rejections. (#875) — thanks @j1philli.</li>
+<li>Agents: scrub tuple <code>items</code> schemas for Gemini tool calls. (#926, fixes #746) — thanks @grp06.</li>
+<li>Agents: stabilize sub-agent announce status from runtime outcomes and normalize Result/Notes. (#835) — thanks @roshanasingh4.</li>
+<li>Auth: normalize Claude Code CLI profile mode to oauth and auto-migrate config. (#855) — thanks @sebslight.</li>
+<li>Embedded runner: suppress raw API error payloads from replies. (#924) — thanks @grp06.</li>
+<li>Logging: tolerate <code>EIO</code> from console writes to avoid gateway crashes. (#925, fixes #878) — thanks @grp06.</li>
+<li>Sandbox: restore <code>docker.binds</code> config validation and preserve configured PATH for <code>docker exec</code>. (#873) — thanks @akonyer.</li>
+<li>Google: downgrade unsigned thinking blocks before send to avoid missing signature errors.</li>
+</ul>
+<h4>macOS / Apps</h4>
+<ul>
+<li>macOS: ensure launchd log directory exists with a test-only override. (#909) — thanks @roshanasingh4.</li>
+<li>macOS: format ConnectionsStore config to satisfy SwiftFormat lint. (#852) — thanks @mneves75.</li>
+<li>macOS: pass auth token/password to dashboard URL for authenticated access. (#918) — thanks @rahthakor.</li>
+<li>macOS: reuse launchd gateway auth and skip wizard when gateway config already exists. (#917)</li>
+<li>Apps: use canonical main session keys from gateway defaults across macOS/iOS/Android to avoid creating bare <code>main</code> sessions.</li>
+<li>macOS: fix cron preview/testing payload to use <code>channel</code> key. (#867) — thanks @wes-davis.</li>
+<li>macOS: update cron testing channel arg. (#896) — thanks @ngutman.</li>
+</ul>
+<h4>Channels / Messaging</h4>
+<ul>
+<li>Slack: isolate thread history and avoid inheriting channel transcripts for new threads by default. (#758)</li>
+<li>Slack: respect <code>channels.slack.requireMention</code> default when resolving channel mention gating. (#850) — thanks @evalexpr.</li>
+<li>Slack: drop Socket Mode events with mismatched <code>api_app_id</code>/<code>team_id</code>. (#889) — thanks @roshanasingh4.</li>
+<li>Commands: add native command argument menus across Discord/Slack/Telegram. (#936) — thanks @thewilloftheshadow.</li>
+<li>Discord: isolate autoThread thread context. (#856) — thanks @davidguttman.</li>
+<li>Telegram: honor <code>channels.telegram.timeoutSeconds</code> for grammY API requests. (#863) — thanks @Snaver.</li>
+<li>Telegram: aggregate split inbound messages into one prompt (reduces “one reply per fragment”).</li>
+<li>Telegram: let control commands bypass per-chat sequentialization; always allow abort triggers.</li>
+<li>Telegram: split long captions into media + follow-up text messages. (#907) — thanks @jalehman.</li>
+<li>Telegram: migrate group config when supergroups change chat IDs. (#906) — thanks @sleontenko.</li>
+<li>Telegram: register dock native commands with underscores to avoid <code>BOT_COMMAND_INVALID</code> (#929, fixes #901) — thanks @grp06.</li>
+<li>Messaging: unify markdown formatting + format-first chunking for Slack/Telegram/Signal. (#920) — thanks @TheSethRose.</li>
+<li>iMessage: prefer handle routing for direct-message replies; include imsg RPC error details. (#935)</li>
+<li>WhatsApp: fix context isolation using wrong ID (was bot's number, now conversation ID). (#911) — thanks @tristanmanchester.</li>
+<li>WhatsApp: normalize user JIDs with device suffix for allowlist checks in groups. (#838) — thanks @peschee.</li>
+<li>WhatsApp: harden owner command auth.</li>
+<li>Auto-reply: treat trailing <code>NO_REPLY</code> tokens as silent replies.</li>
+</ul>
+<h4>Config / Doctor / Packaging</h4>
+<ul>
+<li>Config: prevent partial config writes from clobbering unrelated settings (base hash guard + merge patch for connection saves).</li>
+<li>Config/Doctor: remove legacy Clawdis env fallbacks and config/service migrations (Clawdbot-only).</li>
+<li>Doctor: avoid re-adding WhatsApp config when only legacy ack reactions are set. (#927, fixes #900) — thanks @grp06.</li>
+<li>Packaging: run <code>pnpm build</code> on <code>prepack</code> so npm publishes include fresh <code>dist/</code> output.</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.14-1/Clawdbot-2026.1.14-1.zip" length="19887144" type="application/octet-stream" sparkle:edSignature="1irKxBLt2eRtns34m/8JsjL/ZzhZQNjahwrxtArTvzaCnidS/MEnpD4nV2SHnhuo8g+fJZQpV9NoCAoEOAinCw=="/>
+        </item>
+        <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>
+            <link>https://raw.githubusercontent.com/clawdbot/clawdbot/main/appcast.xml</link>
+            <sparkle:version>5212</sparkle:version>
+            <sparkle:shortVersionString>2026.1.11-3</sparkle:shortVersionString>
+            <sparkle:minimumSystemVersion>15.0</sparkle:minimumSystemVersion>
+            <description><![CDATA[<h2>Clawdbot 2026.1.11-3</h2>
+<h3>Fixes</h3>
+<ul>
+<li>CLI: avoid top-level await warnings in the entrypoint on fresh installs.</li>
+<li>CLI: show a commit hash in the banner for npm installs (package.json gitHead fallback).</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-3/Clawdbot-2026.1.11-3.zip" length="19860758" type="application/octet-stream" sparkle:edSignature="LbvGUSjc3jGO7aVo2UVA0nEkaJbb3O4iwRBo1TBqoapdTtxnDlS3s6N+Z4vOSLRAoAm22EoZOwbpK9085c7HAQ=="/>
+        </item>
+    </channel>
+</rss>

apps/android/.gitignore

@@ -0,0 +1,5 @@
+.gradle/
+**/build/
+local.properties
+.idea/
+**/*.iml

apps/android/README.md

@@ -0,0 +1,51 @@
+## Clawdbot Node (Android) (internal)
+
+Modern Android node app: connects to the **Gateway-owned bridge** (`_clawdbot-bridge._tcp`) over TCP and exposes **Canvas + Chat + Camera**.
+
+Notes:
+- The node keeps the connection alive via a **foreground service** (persistent notification with a Disconnect action).
+- Chat always uses the shared session key **`main`** (same session across iOS/macOS/WebChat/Android).
+- Supports modern Android only (`minSdk 31`, Kotlin + Jetpack Compose).
+
+## Open in Android Studio
+- Open the folder `apps/android`.
+
+## Build / Run
+
+```bash
+cd apps/android
+./gradlew :app:assembleDebug
+./gradlew :app:installDebug
+./gradlew :app:testDebugUnitTest
+```
+
+`gradlew` auto-detects the Android SDK at `~/Library/Android/sdk` (macOS default) if `ANDROID_SDK_ROOT` / `ANDROID_HOME` are unset.
+
+## Connect / Pair
+
+1) Start the gateway (on your “master” machine):
+```bash
+pnpm clawdbot gateway --port 18789 --verbose
+```
+
+2) In the Android app:
+- Open **Settings**
+- Either select a discovered bridge under **Discovered Bridges**, or use **Advanced → Manual Bridge** (host + port).
+
+3) Approve pairing (on the gateway machine):
+```bash
+clawdbot nodes pending
+clawdbot nodes approve <requestId>
+```
+
+More details: `docs/android/connect.md`.
+
+## Permissions
+
+- Discovery:
+  - Android 13+ (`API 33+`): `NEARBY_WIFI_DEVICES`
+  - Android 12 and below: `ACCESS_FINE_LOCATION` (required for NSD scanning)
+- Foreground service notification (Android 13+): `POST_NOTIFICATIONS`
+- Camera:
+  - `CAMERA` for `camera.snap` and `camera.clip`
+  - `RECORD_AUDIO` for `camera.clip` when `includeAudio=true`

apps/android/app/build.gradle.kts

@@ -0,0 +1,127 @@
+import com.android.build.api.variant.impl.VariantOutputImpl
+
+plugins {
+  id("com.android.application")
+  id("org.jetbrains.kotlin.android")
+  id("org.jetbrains.kotlin.plugin.compose")
+  id("org.jetbrains.kotlin.plugin.serialization")
+}
+
+android {
+  namespace = "com.clawdbot.android"
+  compileSdk = 36
+
+  sourceSets {
+    getByName("main") {
+      assets.srcDir(file("../../shared/ClawdbotKit/Sources/ClawdbotKit/Resources"))
+    }
+  }
+
+  defaultConfig {
+    applicationId = "com.clawdbot.android"
+    minSdk = 31
+    targetSdk = 36
+    versionCode = 202601114
+    versionName = "2026.1.11-4"
+  }
+
+  buildTypes {
+    release {
+      isMinifyEnabled = false
+    }
+  }
+
+  buildFeatures {
+    compose = true
+    buildConfig = true
+  }
+
+  compileOptions {
+    sourceCompatibility = JavaVersion.VERSION_17
+    targetCompatibility = JavaVersion.VERSION_17
+  }
+
+  packaging {
+    resources {
+      excludes += "/META-INF/{AL2.0,LGPL2.1}"
+    }
+  }
+
+  lint {
+    disable += setOf("IconLauncherShape")
+    warningsAsErrors = true
+  }
+
+  testOptions {
+    unitTests.isIncludeAndroidResources = true
+  }
+}
+
+androidComponents {
+  onVariants { variant ->
+    variant.outputs
+      .filterIsInstance<VariantOutputImpl>()
+      .forEach { output ->
+        val versionName = output.versionName.orNull ?: "0"
+        val buildType = variant.buildType
+
+        val outputFileName = "clawdbot-${versionName}-${buildType}.apk"
+        output.outputFileName = outputFileName
+      }
+  }
+}
+kotlin {
+  compilerOptions {
+    jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+    allWarningsAsErrors.set(true)
+  }
+}
+
+dependencies {
+  val composeBom = platform("androidx.compose:compose-bom:2025.12.00")
+  implementation(composeBom)
+  androidTestImplementation(composeBom)
+
+  implementation("androidx.core:core-ktx:1.17.0")
+  implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.10.0")
+  implementation("androidx.activity:activity-compose:1.12.2")
+  implementation("androidx.webkit:webkit:1.15.0")
+
+  implementation("androidx.compose.ui:ui")
+  implementation("androidx.compose.ui:ui-tooling-preview")
+  implementation("androidx.compose.material3:material3")
+  implementation("androidx.compose.material:material-icons-extended")
+  implementation("androidx.navigation:navigation-compose:2.9.6")
+
+  debugImplementation("androidx.compose.ui:ui-tooling")
+
+  // Material Components (XML theme + resources)
+  implementation("com.google.android.material:material:1.13.0")
+
+  implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.10.2")
+  implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.9.0")
+
+  implementation("androidx.security:security-crypto:1.1.0")
+  implementation("androidx.exifinterface:exifinterface:1.4.2")
+
+  // CameraX (for node.invoke camera.* parity)
+  implementation("androidx.camera:camera-core:1.5.2")
+  implementation("androidx.camera:camera-camera2:1.5.2")
+  implementation("androidx.camera:camera-lifecycle:1.5.2")
+  implementation("androidx.camera:camera-video:1.5.2")
+  implementation("androidx.camera:camera-view:1.5.2")
+
+  // Unicast DNS-SD (Wide-Area Bonjour) for tailnet discovery domains.
+  implementation("dnsjava:dnsjava:3.6.3")
+
+  testImplementation("junit:junit:4.13.2")
+  testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.10.2")
+  testImplementation("io.kotest:kotest-runner-junit5-jvm:6.0.7")
+  testImplementation("io.kotest:kotest-assertions-core-jvm:6.0.7")
+  testImplementation("org.robolectric:robolectric:4.16")
+  testRuntimeOnly("org.junit.vintage:junit-vintage-engine:6.0.2")
+}
+
+tasks.withType<Test>().configureEach {
+  useJUnitPlatform()
+}

apps/android/app/src/main/AndroidManifest.xml

@@ -0,0 +1,49 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <uses-permission
+        android:name="android.permission.NEARBY_WIFI_DEVICES"
+        android:usesPermissionFlags="neverForLocation" />
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
+    <uses-permission android:name="android.permission.CAMERA" />
+    <uses-permission android:name="android.permission.RECORD_AUDIO" />
+    <uses-permission android:name="android.permission.SEND_SMS" />
+    <uses-feature
+        android:name="android.hardware.camera"
+        android:required="false" />
+    <uses-feature
+        android:name="android.hardware.telephony"
+        android:required="false" />
+
+    <application
+        android:name=".NodeApp"
+        android:allowBackup="true"
+        android:dataExtractionRules="@xml/data_extraction_rules"
+        android:fullBackupContent="@xml/backup_rules"
+        android:icon="@mipmap/ic_launcher"
+        android:roundIcon="@mipmap/ic_launcher_round"
+        android:label="@string/app_name"
+        android:supportsRtl="true"
+        android:networkSecurityConfig="@xml/network_security_config"
+        android:theme="@style/Theme.ClawdbotNode">
+        <service
+            android:name=".NodeForegroundService"
+            android:exported="false"
+            android:foregroundServiceType="dataSync|microphone|mediaProjection" />
+        <activity
+            android:name=".MainActivity"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+</manifest>

apps/android/app/src/main/java/com/clawdbot/android/CameraHudState.kt

@@ -0,0 +1,15 @@
+package com.clawdbot.android
+
+enum class CameraHudKind {
+  Photo,
+  Recording,
+  Success,
+  Error,
+}
+
+data class CameraHudState(
+  val token: Long,
+  val kind: CameraHudKind,
+  val message: String,
+)
+

apps/android/app/src/main/java/com/clawdbot/android/DeviceNames.kt

@@ -0,0 +1,26 @@
+package com.clawdbot.android
+
+import android.content.Context
+import android.os.Build
+import android.provider.Settings
+
+object DeviceNames {
+  fun bestDefaultNodeName(context: Context): String {
+    val deviceName =
+      runCatching {
+          Settings.Global.getString(context.contentResolver, "device_name")
+        }
+        .getOrNull()
+        ?.trim()
+        .orEmpty()
+
+    if (deviceName.isNotEmpty()) return deviceName
+
+    val model =
+      listOfNotNull(Build.MANUFACTURER?.takeIf { it.isNotBlank() }, Build.MODEL?.takeIf { it.isNotBlank() })
+        .joinToString(" ")
+        .trim()
+
+    return model.ifEmpty { "Android Node" }
+  }
+}

apps/android/app/src/main/java/com/clawdbot/android/LocationMode.kt

@@ -0,0 +1,15 @@
+package com.clawdbot.android
+
+enum class LocationMode(val rawValue: String) {
+  Off("off"),
+  WhileUsing("whileUsing"),
+  Always("always"),
+  ;
+
+  companion object {
+    fun fromRawValue(raw: String?): LocationMode {
+      val normalized = raw?.trim()?.lowercase()
+      return entries.firstOrNull { it.rawValue.lowercase() == normalized } ?: Off
+    }
+  }
+}

apps/android/app/src/main/java/com/clawdbot/android/MainActivity.kt

@@ -0,0 +1,130 @@
+package com.clawdbot.android
+
+import android.Manifest
+import android.content.pm.ApplicationInfo
+import android.os.Bundle
+import android.os.Build
+import android.view.WindowManager
+import android.webkit.WebView
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.activity.viewModels
+import androidx.compose.material3.Surface
+import androidx.compose.ui.Modifier
+import androidx.core.content.ContextCompat
+import androidx.core.view.WindowCompat
+import androidx.core.view.WindowInsetsCompat
+import androidx.core.view.WindowInsetsControllerCompat
+import androidx.lifecycle.Lifecycle
+import androidx.lifecycle.lifecycleScope
+import androidx.lifecycle.repeatOnLifecycle
+import com.clawdbot.android.ui.RootScreen
+import com.clawdbot.android.ui.ClawdbotTheme
+import kotlinx.coroutines.launch
+
+class MainActivity : ComponentActivity() {
+  private val viewModel: MainViewModel by viewModels()
+  private lateinit var permissionRequester: PermissionRequester
+  private lateinit var screenCaptureRequester: ScreenCaptureRequester
+
+  override fun onCreate(savedInstanceState: Bundle?) {
+    super.onCreate(savedInstanceState)
+    val isDebuggable = (applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE) != 0
+    WebView.setWebContentsDebuggingEnabled(isDebuggable)
+    applyImmersiveMode()
+    requestDiscoveryPermissionsIfNeeded()
+    requestNotificationPermissionIfNeeded()
+    NodeForegroundService.start(this)
+    permissionRequester = PermissionRequester(this)
+    screenCaptureRequester = ScreenCaptureRequester(this)
+    viewModel.camera.attachLifecycleOwner(this)
+    viewModel.camera.attachPermissionRequester(permissionRequester)
+    viewModel.sms.attachPermissionRequester(permissionRequester)
+    viewModel.screenRecorder.attachScreenCaptureRequester(screenCaptureRequester)
+    viewModel.screenRecorder.attachPermissionRequester(permissionRequester)
+
+    lifecycleScope.launch {
+      repeatOnLifecycle(Lifecycle.State.STARTED) {
+        viewModel.preventSleep.collect { enabled ->
+          if (enabled) {
+            window.addFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
+          } else {
+            window.clearFlags(WindowManager.LayoutParams.FLAG_KEEP_SCREEN_ON)
+          }
+        }
+      }
+    }
+
+    setContent {
+      ClawdbotTheme {
+        Surface(modifier = Modifier) {
+          RootScreen(viewModel = viewModel)
+        }
+      }
+    }
+  }
+
+  override fun onResume() {
+    super.onResume()
+    applyImmersiveMode()
+  }
+
+  override fun onWindowFocusChanged(hasFocus: Boolean) {
+    super.onWindowFocusChanged(hasFocus)
+    if (hasFocus) {
+      applyImmersiveMode()
+    }
+  }
+
+  override fun onStart() {
+    super.onStart()
+    viewModel.setForeground(true)
+  }
+
+  override fun onStop() {
+    viewModel.setForeground(false)
+    super.onStop()
+  }
+
+  private fun applyImmersiveMode() {
+    WindowCompat.setDecorFitsSystemWindows(window, false)
+    val controller = WindowInsetsControllerCompat(window, window.decorView)
+    controller.systemBarsBehavior =
+      WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE
+    controller.hide(WindowInsetsCompat.Type.systemBars())
+  }
+
+  private fun requestDiscoveryPermissionsIfNeeded() {
+    if (Build.VERSION.SDK_INT >= 33) {
+      val ok =
+        ContextCompat.checkSelfPermission(
+          this,
+          Manifest.permission.NEARBY_WIFI_DEVICES,
+        ) == android.content.pm.PackageManager.PERMISSION_GRANTED
+      if (!ok) {
+        requestPermissions(arrayOf(Manifest.permission.NEARBY_WIFI_DEVICES), 100)
+      }
+    } else {
+      val ok =
+        ContextCompat.checkSelfPermission(
+          this,
+          Manifest.permission.ACCESS_FINE_LOCATION,
+        ) == android.content.pm.PackageManager.PERMISSION_GRANTED
+      if (!ok) {
+        requestPermissions(arrayOf(Manifest.permission.ACCESS_FINE_LOCATION), 101)
+      }
+    }
+  }
+
+  private fun requestNotificationPermissionIfNeeded() {
+    if (Build.VERSION.SDK_INT < 33) return
+    val ok =
+      ContextCompat.checkSelfPermission(
+        this,
+        Manifest.permission.POST_NOTIFICATIONS,
+      ) == android.content.pm.PackageManager.PERMISSION_GRANTED
+    if (!ok) {
+      requestPermissions(arrayOf(Manifest.permission.POST_NOTIFICATIONS), 102)
+    }
+  }
+}

apps/android/app/src/main/java/com/clawdbot/android/MainViewModel.kt

@@ -0,0 +1,169 @@
+package com.clawdbot.android
+
+import android.app.Application
+import androidx.lifecycle.AndroidViewModel
+import com.clawdbot.android.bridge.BridgeEndpoint
+import com.clawdbot.android.chat.OutgoingAttachment
+import com.clawdbot.android.node.CameraCaptureManager
+import com.clawdbot.android.node.CanvasController
+import com.clawdbot.android.node.ScreenRecordManager
+import com.clawdbot.android.node.SmsManager
+import kotlinx.coroutines.flow.StateFlow
+
+class MainViewModel(app: Application) : AndroidViewModel(app) {
+  private val runtime: NodeRuntime = (app as NodeApp).runtime
+
+  val canvas: CanvasController = runtime.canvas
+  val camera: CameraCaptureManager = runtime.camera
+  val screenRecorder: ScreenRecordManager = runtime.screenRecorder
+  val sms: SmsManager = runtime.sms
+
+  val bridges: StateFlow<List<BridgeEndpoint>> = runtime.bridges
+  val discoveryStatusText: StateFlow<String> = runtime.discoveryStatusText
+
+  val isConnected: StateFlow<Boolean> = runtime.isConnected
+  val statusText: StateFlow<String> = runtime.statusText
+  val serverName: StateFlow<String?> = runtime.serverName
+  val remoteAddress: StateFlow<String?> = runtime.remoteAddress
+  val isForeground: StateFlow<Boolean> = runtime.isForeground
+  val seamColorArgb: StateFlow<Long> = runtime.seamColorArgb
+  val mainSessionKey: StateFlow<String> = runtime.mainSessionKey
+
+  val cameraHud: StateFlow<CameraHudState?> = runtime.cameraHud
+  val cameraFlashToken: StateFlow<Long> = runtime.cameraFlashToken
+  val screenRecordActive: StateFlow<Boolean> = runtime.screenRecordActive
+
+  val instanceId: StateFlow<String> = runtime.instanceId
+  val displayName: StateFlow<String> = runtime.displayName
+  val cameraEnabled: StateFlow<Boolean> = runtime.cameraEnabled
+  val locationMode: StateFlow<LocationMode> = runtime.locationMode
+  val locationPreciseEnabled: StateFlow<Boolean> = runtime.locationPreciseEnabled
+  val preventSleep: StateFlow<Boolean> = runtime.preventSleep
+  val wakeWords: StateFlow<List<String>> = runtime.wakeWords
+  val voiceWakeMode: StateFlow<VoiceWakeMode> = runtime.voiceWakeMode
+  val voiceWakeStatusText: StateFlow<String> = runtime.voiceWakeStatusText
+  val voiceWakeIsListening: StateFlow<Boolean> = runtime.voiceWakeIsListening
+  val talkEnabled: StateFlow<Boolean> = runtime.talkEnabled
+  val talkStatusText: StateFlow<String> = runtime.talkStatusText
+  val talkIsListening: StateFlow<Boolean> = runtime.talkIsListening
+  val talkIsSpeaking: StateFlow<Boolean> = runtime.talkIsSpeaking
+  val manualEnabled: StateFlow<Boolean> = runtime.manualEnabled
+  val manualHost: StateFlow<String> = runtime.manualHost
+  val manualPort: StateFlow<Int> = runtime.manualPort
+  val canvasDebugStatusEnabled: StateFlow<Boolean> = runtime.canvasDebugStatusEnabled
+
+  val chatSessionKey: StateFlow<String> = runtime.chatSessionKey
+  val chatSessionId: StateFlow<String?> = runtime.chatSessionId
+  val chatMessages = runtime.chatMessages
+  val chatError: StateFlow<String?> = runtime.chatError
+  val chatHealthOk: StateFlow<Boolean> = runtime.chatHealthOk
+  val chatThinkingLevel: StateFlow<String> = runtime.chatThinkingLevel
+  val chatStreamingAssistantText: StateFlow<String?> = runtime.chatStreamingAssistantText
+  val chatPendingToolCalls = runtime.chatPendingToolCalls
+  val chatSessions = runtime.chatSessions
+  val pendingRunCount: StateFlow<Int> = runtime.pendingRunCount
+
+  fun setForeground(value: Boolean) {
+    runtime.setForeground(value)
+  }
+
+  fun setDisplayName(value: String) {
+    runtime.setDisplayName(value)
+  }
+
+  fun setCameraEnabled(value: Boolean) {
+    runtime.setCameraEnabled(value)
+  }
+
+  fun setLocationMode(mode: LocationMode) {
+    runtime.setLocationMode(mode)
+  }
+
+  fun setLocationPreciseEnabled(value: Boolean) {
+    runtime.setLocationPreciseEnabled(value)
+  }
+
+  fun setPreventSleep(value: Boolean) {
+    runtime.setPreventSleep(value)
+  }
+
+  fun setManualEnabled(value: Boolean) {
+    runtime.setManualEnabled(value)
+  }
+
+  fun setManualHost(value: String) {
+    runtime.setManualHost(value)
+  }
+
+  fun setManualPort(value: Int) {
+    runtime.setManualPort(value)
+  }
+
+  fun setCanvasDebugStatusEnabled(value: Boolean) {
+    runtime.setCanvasDebugStatusEnabled(value)
+  }
+
+  fun setWakeWords(words: List<String>) {
+    runtime.setWakeWords(words)
+  }
+
+  fun resetWakeWordsDefaults() {
+    runtime.resetWakeWordsDefaults()
+  }
+
+  fun setVoiceWakeMode(mode: VoiceWakeMode) {
+    runtime.setVoiceWakeMode(mode)
+  }
+
+  fun setTalkEnabled(enabled: Boolean) {
+    runtime.setTalkEnabled(enabled)
+  }
+
+  fun refreshBridgeHello() {
+    runtime.refreshBridgeHello()
+  }
+
+  fun connect(endpoint: BridgeEndpoint) {
+    runtime.connect(endpoint)
+  }
+
+  fun connectManual() {
+    runtime.connectManual()
+  }
+
+  fun disconnect() {
+    runtime.disconnect()
+  }
+
+  fun handleCanvasA2UIActionFromWebView(payloadJson: String) {
+    runtime.handleCanvasA2UIActionFromWebView(payloadJson)
+  }
+
+  fun loadChat(sessionKey: String) {
+    runtime.loadChat(sessionKey)
+  }
+
+  fun refreshChat() {
+    runtime.refreshChat()
+  }
+
+  fun refreshChatSessions(limit: Int? = null) {
+    runtime.refreshChatSessions(limit = limit)
+  }
+
+  fun setChatThinkingLevel(level: String) {
+    runtime.setChatThinkingLevel(level)
+  }
+
+  fun switchChatSession(sessionKey: String) {
+    runtime.switchChatSession(sessionKey)
+  }
+
+  fun abortChat() {
+    runtime.abortChat()
+  }
+
+  fun sendChat(message: String, thinking: String, attachments: List<OutgoingAttachment>) {
+    runtime.sendChat(message = message, thinking = thinking, attachments = attachments)
+  }
+}

apps/android/app/src/main/java/com/clawdbot/android/NodeApp.kt

@@ -0,0 +1,26 @@
+package com.clawdbot.android
+
+import android.app.Application
+import android.os.StrictMode
+
+class NodeApp : Application() {
+  val runtime: NodeRuntime by lazy { NodeRuntime(this) }
+
+  override fun onCreate() {
+    super.onCreate()
+    if (BuildConfig.DEBUG) {
+      StrictMode.setThreadPolicy(
+        StrictMode.ThreadPolicy.Builder()
+          .detectAll()
+          .penaltyLog()
+          .build(),
+      )
+      StrictMode.setVmPolicy(
+        StrictMode.VmPolicy.Builder()
+          .detectAll()
+          .penaltyLog()
+          .build(),
+      )
+    }
+  }
+}

apps/android/app/src/main/java/com/clawdbot/android/NodeForegroundService.kt

@@ -0,0 +1,180 @@
+package com.clawdbot.android
+
+import android.app.Notification
+import android.app.NotificationChannel
+import android.app.NotificationManager
+import android.app.Service
+import android.app.PendingIntent
+import android.Manifest
+import android.content.Context
+import android.content.Intent
+import android.content.pm.PackageManager
+import android.content.pm.ServiceInfo
+import androidx.core.app.NotificationCompat
+import androidx.core.content.ContextCompat
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.cancel
+import kotlinx.coroutines.flow.combine
+import kotlinx.coroutines.launch
+
+class NodeForegroundService : Service() {
+  private val scope: CoroutineScope = CoroutineScope(SupervisorJob() + Dispatchers.Main)
+  private var notificationJob: Job? = null
+  private var lastRequiresMic = false
+  private var didStartForeground = false
+
+  override fun onCreate() {
+    super.onCreate()
+    ensureChannel()
+    val initial = buildNotification(title = "Clawdbot Node", text = "Starting…")
+    startForegroundWithTypes(notification = initial, requiresMic = false)
+
+    val runtime = (application as NodeApp).runtime
+    notificationJob =
+      scope.launch {
+        combine(
+          runtime.statusText,
+          runtime.serverName,
+          runtime.isConnected,
+          runtime.voiceWakeMode,
+          runtime.voiceWakeIsListening,
+        ) { status, server, connected, voiceMode, voiceListening ->
+          Quint(status, server, connected, voiceMode, voiceListening)
+        }.collect { (status, server, connected, voiceMode, voiceListening) ->
+          val title = if (connected) "Clawdbot Node · Connected" else "Clawdbot Node"
+          val voiceSuffix =
+            if (voiceMode == VoiceWakeMode.Always) {
+              if (voiceListening) " · Voice Wake: Listening" else " · Voice Wake: Paused"
+            } else {
+              ""
+            }
+          val text = (server?.let { "$status · $it" } ?: status) + voiceSuffix
+
+          val requiresMic =
+            voiceMode == VoiceWakeMode.Always && hasRecordAudioPermission()
+          startForegroundWithTypes(
+            notification = buildNotification(title = title, text = text),
+            requiresMic = requiresMic,
+          )
+        }
+      }
+  }
+
+  override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+    when (intent?.action) {
+      ACTION_STOP -> {
+        (application as NodeApp).runtime.disconnect()
+        stopSelf()
+        return START_NOT_STICKY
+      }
+    }
+    // Keep running; connection is managed by NodeRuntime (auto-reconnect + manual).
+    return START_STICKY
+  }
+
+  override fun onDestroy() {
+    notificationJob?.cancel()
+    scope.cancel()
+    super.onDestroy()
+  }
+
+  override fun onBind(intent: Intent?) = null
+
+  private fun ensureChannel() {
+    val mgr = getSystemService(NotificationManager::class.java)
+    val channel =
+      NotificationChannel(
+        CHANNEL_ID,
+        "Connection",
+        NotificationManager.IMPORTANCE_LOW,
+      ).apply {
+        description = "Clawdbot node connection status"
+        setShowBadge(false)
+      }
+    mgr.createNotificationChannel(channel)
+  }
+
+  private fun buildNotification(title: String, text: String): Notification {
+    val launchIntent = Intent(this, MainActivity::class.java).apply {
+      flags = Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_CLEAR_TOP
+    }
+    val launchPending =
+      PendingIntent.getActivity(
+        this,
+        1,
+        launchIntent,
+        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+      )
+
+    val stopIntent = Intent(this, NodeForegroundService::class.java).setAction(ACTION_STOP)
+    val stopPending =
+      PendingIntent.getService(
+        this,
+        2,
+        stopIntent,
+        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+      )
+
+    return NotificationCompat.Builder(this, CHANNEL_ID)
+      .setSmallIcon(R.mipmap.ic_launcher)
+      .setContentTitle(title)
+      .setContentText(text)
+      .setContentIntent(launchPending)
+      .setOngoing(true)
+      .setOnlyAlertOnce(true)
+      .setForegroundServiceBehavior(NotificationCompat.FOREGROUND_SERVICE_IMMEDIATE)
+      .addAction(0, "Disconnect", stopPending)
+      .build()
+  }
+
+  private fun updateNotification(notification: Notification) {
+    val mgr = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
+    mgr.notify(NOTIFICATION_ID, notification)
+  }
+
+  private fun startForegroundWithTypes(notification: Notification, requiresMic: Boolean) {
+    if (didStartForeground && requiresMic == lastRequiresMic) {
+      updateNotification(notification)
+      return
+    }
+
+    lastRequiresMic = requiresMic
+    val types =
+      if (requiresMic) {
+        ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC or ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE
+      } else {
+        ServiceInfo.FOREGROUND_SERVICE_TYPE_DATA_SYNC
+      }
+    startForeground(NOTIFICATION_ID, notification, types)
+    didStartForeground = true
+  }
+
+  private fun hasRecordAudioPermission(): Boolean {
+    return (
+      ContextCompat.checkSelfPermission(this, Manifest.permission.RECORD_AUDIO) ==
+        PackageManager.PERMISSION_GRANTED
+      )
+  }
+
+  companion object {
+    private const val CHANNEL_ID = "connection"
+    private const val NOTIFICATION_ID = 1
+
+    private const val ACTION_STOP = "com.clawdbot.android.action.STOP"
+
+    fun start(context: Context) {
+      val intent = Intent(context, NodeForegroundService::class.java)
+      context.startForegroundService(intent)
+    }
+
+    fun stop(context: Context) {
+      val intent = Intent(context, NodeForegroundService::class.java).setAction(ACTION_STOP)
+      context.startService(intent)
+    }
+  }
+}
+
+private data class Quint<A, B, C, D, E>(val first: A, val second: B, val third: C, val fourth: D, val fifth: E)

apps/android/app/src/main/java/com/clawdbot/android/PermissionRequester.kt

@@ -0,0 +1,133 @@
+package com.clawdbot.android
+
+import android.content.pm.PackageManager
+import android.content.Intent
+import android.Manifest
+import android.net.Uri
+import android.provider.Settings
+import androidx.appcompat.app.AlertDialog
+import androidx.activity.ComponentActivity
+import androidx.activity.result.ActivityResultLauncher
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.core.content.ContextCompat
+import androidx.core.app.ActivityCompat
+import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import kotlinx.coroutines.withContext
+import kotlinx.coroutines.suspendCancellableCoroutine
+import kotlin.coroutines.resume
+
+class PermissionRequester(private val activity: ComponentActivity) {
+  private val mutex = Mutex()
+  private var pending: CompletableDeferred<Map<String, Boolean>>? = null
+
+  private val launcher: ActivityResultLauncher<Array<String>> =
+    activity.registerForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) { result ->
+      val p = pending
+      pending = null
+      p?.complete(result)
+    }
+
+  suspend fun requestIfMissing(
+    permissions: List<String>,
+    timeoutMs: Long = 20_000,
+  ): Map<String, Boolean> =
+    mutex.withLock {
+      val missing =
+        permissions.filter { perm ->
+          ContextCompat.checkSelfPermission(activity, perm) != PackageManager.PERMISSION_GRANTED
+        }
+      if (missing.isEmpty()) {
+        return permissions.associateWith { true }
+      }
+
+      val needsRationale =
+        missing.any { ActivityCompat.shouldShowRequestPermissionRationale(activity, it) }
+      if (needsRationale) {
+        val proceed = showRationaleDialog(missing)
+        if (!proceed) {
+          return permissions.associateWith { perm ->
+            ContextCompat.checkSelfPermission(activity, perm) == PackageManager.PERMISSION_GRANTED
+          }
+        }
+      }
+
+      val deferred = CompletableDeferred<Map<String, Boolean>>()
+      pending = deferred
+      withContext(Dispatchers.Main) {
+        launcher.launch(missing.toTypedArray())
+      }
+
+      val result =
+        withContext(Dispatchers.Default) {
+          kotlinx.coroutines.withTimeout(timeoutMs) { deferred.await() }
+        }
+
+      // Merge: if something was already granted, treat it as granted even if launcher omitted it.
+      val merged =
+        permissions.associateWith { perm ->
+        val nowGranted =
+          ContextCompat.checkSelfPermission(activity, perm) == PackageManager.PERMISSION_GRANTED
+        result[perm] == true || nowGranted
+      }
+
+      val denied =
+        merged.filterValues { !it }.keys.filter {
+          !ActivityCompat.shouldShowRequestPermissionRationale(activity, it)
+        }
+      if (denied.isNotEmpty()) {
+        showSettingsDialog(denied)
+      }
+
+      return merged
+    }
+
+  private suspend fun showRationaleDialog(permissions: List<String>): Boolean =
+    withContext(Dispatchers.Main) {
+      suspendCancellableCoroutine { cont ->
+        AlertDialog.Builder(activity)
+          .setTitle("Permission required")
+          .setMessage(buildRationaleMessage(permissions))
+          .setPositiveButton("Continue") { _, _ -> cont.resume(true) }
+          .setNegativeButton("Not now") { _, _ -> cont.resume(false) }
+          .setOnCancelListener { cont.resume(false) }
+          .show()
+      }
+    }
+
+  private fun showSettingsDialog(permissions: List<String>) {
+    AlertDialog.Builder(activity)
+      .setTitle("Enable permission in Settings")
+      .setMessage(buildSettingsMessage(permissions))
+      .setPositiveButton("Open Settings") { _, _ ->
+        val intent =
+          Intent(
+            Settings.ACTION_APPLICATION_DETAILS_SETTINGS,
+            Uri.fromParts("package", activity.packageName, null),
+          )
+        activity.startActivity(intent)
+      }
+      .setNegativeButton("Cancel", null)
+      .show()
+  }
+
+  private fun buildRationaleMessage(permissions: List<String>): String {
+    val labels = permissions.map { permissionLabel(it) }
+    return "Clawdbot needs ${labels.joinToString(", ")} permissions to continue."
+  }
+
+  private fun buildSettingsMessage(permissions: List<String>): String {
+    val labels = permissions.map { permissionLabel(it) }
+    return "Please enable ${labels.joinToString(", ")} in Android Settings to continue."
+  }
+
+  private fun permissionLabel(permission: String): String =
+    when (permission) {
+      Manifest.permission.CAMERA -> "Camera"
+      Manifest.permission.RECORD_AUDIO -> "Microphone"
+      Manifest.permission.SEND_SMS -> "SMS"
+      else -> permission
+    }
+}

apps/android/app/src/main/java/com/clawdbot/android/ScreenCaptureRequester.kt

@@ -0,0 +1,65 @@
+package com.clawdbot.android
+
+import android.app.Activity
+import android.content.Context
+import android.content.Intent
+import android.media.projection.MediaProjectionManager
+import androidx.activity.ComponentActivity
+import androidx.activity.result.ActivityResultLauncher
+import androidx.activity.result.contract.ActivityResultContracts
+import androidx.appcompat.app.AlertDialog
+import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import kotlinx.coroutines.withContext
+import kotlinx.coroutines.withTimeout
+import kotlinx.coroutines.suspendCancellableCoroutine
+import kotlin.coroutines.resume
+
+class ScreenCaptureRequester(private val activity: ComponentActivity) {
+  data class CaptureResult(val resultCode: Int, val data: Intent)
+
+  private val mutex = Mutex()
+  private var pending: CompletableDeferred<CaptureResult?>? = null
+
+  private val launcher: ActivityResultLauncher<Intent> =
+    activity.registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result ->
+      val p = pending
+      pending = null
+      val data = result.data
+      if (result.resultCode == Activity.RESULT_OK && data != null) {
+        p?.complete(CaptureResult(result.resultCode, data))
+      } else {
+        p?.complete(null)
+      }
+    }
+
+  suspend fun requestCapture(timeoutMs: Long = 20_000): CaptureResult? =
+    mutex.withLock {
+      val proceed = showRationaleDialog()
+      if (!proceed) return null
+
+      val mgr = activity.getSystemService(Context.MEDIA_PROJECTION_SERVICE) as MediaProjectionManager
+      val intent = mgr.createScreenCaptureIntent()
+
+      val deferred = CompletableDeferred<CaptureResult?>()
+      pending = deferred
+      withContext(Dispatchers.Main) { launcher.launch(intent) }
+
+      withContext(Dispatchers.Default) { withTimeout(timeoutMs) { deferred.await() } }
+    }
+
+  private suspend fun showRationaleDialog(): Boolean =
+    withContext(Dispatchers.Main) {
+      suspendCancellableCoroutine { cont ->
+        AlertDialog.Builder(activity)
+          .setTitle("Screen recording required")
+          .setMessage("Clawdbot needs to record the screen for this command.")
+          .setPositiveButton("Continue") { _, _ -> cont.resume(true) }
+          .setNegativeButton("Not now") { _, _ -> cont.resume(false) }
+          .setOnCancelListener { cont.resume(false) }
+          .show()
+      }
+    }
+}

apps/android/app/src/main/java/com/clawdbot/android/SecurePrefs.kt

@@ -0,0 +1,228 @@
+@file:Suppress("DEPRECATION")
+
+package com.clawdbot.android
+
+import android.content.Context
+import androidx.core.content.edit
+import androidx.security.crypto.EncryptedSharedPreferences
+import androidx.security.crypto.MasterKey
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonArray
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonPrimitive
+import java.util.UUID
+
+class SecurePrefs(context: Context) {
+  companion object {
+    val defaultWakeWords: List<String> = listOf("clawd", "claude")
+    private const val displayNameKey = "node.displayName"
+    private const val voiceWakeModeKey = "voiceWake.mode"
+  }
+
+  private val json = Json { ignoreUnknownKeys = true }
+
+  private val masterKey =
+    MasterKey.Builder(context)
+      .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
+      .build()
+
+  private val prefs =
+    EncryptedSharedPreferences.create(
+      context,
+      "clawdbot.node.secure",
+      masterKey,
+      EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
+      EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM,
+    )
+
+  private val _instanceId = MutableStateFlow(loadOrCreateInstanceId())
+  val instanceId: StateFlow<String> = _instanceId
+
+  private val _displayName =
+    MutableStateFlow(loadOrMigrateDisplayName(context = context))
+  val displayName: StateFlow<String> = _displayName
+
+  private val _cameraEnabled = MutableStateFlow(prefs.getBoolean("camera.enabled", true))
+  val cameraEnabled: StateFlow<Boolean> = _cameraEnabled
+
+  private val _locationMode =
+    MutableStateFlow(LocationMode.fromRawValue(prefs.getString("location.enabledMode", "off")))
+  val locationMode: StateFlow<LocationMode> = _locationMode
+
+  private val _locationPreciseEnabled =
+    MutableStateFlow(prefs.getBoolean("location.preciseEnabled", true))
+  val locationPreciseEnabled: StateFlow<Boolean> = _locationPreciseEnabled
+
+  private val _preventSleep = MutableStateFlow(prefs.getBoolean("screen.preventSleep", true))
+  val preventSleep: StateFlow<Boolean> = _preventSleep
+
+  private val _manualEnabled = MutableStateFlow(prefs.getBoolean("bridge.manual.enabled", false))
+  val manualEnabled: StateFlow<Boolean> = _manualEnabled
+
+  private val _manualHost = MutableStateFlow(prefs.getString("bridge.manual.host", "")!!)
+  val manualHost: StateFlow<String> = _manualHost
+
+  private val _manualPort = MutableStateFlow(prefs.getInt("bridge.manual.port", 18790))
+  val manualPort: StateFlow<Int> = _manualPort
+
+  private val _lastDiscoveredStableId =
+    MutableStateFlow(prefs.getString("bridge.lastDiscoveredStableId", "")!!)
+  val lastDiscoveredStableId: StateFlow<String> = _lastDiscoveredStableId
+
+  private val _canvasDebugStatusEnabled =
+    MutableStateFlow(prefs.getBoolean("canvas.debugStatusEnabled", false))
+  val canvasDebugStatusEnabled: StateFlow<Boolean> = _canvasDebugStatusEnabled
+
+  private val _wakeWords = MutableStateFlow(loadWakeWords())
+  val wakeWords: StateFlow<List<String>> = _wakeWords
+
+  private val _voiceWakeMode = MutableStateFlow(loadVoiceWakeMode())
+  val voiceWakeMode: StateFlow<VoiceWakeMode> = _voiceWakeMode
+
+  private val _talkEnabled = MutableStateFlow(prefs.getBoolean("talk.enabled", false))
+  val talkEnabled: StateFlow<Boolean> = _talkEnabled
+
+  fun setLastDiscoveredStableId(value: String) {
+    val trimmed = value.trim()
+    prefs.edit { putString("bridge.lastDiscoveredStableId", trimmed) }
+    _lastDiscoveredStableId.value = trimmed
+  }
+
+  fun setDisplayName(value: String) {
+    val trimmed = value.trim()
+    prefs.edit { putString(displayNameKey, trimmed) }
+    _displayName.value = trimmed
+  }
+
+  fun setCameraEnabled(value: Boolean) {
+    prefs.edit { putBoolean("camera.enabled", value) }
+    _cameraEnabled.value = value
+  }
+
+  fun setLocationMode(mode: LocationMode) {
+    prefs.edit { putString("location.enabledMode", mode.rawValue) }
+    _locationMode.value = mode
+  }
+
+  fun setLocationPreciseEnabled(value: Boolean) {
+    prefs.edit { putBoolean("location.preciseEnabled", value) }
+    _locationPreciseEnabled.value = value
+  }
+
+  fun setPreventSleep(value: Boolean) {
+    prefs.edit { putBoolean("screen.preventSleep", value) }
+    _preventSleep.value = value
+  }
+
+  fun setManualEnabled(value: Boolean) {
+    prefs.edit { putBoolean("bridge.manual.enabled", value) }
+    _manualEnabled.value = value
+  }
+
+  fun setManualHost(value: String) {
+    val trimmed = value.trim()
+    prefs.edit { putString("bridge.manual.host", trimmed) }
+    _manualHost.value = trimmed
+  }
+
+  fun setManualPort(value: Int) {
+    prefs.edit { putInt("bridge.manual.port", value) }
+    _manualPort.value = value
+  }
+
+  fun setCanvasDebugStatusEnabled(value: Boolean) {
+    prefs.edit { putBoolean("canvas.debugStatusEnabled", value) }
+    _canvasDebugStatusEnabled.value = value
+  }
+
+  fun loadBridgeToken(): String? {
+    val key = "bridge.token.${_instanceId.value}"
+    return prefs.getString(key, null)
+  }
+
+  fun saveBridgeToken(token: String) {
+    val key = "bridge.token.${_instanceId.value}"
+    prefs.edit { putString(key, token.trim()) }
+  }
+
+  fun loadBridgeTlsFingerprint(stableId: String): String? {
+    val key = "bridge.tls.$stableId"
+    return prefs.getString(key, null)?.trim()?.takeIf { it.isNotEmpty() }
+  }
+
+  fun saveBridgeTlsFingerprint(stableId: String, fingerprint: String) {
+    val key = "bridge.tls.$stableId"
+    prefs.edit { putString(key, fingerprint.trim()) }
+  }
+
+  private fun loadOrCreateInstanceId(): String {
+    val existing = prefs.getString("node.instanceId", null)?.trim()
+    if (!existing.isNullOrBlank()) return existing
+    val fresh = UUID.randomUUID().toString()
+    prefs.edit { putString("node.instanceId", fresh) }
+    return fresh
+  }
+
+  private fun loadOrMigrateDisplayName(context: Context): String {
+    val existing = prefs.getString(displayNameKey, null)?.trim().orEmpty()
+    if (existing.isNotEmpty() && existing != "Android Node") return existing
+
+    val candidate = DeviceNames.bestDefaultNodeName(context).trim()
+    val resolved = candidate.ifEmpty { "Android Node" }
+
+    prefs.edit { putString(displayNameKey, resolved) }
+    return resolved
+  }
+
+  fun setWakeWords(words: List<String>) {
+    val sanitized = WakeWords.sanitize(words, defaultWakeWords)
+    val encoded =
+      JsonArray(sanitized.map { JsonPrimitive(it) }).toString()
+    prefs.edit { putString("voiceWake.triggerWords", encoded) }
+    _wakeWords.value = sanitized
+  }
+
+  fun setVoiceWakeMode(mode: VoiceWakeMode) {
+    prefs.edit { putString(voiceWakeModeKey, mode.rawValue) }
+    _voiceWakeMode.value = mode
+  }
+
+  fun setTalkEnabled(value: Boolean) {
+    prefs.edit { putBoolean("talk.enabled", value) }
+    _talkEnabled.value = value
+  }
+
+  private fun loadVoiceWakeMode(): VoiceWakeMode {
+    val raw = prefs.getString(voiceWakeModeKey, null)
+    val resolved = VoiceWakeMode.fromRawValue(raw)
+
+    // Default ON (foreground) when unset.
+    if (raw.isNullOrBlank()) {
+      prefs.edit { putString(voiceWakeModeKey, resolved.rawValue) }
+    }
+
+    return resolved
+  }
+
+  private fun loadWakeWords(): List<String> {
+    val raw = prefs.getString("voiceWake.triggerWords", null)?.trim()
+    if (raw.isNullOrEmpty()) return defaultWakeWords
+    return try {
+      val element = json.parseToJsonElement(raw)
+      val array = element as? JsonArray ?: return defaultWakeWords
+      val decoded =
+        array.mapNotNull { item ->
+          when (item) {
+            is JsonNull -> null
+            is JsonPrimitive -> item.content.trim().takeIf { it.isNotEmpty() }
+            else -> null
+          }
+        }
+      WakeWords.sanitize(decoded, defaultWakeWords)
+    } catch (_: Throwable) {
+      defaultWakeWords
+    }
+  }
+}

apps/android/app/src/main/java/com/clawdbot/android/SessionKey.kt

@@ -0,0 +1,13 @@
+package com.clawdbot.android
+
+internal fun normalizeMainKey(raw: String?): String {
+  val trimmed = raw?.trim()
+  return if (!trimmed.isNullOrEmpty()) trimmed else "main"
+}
+
+internal fun isCanonicalMainSessionKey(raw: String?): Boolean {
+  val trimmed = raw?.trim().orEmpty()
+  if (trimmed.isEmpty()) return false
+  if (trimmed == "global") return true
+  return trimmed.startsWith("agent:")
+}

apps/android/app/src/main/java/com/clawdbot/android/VoiceWakeMode.kt

@@ -0,0 +1,15 @@
+package com.clawdbot.android
+
+enum class VoiceWakeMode(val rawValue: String) {
+  Off("off"),
+  Foreground("foreground"),
+  Always("always"),
+  ;
+
+  companion object {
+    fun fromRawValue(raw: String?): VoiceWakeMode {
+      return entries.firstOrNull { it.rawValue == raw?.trim()?.lowercase() } ?: Foreground
+    }
+  }
+}
+

apps/android/app/src/main/java/com/clawdbot/android/WakeWords.kt

@@ -0,0 +1,17 @@
+package com.clawdbot.android
+
+object WakeWords {
+  const val maxWords: Int = 32
+  const val maxWordLength: Int = 64
+
+  fun parseCommaSeparated(input: String): List<String> {
+    return input.split(",").map { it.trim() }.filter { it.isNotEmpty() }
+  }
+
+  fun sanitize(words: List<String>, defaults: List<String>): List<String> {
+    val cleaned =
+      words.map { it.trim() }.filter { it.isNotEmpty() }.take(maxWords).map { it.take(maxWordLength) }
+    return cleaned.ifEmpty { defaults }
+  }
+}
+

apps/android/app/src/main/java/com/clawdbot/android/bridge/BonjourEscapes.kt

@@ -0,0 +1,35 @@
+package com.clawdbot.android.bridge
+
+object BonjourEscapes {
+  fun decode(input: String): String {
+    if (input.isEmpty()) return input
+
+    val bytes = mutableListOf<Byte>()
+    var i = 0
+    while (i < input.length) {
+      if (input[i] == '\\' && i + 3 < input.length) {
+        val d0 = input[i + 1]
+        val d1 = input[i + 2]
+        val d2 = input[i + 3]
+        if (d0.isDigit() && d1.isDigit() && d2.isDigit()) {
+          val value =
+            ((d0.code - '0'.code) * 100) + ((d1.code - '0'.code) * 10) + (d2.code - '0'.code)
+          if (value in 0..255) {
+            bytes.add(value.toByte())
+            i += 4
+            continue
+          }
+        }
+      }
+
+      val codePoint = Character.codePointAt(input, i)
+      val charBytes = String(Character.toChars(codePoint)).toByteArray(Charsets.UTF_8)
+      for (b in charBytes) {
+        bytes.add(b)
+      }
+      i += Character.charCount(codePoint)
+    }
+
+    return String(bytes.toByteArray(), Charsets.UTF_8)
+  }
+}

apps/android/app/src/main/java/com/clawdbot/android/bridge/BridgeDiscovery.kt

@@ -0,0 +1,523 @@
+package com.clawdbot.android.bridge
+
+import android.content.Context
+import android.net.ConnectivityManager
+import android.net.DnsResolver
+import android.net.NetworkCapabilities
+import android.net.nsd.NsdManager
+import android.net.nsd.NsdServiceInfo
+import android.os.CancellationSignal
+import android.util.Log
+import java.io.IOException
+import java.net.InetSocketAddress
+import java.nio.ByteBuffer
+import java.nio.charset.CodingErrorAction
+import java.util.concurrent.ConcurrentHashMap
+import java.util.concurrent.Executor
+import java.util.concurrent.Executors
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.suspendCancellableCoroutine
+import org.xbill.DNS.AAAARecord
+import org.xbill.DNS.ARecord
+import org.xbill.DNS.DClass
+import org.xbill.DNS.ExtendedResolver
+import org.xbill.DNS.Message
+import org.xbill.DNS.Name
+import org.xbill.DNS.PTRRecord
+import org.xbill.DNS.Record
+import org.xbill.DNS.Rcode
+import org.xbill.DNS.Resolver
+import org.xbill.DNS.SRVRecord
+import org.xbill.DNS.Section
+import org.xbill.DNS.SimpleResolver
+import org.xbill.DNS.TextParseException
+import org.xbill.DNS.TXTRecord
+import org.xbill.DNS.Type
+import kotlin.coroutines.resume
+import kotlin.coroutines.resumeWithException
+
+@Suppress("DEPRECATION")
+class BridgeDiscovery(
+  context: Context,
+  private val scope: CoroutineScope,
+) {
+  private val nsd = context.getSystemService(NsdManager::class.java)
+  private val connectivity = context.getSystemService(ConnectivityManager::class.java)
+  private val dns = DnsResolver.getInstance()
+  private val serviceType = "_clawdbot-bridge._tcp."
+  private val wideAreaDomain = "clawdbot.internal."
+  private val logTag = "Clawdbot/BridgeDiscovery"
+
+  private val localById = ConcurrentHashMap<String, BridgeEndpoint>()
+  private val unicastById = ConcurrentHashMap<String, BridgeEndpoint>()
+  private val _bridges = MutableStateFlow<List<BridgeEndpoint>>(emptyList())
+  val bridges: StateFlow<List<BridgeEndpoint>> = _bridges.asStateFlow()
+
+  private val _statusText = MutableStateFlow("Searching…")
+  val statusText: StateFlow<String> = _statusText.asStateFlow()
+
+  private var unicastJob: Job? = null
+  private val dnsExecutor: Executor = Executors.newCachedThreadPool()
+
+  @Volatile private var lastWideAreaRcode: Int? = null
+  @Volatile private var lastWideAreaCount: Int = 0
+
+  private val discoveryListener =
+    object : NsdManager.DiscoveryListener {
+      override fun onStartDiscoveryFailed(serviceType: String, errorCode: Int) {}
+      override fun onStopDiscoveryFailed(serviceType: String, errorCode: Int) {}
+      override fun onDiscoveryStarted(serviceType: String) {}
+      override fun onDiscoveryStopped(serviceType: String) {}
+
+      override fun onServiceFound(serviceInfo: NsdServiceInfo) {
+        if (serviceInfo.serviceType != this@BridgeDiscovery.serviceType) return
+        resolve(serviceInfo)
+      }
+
+      override fun onServiceLost(serviceInfo: NsdServiceInfo) {
+        val serviceName = BonjourEscapes.decode(serviceInfo.serviceName)
+        val id = stableId(serviceName, "local.")
+        localById.remove(id)
+        publish()
+      }
+    }
+
+  init {
+    startLocalDiscovery()
+    startUnicastDiscovery(wideAreaDomain)
+  }
+
+  private fun startLocalDiscovery() {
+    try {
+      nsd.discoverServices(serviceType, NsdManager.PROTOCOL_DNS_SD, discoveryListener)
+    } catch (_: Throwable) {
+      // ignore (best-effort)
+    }
+  }
+
+  private fun stopLocalDiscovery() {
+    try {
+      nsd.stopServiceDiscovery(discoveryListener)
+    } catch (_: Throwable) {
+      // ignore (best-effort)
+    }
+  }
+
+  private fun startUnicastDiscovery(domain: String) {
+    unicastJob =
+      scope.launch(Dispatchers.IO) {
+        while (true) {
+          try {
+            refreshUnicast(domain)
+          } catch (_: Throwable) {
+            // ignore (best-effort)
+          }
+          delay(5000)
+        }
+      }
+  }
+
+  private fun resolve(serviceInfo: NsdServiceInfo) {
+    nsd.resolveService(
+      serviceInfo,
+      object : NsdManager.ResolveListener {
+        override fun onResolveFailed(serviceInfo: NsdServiceInfo, errorCode: Int) {}
+
+      override fun onServiceResolved(resolved: NsdServiceInfo) {
+        val host = resolved.host?.hostAddress ?: return
+        val port = resolved.port
+        if (port <= 0) return
+
+        val rawServiceName = resolved.serviceName
+        val serviceName = BonjourEscapes.decode(rawServiceName)
+        val displayName = BonjourEscapes.decode(txt(resolved, "displayName") ?: serviceName)
+        val lanHost = txt(resolved, "lanHost")
+        val tailnetDns = txt(resolved, "tailnetDns")
+        val gatewayPort = txtInt(resolved, "gatewayPort")
+        val bridgePort = txtInt(resolved, "bridgePort")
+        val canvasPort = txtInt(resolved, "canvasPort")
+        val tlsEnabled = txtBool(resolved, "bridgeTls")
+        val tlsFingerprint = txt(resolved, "bridgeTlsSha256")
+        val id = stableId(serviceName, "local.")
+        localById[id] =
+          BridgeEndpoint(
+            stableId = id,
+            name = displayName,
+            host = host,
+            port = port,
+            lanHost = lanHost,
+            tailnetDns = tailnetDns,
+            gatewayPort = gatewayPort,
+            bridgePort = bridgePort,
+            canvasPort = canvasPort,
+            tlsEnabled = tlsEnabled,
+            tlsFingerprintSha256 = tlsFingerprint,
+          )
+        publish()
+      }
+    },
+  )
+  }
+
+  private fun publish() {
+    _bridges.value =
+      (localById.values + unicastById.values).sortedBy { it.name.lowercase() }
+    _statusText.value = buildStatusText()
+  }
+
+  private fun buildStatusText(): String {
+    val localCount = localById.size
+    val wideRcode = lastWideAreaRcode
+    val wideCount = lastWideAreaCount
+
+    val wide =
+      when (wideRcode) {
+        null -> "Wide: ?"
+        Rcode.NOERROR -> "Wide: $wideCount"
+        Rcode.NXDOMAIN -> "Wide: NXDOMAIN"
+        else -> "Wide: ${Rcode.string(wideRcode)}"
+      }
+
+    return when {
+      localCount == 0 && wideRcode == null -> "Searching for bridges…"
+      localCount == 0 -> "$wide"
+      else -> "Local: $localCount • $wide"
+    }
+  }
+
+  private fun stableId(serviceName: String, domain: String): String {
+    return "${serviceType}|${domain}|${normalizeName(serviceName)}"
+  }
+
+  private fun normalizeName(raw: String): String {
+    return raw.trim().split(Regex("\\s+")).joinToString(" ")
+  }
+
+  private fun txt(info: NsdServiceInfo, key: String): String? {
+    val bytes = info.attributes[key] ?: return null
+    return try {
+      String(bytes, Charsets.UTF_8).trim().ifEmpty { null }
+    } catch (_: Throwable) {
+      null
+    }
+  }
+
+  private fun txtInt(info: NsdServiceInfo, key: String): Int? {
+    return txt(info, key)?.toIntOrNull()
+  }
+
+  private fun txtBool(info: NsdServiceInfo, key: String): Boolean {
+    val raw = txt(info, key)?.trim()?.lowercase() ?: return false
+    return raw == "1" || raw == "true" || raw == "yes"
+  }
+
+  private suspend fun refreshUnicast(domain: String) {
+    val ptrName = "${serviceType}${domain}"
+    val ptrMsg = lookupUnicastMessage(ptrName, Type.PTR) ?: return
+    val ptrRecords = records(ptrMsg, Section.ANSWER).mapNotNull { it as? PTRRecord }
+
+    val next = LinkedHashMap<String, BridgeEndpoint>()
+    for (ptr in ptrRecords) {
+      val instanceFqdn = ptr.target.toString()
+      val srv =
+        recordByName(ptrMsg, instanceFqdn, Type.SRV) as? SRVRecord
+          ?: run {
+            val msg = lookupUnicastMessage(instanceFqdn, Type.SRV) ?: return@run null
+            recordByName(msg, instanceFqdn, Type.SRV) as? SRVRecord
+          }
+          ?: continue
+      val port = srv.port
+      if (port <= 0) continue
+
+      val targetFqdn = srv.target.toString()
+      val host =
+        resolveHostFromMessage(ptrMsg, targetFqdn)
+          ?: resolveHostFromMessage(lookupUnicastMessage(instanceFqdn, Type.SRV), targetFqdn)
+          ?: resolveHostUnicast(targetFqdn)
+          ?: continue
+
+      val txtFromPtr =
+        recordsByName(ptrMsg, Section.ADDITIONAL)[keyName(instanceFqdn)]
+          .orEmpty()
+          .mapNotNull { it as? TXTRecord }
+      val txt =
+        if (txtFromPtr.isNotEmpty()) {
+          txtFromPtr
+        } else {
+          val msg = lookupUnicastMessage(instanceFqdn, Type.TXT)
+          records(msg, Section.ANSWER).mapNotNull { it as? TXTRecord }
+        }
+      val instanceName = BonjourEscapes.decode(decodeInstanceName(instanceFqdn, domain))
+      val displayName = BonjourEscapes.decode(txtValue(txt, "displayName") ?: instanceName)
+      val lanHost = txtValue(txt, "lanHost")
+      val tailnetDns = txtValue(txt, "tailnetDns")
+      val gatewayPort = txtIntValue(txt, "gatewayPort")
+      val bridgePort = txtIntValue(txt, "bridgePort")
+      val canvasPort = txtIntValue(txt, "canvasPort")
+      val tlsEnabled = txtBoolValue(txt, "bridgeTls")
+      val tlsFingerprint = txtValue(txt, "bridgeTlsSha256")
+      val id = stableId(instanceName, domain)
+      next[id] =
+        BridgeEndpoint(
+          stableId = id,
+          name = displayName,
+          host = host,
+          port = port,
+          lanHost = lanHost,
+          tailnetDns = tailnetDns,
+          gatewayPort = gatewayPort,
+          bridgePort = bridgePort,
+          canvasPort = canvasPort,
+          tlsEnabled = tlsEnabled,
+          tlsFingerprintSha256 = tlsFingerprint,
+        )
+    }
+
+    unicastById.clear()
+    unicastById.putAll(next)
+    lastWideAreaRcode = ptrMsg.header.rcode
+    lastWideAreaCount = next.size
+    publish()
+
+    if (next.isEmpty()) {
+      Log.d(
+        logTag,
+        "wide-area discovery: 0 results for $ptrName (rcode=${Rcode.string(ptrMsg.header.rcode)})",
+      )
+    }
+  }
+
+  private fun decodeInstanceName(instanceFqdn: String, domain: String): String {
+    val suffix = "${serviceType}${domain}"
+    val withoutSuffix =
+      if (instanceFqdn.endsWith(suffix)) {
+        instanceFqdn.removeSuffix(suffix)
+      } else {
+        instanceFqdn.substringBefore(serviceType)
+      }
+    return normalizeName(stripTrailingDot(withoutSuffix))
+  }
+
+  private fun stripTrailingDot(raw: String): String {
+    return raw.removeSuffix(".")
+  }
+
+  private suspend fun lookupUnicastMessage(name: String, type: Int): Message? {
+    val query =
+      try {
+        Message.newQuery(
+          org.xbill.DNS.Record.newRecord(
+            Name.fromString(name),
+            type,
+            DClass.IN,
+          ),
+        )
+      } catch (_: TextParseException) {
+        return null
+      }
+
+    val system = queryViaSystemDns(query)
+    if (records(system, Section.ANSWER).any { it.type == type }) return system
+
+    val direct = createDirectResolver() ?: return system
+    return try {
+      val msg = direct.send(query)
+      if (records(msg, Section.ANSWER).any { it.type == type }) msg else system
+    } catch (_: Throwable) {
+      system
+    }
+  }
+
+  private suspend fun queryViaSystemDns(query: Message): Message? {
+    val network = preferredDnsNetwork()
+    val bytes =
+      try {
+        rawQuery(network, query.toWire())
+      } catch (_: Throwable) {
+        return null
+      }
+
+    return try {
+      Message(bytes)
+    } catch (_: IOException) {
+      null
+    }
+  }
+
+  private fun records(msg: Message?, section: Int): List<Record> {
+    return msg?.getSectionArray(section)?.toList() ?: emptyList()
+  }
+
+  private fun keyName(raw: String): String {
+    return raw.trim().lowercase()
+  }
+
+  private fun recordsByName(msg: Message, section: Int): Map<String, List<Record>> {
+    val next = LinkedHashMap<String, MutableList<Record>>()
+    for (r in records(msg, section)) {
+      val name = r.name?.toString() ?: continue
+      next.getOrPut(keyName(name)) { mutableListOf() }.add(r)
+    }
+    return next
+  }
+
+  private fun recordByName(msg: Message, fqdn: String, type: Int): Record? {
+    val key = keyName(fqdn)
+    val byNameAnswer = recordsByName(msg, Section.ANSWER)
+    val fromAnswer = byNameAnswer[key].orEmpty().firstOrNull { it.type == type }
+    if (fromAnswer != null) return fromAnswer
+
+    val byNameAdditional = recordsByName(msg, Section.ADDITIONAL)
+    return byNameAdditional[key].orEmpty().firstOrNull { it.type == type }
+  }
+
+  private fun resolveHostFromMessage(msg: Message?, hostname: String): String? {
+    val m = msg ?: return null
+    val key = keyName(hostname)
+    val additional = recordsByName(m, Section.ADDITIONAL)[key].orEmpty()
+    val a = additional.mapNotNull { it as? ARecord }.mapNotNull { it.address?.hostAddress }
+    val aaaa = additional.mapNotNull { it as? AAAARecord }.mapNotNull { it.address?.hostAddress }
+    return a.firstOrNull() ?: aaaa.firstOrNull()
+  }
+
+  private fun preferredDnsNetwork(): android.net.Network? {
+    val cm = connectivity ?: return null
+
+    // Prefer VPN (Tailscale) when present; otherwise use the active network.
+    cm.allNetworks.firstOrNull { n ->
+      val caps = cm.getNetworkCapabilities(n) ?: return@firstOrNull false
+      caps.hasTransport(NetworkCapabilities.TRANSPORT_VPN)
+    }?.let { return it }
+
+    return cm.activeNetwork
+  }
+
+  private fun createDirectResolver(): Resolver? {
+    val cm = connectivity ?: return null
+
+    val candidateNetworks =
+      buildList {
+        cm.allNetworks
+          .firstOrNull { n ->
+            val caps = cm.getNetworkCapabilities(n) ?: return@firstOrNull false
+            caps.hasTransport(NetworkCapabilities.TRANSPORT_VPN)
+          }?.let(::add)
+        cm.activeNetwork?.let(::add)
+      }.distinct()
+
+    val servers =
+      candidateNetworks
+        .asSequence()
+        .flatMap { n ->
+          cm.getLinkProperties(n)?.dnsServers?.asSequence() ?: emptySequence()
+        }
+        .distinctBy { it.hostAddress ?: it.toString() }
+        .toList()
+    if (servers.isEmpty()) return null
+
+    return try {
+      val resolvers =
+        servers.mapNotNull { addr ->
+          try {
+            SimpleResolver().apply {
+              setAddress(InetSocketAddress(addr, 53))
+              setTimeout(3)
+            }
+          } catch (_: Throwable) {
+            null
+          }
+        }
+      if (resolvers.isEmpty()) return null
+      ExtendedResolver(resolvers.toTypedArray()).apply { setTimeout(3) }
+    } catch (_: Throwable) {
+      null
+    }
+  }
+
+  private suspend fun rawQuery(network: android.net.Network?, wireQuery: ByteArray): ByteArray =
+    suspendCancellableCoroutine { cont ->
+      val signal = CancellationSignal()
+      cont.invokeOnCancellation { signal.cancel() }
+
+      dns.rawQuery(
+        network,
+        wireQuery,
+        DnsResolver.FLAG_EMPTY,
+        dnsExecutor,
+        signal,
+        object : DnsResolver.Callback<ByteArray> {
+          override fun onAnswer(answer: ByteArray, rcode: Int) {
+            cont.resume(answer)
+          }
+
+          override fun onError(error: DnsResolver.DnsException) {
+            cont.resumeWithException(error)
+          }
+        },
+      )
+    }
+
+  private fun txtValue(records: List<TXTRecord>, key: String): String? {
+    val prefix = "$key="
+    for (r in records) {
+      val strings: List<String> =
+        try {
+          r.strings.mapNotNull { it as? String }
+        } catch (_: Throwable) {
+          emptyList()
+        }
+      for (s in strings) {
+        val trimmed = decodeDnsTxtString(s).trim()
+        if (trimmed.startsWith(prefix)) {
+          return trimmed.removePrefix(prefix).trim().ifEmpty { null }
+        }
+      }
+    }
+    return null
+  }
+
+  private fun txtIntValue(records: List<TXTRecord>, key: String): Int? {
+    return txtValue(records, key)?.toIntOrNull()
+  }
+
+  private fun txtBoolValue(records: List<TXTRecord>, key: String): Boolean {
+    val raw = txtValue(records, key)?.trim()?.lowercase() ?: return false
+    return raw == "1" || raw == "true" || raw == "yes"
+  }
+
+  private fun decodeDnsTxtString(raw: String): String {
+    // dnsjava treats TXT as opaque bytes and decodes as ISO-8859-1 to preserve bytes.
+    // Our TXT payload is UTF-8 (written by the gateway), so re-decode when possible.
+    val bytes = raw.toByteArray(Charsets.ISO_8859_1)
+    val decoder =
+      Charsets.UTF_8
+        .newDecoder()
+        .onMalformedInput(CodingErrorAction.REPORT)
+        .onUnmappableCharacter(CodingErrorAction.REPORT)
+    return try {
+      decoder.decode(ByteBuffer.wrap(bytes)).toString()
+    } catch (_: Throwable) {
+      raw
+    }
+  }
+
+  private suspend fun resolveHostUnicast(hostname: String): String? {
+    val a =
+      records(lookupUnicastMessage(hostname, Type.A), Section.ANSWER)
+        .mapNotNull { it as? ARecord }
+        .mapNotNull { it.address?.hostAddress }
+    val aaaa =
+      records(lookupUnicastMessage(hostname, Type.AAAA), Section.ANSWER)
+        .mapNotNull { it as? AAAARecord }
+        .mapNotNull { it.address?.hostAddress }
+
+    return a.firstOrNull() ?: aaaa.firstOrNull()
+  }
+}

apps/android/app/src/main/java/com/clawdbot/android/bridge/BridgeEndpoint.kt

@@ -0,0 +1,27 @@
+package com.clawdbot.android.bridge
+
+data class BridgeEndpoint(
+  val stableId: String,
+  val name: String,
+  val host: String,
+  val port: Int,
+  val lanHost: String? = null,
+  val tailnetDns: String? = null,
+  val gatewayPort: Int? = null,
+  val bridgePort: Int? = null,
+  val canvasPort: Int? = null,
+  val tlsEnabled: Boolean = false,
+  val tlsFingerprintSha256: String? = null,
+) {
+  companion object {
+    fun manual(host: String, port: Int): BridgeEndpoint =
+      BridgeEndpoint(
+        stableId = "manual|$host|$port",
+        name = "$host:$port",
+        host = host,
+        port = port,
+        tlsEnabled = false,
+        tlsFingerprintSha256 = null,
+      )
+  }
+}

apps/android/app/src/main/java/com/clawdbot/android/bridge/BridgePairingClient.kt

@@ -0,0 +1,158 @@
+package com.clawdbot.android.bridge
+
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonArray
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.buildJsonObject
+import java.io.BufferedReader
+import java.io.BufferedWriter
+import java.io.InputStreamReader
+import java.io.OutputStreamWriter
+import java.net.InetSocketAddress
+
+class BridgePairingClient {
+  private val json = Json { ignoreUnknownKeys = true }
+
+  data class Hello(
+    val nodeId: String,
+    val displayName: String?,
+    val token: String?,
+    val platform: String?,
+    val version: String?,
+    val deviceFamily: String?,
+    val modelIdentifier: String?,
+    val caps: List<String>?,
+    val commands: List<String>?,
+  )
+
+  data class PairResult(val ok: Boolean, val token: String?, val error: String? = null)
+
+  suspend fun pairAndHello(
+    endpoint: BridgeEndpoint,
+    hello: Hello,
+    tls: BridgeTlsParams? = null,
+    onTlsFingerprint: ((String) -> Unit)? = null,
+  ): PairResult =
+    withContext(Dispatchers.IO) {
+      if (tls != null) {
+        try {
+          return@withContext pairAndHelloWithTls(endpoint, hello, tls, onTlsFingerprint)
+        } catch (e: Exception) {
+          if (tls.required) throw e
+        }
+      }
+      pairAndHelloWithTls(endpoint, hello, null, null)
+    }
+
+  private fun pairAndHelloWithTls(
+    endpoint: BridgeEndpoint,
+    hello: Hello,
+    tls: BridgeTlsParams?,
+    onTlsFingerprint: ((String) -> Unit)?,
+  ): PairResult {
+    val socket =
+      createBridgeSocket(tls) { fingerprint ->
+        onTlsFingerprint?.invoke(fingerprint)
+      }
+    socket.tcpNoDelay = true
+    try {
+      socket.connect(InetSocketAddress(endpoint.host, endpoint.port), 8_000)
+      socket.soTimeout = 60_000
+      startTlsHandshakeIfNeeded(socket)
+
+      val reader = BufferedReader(InputStreamReader(socket.getInputStream(), Charsets.UTF_8))
+      val writer = BufferedWriter(OutputStreamWriter(socket.getOutputStream(), Charsets.UTF_8))
+
+      fun send(line: String) {
+        writer.write(line)
+        writer.write("\n")
+        writer.flush()
+      }
+
+      fun sendJson(obj: JsonObject) = send(obj.toString())
+
+      sendJson(
+        buildJsonObject {
+          put("type", JsonPrimitive("hello"))
+          put("nodeId", JsonPrimitive(hello.nodeId))
+          hello.displayName?.let { put("displayName", JsonPrimitive(it)) }
+          hello.token?.let { put("token", JsonPrimitive(it)) }
+          hello.platform?.let { put("platform", JsonPrimitive(it)) }
+          hello.version?.let { put("version", JsonPrimitive(it)) }
+          hello.deviceFamily?.let { put("deviceFamily", JsonPrimitive(it)) }
+          hello.modelIdentifier?.let { put("modelIdentifier", JsonPrimitive(it)) }
+          hello.caps?.let { put("caps", JsonArray(it.map(::JsonPrimitive))) }
+          hello.commands?.let { put("commands", JsonArray(it.map(::JsonPrimitive))) }
+        },
+      )
+
+      val firstObj = json.parseToJsonElement(reader.readLine()).asObjectOrNull()
+        ?: return PairResult(ok = false, token = null, error = "unexpected bridge response")
+      return when (firstObj["type"].asStringOrNull()) {
+        "hello-ok" -> PairResult(ok = true, token = hello.token)
+        "error" -> {
+          val code = firstObj["code"].asStringOrNull() ?: "UNAVAILABLE"
+          val message = firstObj["message"].asStringOrNull() ?: "pairing required"
+          if (code != "NOT_PAIRED" && code != "UNAUTHORIZED") {
+            return PairResult(ok = false, token = null, error = "$code: $message")
+          }
+
+          sendJson(
+            buildJsonObject {
+              put("type", JsonPrimitive("pair-request"))
+              put("nodeId", JsonPrimitive(hello.nodeId))
+              hello.displayName?.let { put("displayName", JsonPrimitive(it)) }
+              hello.platform?.let { put("platform", JsonPrimitive(it)) }
+              hello.version?.let { put("version", JsonPrimitive(it)) }
+              hello.deviceFamily?.let { put("deviceFamily", JsonPrimitive(it)) }
+              hello.modelIdentifier?.let { put("modelIdentifier", JsonPrimitive(it)) }
+              hello.caps?.let { put("caps", JsonArray(it.map(::JsonPrimitive))) }
+              hello.commands?.let { put("commands", JsonArray(it.map(::JsonPrimitive))) }
+            },
+          )
+
+          while (true) {
+            val nextLine = reader.readLine() ?: break
+            val next = json.parseToJsonElement(nextLine).asObjectOrNull() ?: continue
+            when (next["type"].asStringOrNull()) {
+              "pair-ok" -> {
+                val token = next["token"].asStringOrNull()
+                return PairResult(ok = !token.isNullOrBlank(), token = token)
+              }
+              "error" -> {
+                val c = next["code"].asStringOrNull() ?: "UNAVAILABLE"
+                val m = next["message"].asStringOrNull() ?: "pairing failed"
+                return PairResult(ok = false, token = null, error = "$c: $m")
+              }
+            }
+          }
+          PairResult(ok = false, token = null, error = "pairing failed")
+        }
+        else -> PairResult(ok = false, token = null, error = "unexpected bridge response")
+      }
+    } catch (e: Exception) {
+      val message = e.message?.trim().orEmpty().ifEmpty { "gateway unreachable" }
+      return PairResult(ok = false, token = null, error = message)
+    } finally {
+      try {
+        socket.close()
+      } catch (_: Throwable) {
+        // ignore
+      }
+    }
+  }
+}
+
+private fun JsonElement?.asObjectOrNull(): JsonObject? = this as? JsonObject
+
+private fun JsonElement?.asStringOrNull(): String? =
+  when (this) {
+    is JsonNull -> null
+    is JsonPrimitive -> content
+    else -> null
+  }

apps/android/app/src/main/java/com/clawdbot/android/bridge/BridgeSession.kt

@@ -0,0 +1,398 @@
+package com.clawdbot.android.bridge
+
+import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.cancelAndJoin
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.isActive
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.sync.Mutex
+import kotlinx.coroutines.sync.withLock
+import kotlinx.coroutines.withContext
+import com.clawdbot.android.BuildConfig
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonArray
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.buildJsonObject
+import java.io.BufferedReader
+import java.io.BufferedWriter
+import java.io.InputStreamReader
+import java.io.OutputStreamWriter
+import java.net.InetSocketAddress
+import java.net.URI
+import java.net.Socket
+import java.util.UUID
+import java.util.concurrent.ConcurrentHashMap
+
+class BridgeSession(
+  private val scope: CoroutineScope,
+  private val onConnected: (serverName: String, remoteAddress: String?, mainSessionKey: String?) -> Unit,
+  private val onDisconnected: (message: String) -> Unit,
+  private val onEvent: (event: String, payloadJson: String?) -> Unit,
+  private val onInvoke: suspend (InvokeRequest) -> InvokeResult,
+  private val onTlsFingerprint: ((stableId: String, fingerprint: String) -> Unit)? = null,
+) {
+  data class Hello(
+    val nodeId: String,
+    val displayName: String?,
+    val token: String?,
+    val platform: String?,
+    val version: String?,
+    val deviceFamily: String?,
+    val modelIdentifier: String?,
+    val caps: List<String>?,
+    val commands: List<String>?,
+  )
+
+  data class InvokeRequest(val id: String, val command: String, val paramsJson: String?)
+
+  data class InvokeResult(val ok: Boolean, val payloadJson: String?, val error: ErrorShape?) {
+    companion object {
+      fun ok(payloadJson: String?) = InvokeResult(ok = true, payloadJson = payloadJson, error = null)
+      fun error(code: String, message: String) =
+        InvokeResult(ok = false, payloadJson = null, error = ErrorShape(code = code, message = message))
+    }
+  }
+
+  data class ErrorShape(val code: String, val message: String)
+
+  private val json = Json { ignoreUnknownKeys = true }
+  private val writeLock = Mutex()
+  private val pending = ConcurrentHashMap<String, CompletableDeferred<RpcResponse>>()
+  @Volatile private var canvasHostUrl: String? = null
+  @Volatile private var mainSessionKey: String? = null
+
+  private data class DesiredConnection(
+    val endpoint: BridgeEndpoint,
+    val hello: Hello,
+    val tls: BridgeTlsParams?,
+  )
+
+  private var desired: DesiredConnection? = null
+  private var job: Job? = null
+
+  fun connect(endpoint: BridgeEndpoint, hello: Hello, tls: BridgeTlsParams? = null) {
+    desired = DesiredConnection(endpoint, hello, tls)
+    if (job == null) {
+      job = scope.launch(Dispatchers.IO) { runLoop() }
+    }
+  }
+
+  suspend fun updateHello(hello: Hello) {
+    val target = desired ?: return
+    desired = target.copy(hello = hello)
+    val conn = currentConnection ?: return
+    conn.sendJson(buildHelloJson(hello))
+  }
+
+  fun disconnect() {
+    desired = null
+    // Unblock connectOnce() read loop. Coroutine cancellation alone won't interrupt BufferedReader.readLine().
+    currentConnection?.closeQuietly()
+    scope.launch(Dispatchers.IO) {
+      job?.cancelAndJoin()
+      job = null
+      canvasHostUrl = null
+      mainSessionKey = null
+      onDisconnected("Offline")
+    }
+  }
+
+  fun currentCanvasHostUrl(): String? = canvasHostUrl
+  fun currentMainSessionKey(): String? = mainSessionKey
+
+  suspend fun sendEvent(event: String, payloadJson: String?) {
+    val conn = currentConnection ?: return
+    conn.sendJson(
+      buildJsonObject {
+        put("type", JsonPrimitive("event"))
+        put("event", JsonPrimitive(event))
+        if (payloadJson != null) put("payloadJSON", JsonPrimitive(payloadJson)) else put("payloadJSON", JsonNull)
+      },
+    )
+  }
+
+  suspend fun request(method: String, paramsJson: String?): String {
+    val conn = currentConnection ?: throw IllegalStateException("not connected")
+    val id = UUID.randomUUID().toString()
+    val deferred = CompletableDeferred<RpcResponse>()
+    pending[id] = deferred
+    conn.sendJson(
+      buildJsonObject {
+        put("type", JsonPrimitive("req"))
+        put("id", JsonPrimitive(id))
+        put("method", JsonPrimitive(method))
+        if (paramsJson != null) put("paramsJSON", JsonPrimitive(paramsJson)) else put("paramsJSON", JsonNull)
+      },
+    )
+    val res = deferred.await()
+    if (res.ok) return res.payloadJson ?: ""
+    val err = res.error
+    throw IllegalStateException("${err?.code ?: "UNAVAILABLE"}: ${err?.message ?: "request failed"}")
+  }
+
+  private data class RpcResponse(val id: String, val ok: Boolean, val payloadJson: String?, val error: ErrorShape?)
+
+  private class Connection(private val socket: Socket, private val reader: BufferedReader, private val writer: BufferedWriter, private val writeLock: Mutex) {
+    val remoteAddress: String? =
+      socket.inetAddress?.hostAddress?.takeIf { it.isNotBlank() }?.let { "${it}:${socket.port}" }
+
+    suspend fun sendJson(obj: JsonObject) {
+      writeLock.withLock {
+        writer.write(obj.toString())
+        writer.write("\n")
+        writer.flush()
+      }
+    }
+
+    fun closeQuietly() {
+      try {
+        socket.close()
+      } catch (_: Throwable) {
+        // ignore
+      }
+    }
+  }
+
+  @Volatile private var currentConnection: Connection? = null
+
+  private suspend fun runLoop() {
+    var attempt = 0
+    while (scope.isActive) {
+      val target = desired
+      if (target == null) {
+        currentConnection?.closeQuietly()
+        currentConnection = null
+        delay(250)
+        continue
+      }
+
+      val (endpoint, hello, tls) = target
+      try {
+        onDisconnected(if (attempt == 0) "Connecting…" else "Reconnecting…")
+        connectOnce(endpoint, hello, tls)
+        attempt = 0
+      } catch (err: Throwable) {
+        attempt += 1
+        onDisconnected("Bridge error: ${err.message ?: err::class.java.simpleName}")
+        val sleepMs = minOf(8_000L, (350.0 * Math.pow(1.7, attempt.toDouble())).toLong())
+        delay(sleepMs)
+      }
+    }
+  }
+
+  private fun invokeErrorFromThrowable(err: Throwable): InvokeResult {
+    val msg = err.message?.trim().takeIf { !it.isNullOrEmpty() } ?: err::class.java.simpleName
+    val parts = msg.split(":", limit = 2)
+    if (parts.size == 2) {
+      val code = parts[0].trim()
+      val rest = parts[1].trim()
+      if (code.isNotEmpty() && code.all { it.isUpperCase() || it == '_' }) {
+        return InvokeResult.error(code = code, message = rest.ifEmpty { msg })
+      }
+    }
+    return InvokeResult.error(code = "UNAVAILABLE", message = msg)
+  }
+
+  private suspend fun connectOnce(endpoint: BridgeEndpoint, hello: Hello, tls: BridgeTlsParams?) =
+    withContext(Dispatchers.IO) {
+      if (tls != null) {
+        try {
+          connectWithSocket(endpoint, hello, tls)
+          return@withContext
+        } catch (err: Throwable) {
+          if (tls.required) throw err
+        }
+      }
+      connectWithSocket(endpoint, hello, null)
+    }
+
+  private suspend fun connectWithSocket(endpoint: BridgeEndpoint, hello: Hello, tls: BridgeTlsParams?) {
+    val socket =
+      createBridgeSocket(tls) { fingerprint ->
+        onTlsFingerprint?.invoke(tls?.stableId ?: endpoint.stableId, fingerprint)
+      }
+    socket.tcpNoDelay = true
+    socket.connect(InetSocketAddress(endpoint.host, endpoint.port), 8_000)
+    socket.soTimeout = 0
+    startTlsHandshakeIfNeeded(socket)
+
+    val reader = BufferedReader(InputStreamReader(socket.getInputStream(), Charsets.UTF_8))
+    val writer = BufferedWriter(OutputStreamWriter(socket.getOutputStream(), Charsets.UTF_8))
+
+    val conn = Connection(socket, reader, writer, writeLock)
+    currentConnection = conn
+
+    try {
+      conn.sendJson(buildHelloJson(hello))
+
+      val firstLine = reader.readLine() ?: throw IllegalStateException("bridge closed connection")
+      val first = json.parseToJsonElement(firstLine).asObjectOrNull()
+        ?: throw IllegalStateException("unexpected bridge response")
+      when (first["type"].asStringOrNull()) {
+        "hello-ok" -> {
+          val name = first["serverName"].asStringOrNull() ?: "Bridge"
+          val rawCanvasUrl = first["canvasHostUrl"].asStringOrNull()?.trim()?.ifEmpty { null }
+          val rawMainSessionKey = first["mainSessionKey"].asStringOrNull()?.trim()?.ifEmpty { null }
+          canvasHostUrl = normalizeCanvasHostUrl(rawCanvasUrl, endpoint)
+          mainSessionKey = rawMainSessionKey
+          if (BuildConfig.DEBUG) {
+            // Local JVM unit tests use android.jar stubs; Log.d can throw "not mocked".
+            runCatching {
+              android.util.Log.d(
+                "ClawdbotBridge",
+                "canvasHostUrl resolved=${canvasHostUrl ?: "none"} (raw=${rawCanvasUrl ?: "none"})",
+              )
+            }
+          }
+          onConnected(name, conn.remoteAddress, rawMainSessionKey)
+        }
+        "error" -> {
+          val code = first["code"].asStringOrNull() ?: "UNAVAILABLE"
+          val msg = first["message"].asStringOrNull() ?: "connect failed"
+          throw IllegalStateException("$code: $msg")
+        }
+        else -> throw IllegalStateException("unexpected bridge response")
+      }
+
+      while (scope.isActive) {
+        val line = reader.readLine() ?: break
+        val frame = json.parseToJsonElement(line).asObjectOrNull() ?: continue
+        when (frame["type"].asStringOrNull()) {
+          "event" -> {
+            val event = frame["event"].asStringOrNull() ?: continue
+            val payload = frame["payloadJSON"].asStringOrNull()
+            onEvent(event, payload)
+          }
+            "ping" -> {
+              val id = frame["id"].asStringOrNull() ?: ""
+              conn.sendJson(buildJsonObject { put("type", JsonPrimitive("pong")); put("id", JsonPrimitive(id)) })
+            }
+            "res" -> {
+              val id = frame["id"].asStringOrNull() ?: continue
+              val ok = frame["ok"].asBooleanOrNull() ?: false
+              val payloadJson = frame["payloadJSON"].asStringOrNull()
+              val error =
+                frame["error"]?.let {
+                  val obj = it.asObjectOrNull() ?: return@let null
+                  val code = obj["code"].asStringOrNull() ?: "UNAVAILABLE"
+                  val msg = obj["message"].asStringOrNull() ?: "request failed"
+                  ErrorShape(code, msg)
+                }
+              pending.remove(id)?.complete(RpcResponse(id, ok, payloadJson, error))
+            }
+            "invoke" -> {
+              val id = frame["id"].asStringOrNull() ?: continue
+              val command = frame["command"].asStringOrNull() ?: ""
+              val params = frame["paramsJSON"].asStringOrNull()
+              val result =
+                try {
+                  onInvoke(InvokeRequest(id, command, params))
+                } catch (err: Throwable) {
+                  invokeErrorFromThrowable(err)
+                }
+              conn.sendJson(
+                buildJsonObject {
+                  put("type", JsonPrimitive("invoke-res"))
+                  put("id", JsonPrimitive(id))
+                  put("ok", JsonPrimitive(result.ok))
+                  if (result.payloadJson != null) put("payloadJSON", JsonPrimitive(result.payloadJson))
+                  if (result.error != null) {
+                    put(
+                      "error",
+                      buildJsonObject {
+                        put("code", JsonPrimitive(result.error.code))
+                        put("message", JsonPrimitive(result.error.message))
+                      },
+                    )
+                  }
+                },
+              )
+            }
+          "invoke-res" -> {
+            // gateway->node only (ignore)
+          }
+        }
+      }
+    } finally {
+      currentConnection = null
+      for ((_, waiter) in pending) {
+        waiter.cancel()
+      }
+      pending.clear()
+      conn.closeQuietly()
+    }
+  }
+
+  private fun buildHelloJson(hello: Hello): JsonObject =
+    buildJsonObject {
+      put("type", JsonPrimitive("hello"))
+      put("nodeId", JsonPrimitive(hello.nodeId))
+      hello.displayName?.let { put("displayName", JsonPrimitive(it)) }
+      hello.token?.let { put("token", JsonPrimitive(it)) }
+      hello.platform?.let { put("platform", JsonPrimitive(it)) }
+      hello.version?.let { put("version", JsonPrimitive(it)) }
+      hello.deviceFamily?.let { put("deviceFamily", JsonPrimitive(it)) }
+      hello.modelIdentifier?.let { put("modelIdentifier", JsonPrimitive(it)) }
+      hello.caps?.let { put("caps", JsonArray(it.map(::JsonPrimitive))) }
+      hello.commands?.let { put("commands", JsonArray(it.map(::JsonPrimitive))) }
+    }
+
+  private fun normalizeCanvasHostUrl(raw: String?, endpoint: BridgeEndpoint): String? {
+    val trimmed = raw?.trim().orEmpty()
+    val parsed = trimmed.takeIf { it.isNotBlank() }?.let { runCatching { URI(it) }.getOrNull() }
+    val host = parsed?.host?.trim().orEmpty()
+    val port = parsed?.port ?: -1
+    val scheme = parsed?.scheme?.trim().orEmpty().ifBlank { "http" }
+
+    if (trimmed.isNotBlank() && !isLoopbackHost(host)) {
+      return trimmed
+    }
+
+    val fallbackHost =
+      endpoint.tailnetDns?.trim().takeIf { !it.isNullOrEmpty() }
+        ?: endpoint.lanHost?.trim().takeIf { !it.isNullOrEmpty() }
+        ?: endpoint.host.trim()
+    if (fallbackHost.isEmpty()) return trimmed.ifBlank { null }
+
+    val fallbackPort = endpoint.canvasPort ?: if (port > 0) port else 18793
+    val formattedHost = if (fallbackHost.contains(":")) "[${fallbackHost}]" else fallbackHost
+    return "$scheme://$formattedHost:$fallbackPort"
+  }
+
+  private fun isLoopbackHost(raw: String?): Boolean {
+    val host = raw?.trim()?.lowercase().orEmpty()
+    if (host.isEmpty()) return false
+    if (host == "localhost") return true
+    if (host == "::1") return true
+    if (host == "0.0.0.0" || host == "::") return true
+    return host.startsWith("127.")
+  }
+}
+
+private fun JsonElement?.asObjectOrNull(): JsonObject? = this as? JsonObject
+
+private fun JsonElement?.asStringOrNull(): String? =
+  when (this) {
+    is JsonNull -> null
+    is JsonPrimitive -> content
+    else -> null
+  }
+
+private fun JsonElement?.asBooleanOrNull(): Boolean? =
+  when (this) {
+    is JsonPrimitive -> {
+      val c = content.trim()
+      when {
+        c.equals("true", ignoreCase = true) -> true
+        c.equals("false", ignoreCase = true) -> false
+        else -> null
+      }
+    }
+    else -> null
+  }

apps/android/app/src/main/java/com/clawdbot/android/bridge/BridgeTls.kt

@@ -0,0 +1,81 @@
+package com.clawdbot.android.bridge
+
+import android.annotation.SuppressLint
+import java.net.Socket
+import java.security.MessageDigest
+import java.security.SecureRandom
+import java.security.cert.CertificateException
+import java.security.cert.X509Certificate
+import javax.net.ssl.SSLContext
+import javax.net.ssl.SSLSocket
+import javax.net.ssl.TrustManagerFactory
+import javax.net.ssl.X509TrustManager
+
+data class BridgeTlsParams(
+  val required: Boolean,
+  val expectedFingerprint: String?,
+  val allowTOFU: Boolean,
+  val stableId: String,
+)
+
+fun createBridgeSocket(params: BridgeTlsParams?, onStore: ((String) -> Unit)? = null): Socket {
+  if (params == null) return Socket()
+  val expected = params.expectedFingerprint?.let(::normalizeFingerprint)
+  val defaultTrust = defaultTrustManager()
+  @SuppressLint("CustomX509TrustManager")
+  val trustManager =
+    object : X509TrustManager {
+      override fun checkClientTrusted(chain: Array<X509Certificate>, authType: String) {
+        defaultTrust.checkClientTrusted(chain, authType)
+      }
+
+      override fun checkServerTrusted(chain: Array<X509Certificate>, authType: String) {
+        if (chain.isEmpty()) throw CertificateException("empty certificate chain")
+        val fingerprint = sha256Hex(chain[0].encoded)
+        if (expected != null) {
+          if (fingerprint != expected) {
+            throw CertificateException("bridge TLS fingerprint mismatch")
+          }
+          return
+        }
+        if (params.allowTOFU) {
+          onStore?.invoke(fingerprint)
+          return
+        }
+        defaultTrust.checkServerTrusted(chain, authType)
+      }
+
+      override fun getAcceptedIssuers(): Array<X509Certificate> = defaultTrust.acceptedIssuers
+    }
+
+  val context = SSLContext.getInstance("TLS")
+  context.init(null, arrayOf(trustManager), SecureRandom())
+  return context.socketFactory.createSocket()
+}
+
+fun startTlsHandshakeIfNeeded(socket: Socket) {
+  if (socket is SSLSocket) {
+    socket.startHandshake()
+  }
+}
+
+private fun defaultTrustManager(): X509TrustManager {
+  val factory = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm())
+  factory.init(null as java.security.KeyStore?)
+  val trust =
+    factory.trustManagers.firstOrNull { it is X509TrustManager } as? X509TrustManager
+  return trust ?: throw IllegalStateException("No default X509TrustManager found")
+}
+
+private fun sha256Hex(data: ByteArray): String {
+  val digest = MessageDigest.getInstance("SHA-256").digest(data)
+  val out = StringBuilder(digest.size * 2)
+  for (byte in digest) {
+    out.append(String.format("%02x", byte))
+  }
+  return out.toString()
+}
+
+private fun normalizeFingerprint(raw: String): String {
+  return raw.lowercase().filter { it in '0'..'9' || it in 'a'..'f' }
+}

apps/android/app/src/main/java/com/clawdbot/android/chat/ChatController.kt

@@ -0,0 +1,521 @@
+package com.clawdbot.android.chat
+
+import com.clawdbot.android.bridge.BridgeSession
+import java.util.UUID
+import java.util.concurrent.ConcurrentHashMap
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
+import kotlinx.coroutines.launch
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonArray
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonNull
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.buildJsonObject
+
+class ChatController(
+  private val scope: CoroutineScope,
+  private val session: BridgeSession,
+  private val json: Json,
+) {
+  private val _sessionKey = MutableStateFlow("main")
+  val sessionKey: StateFlow<String> = _sessionKey.asStateFlow()
+
+  private val _sessionId = MutableStateFlow<String?>(null)
+  val sessionId: StateFlow<String?> = _sessionId.asStateFlow()
+
+  private val _messages = MutableStateFlow<List<ChatMessage>>(emptyList())
+  val messages: StateFlow<List<ChatMessage>> = _messages.asStateFlow()
+
+  private val _errorText = MutableStateFlow<String?>(null)
+  val errorText: StateFlow<String?> = _errorText.asStateFlow()
+
+  private val _healthOk = MutableStateFlow(false)
+  val healthOk: StateFlow<Boolean> = _healthOk.asStateFlow()
+
+  private val _thinkingLevel = MutableStateFlow("off")
+  val thinkingLevel: StateFlow<String> = _thinkingLevel.asStateFlow()
+
+  private val _pendingRunCount = MutableStateFlow(0)
+  val pendingRunCount: StateFlow<Int> = _pendingRunCount.asStateFlow()
+
+  private val _streamingAssistantText = MutableStateFlow<String?>(null)
+  val streamingAssistantText: StateFlow<String?> = _streamingAssistantText.asStateFlow()
+
+  private val pendingToolCallsById = ConcurrentHashMap<String, ChatPendingToolCall>()
+  private val _pendingToolCalls = MutableStateFlow<List<ChatPendingToolCall>>(emptyList())
+  val pendingToolCalls: StateFlow<List<ChatPendingToolCall>> = _pendingToolCalls.asStateFlow()
+
+  private val _sessions = MutableStateFlow<List<ChatSessionEntry>>(emptyList())
+  val sessions: StateFlow<List<ChatSessionEntry>> = _sessions.asStateFlow()
+
+  private val pendingRuns = mutableSetOf<String>()
+  private val pendingRunTimeoutJobs = ConcurrentHashMap<String, Job>()
+  private val pendingRunTimeoutMs = 120_000L
+
+  private var lastHealthPollAtMs: Long? = null
+
+  fun onDisconnected(message: String) {
+    _healthOk.value = false
+    // Not an error; keep connection status in the UI pill.
+    _errorText.value = null
+    clearPendingRuns()
+    pendingToolCallsById.clear()
+    publishPendingToolCalls()
+    _streamingAssistantText.value = null
+    _sessionId.value = null
+  }
+
+  fun load(sessionKey: String) {
+    val key = sessionKey.trim().ifEmpty { "main" }
+    _sessionKey.value = key
+    scope.launch { bootstrap(forceHealth = true) }
+  }
+
+  fun applyMainSessionKey(mainSessionKey: String) {
+    val trimmed = mainSessionKey.trim()
+    if (trimmed.isEmpty()) return
+    if (_sessionKey.value == trimmed) return
+    if (_sessionKey.value != "main") return
+    _sessionKey.value = trimmed
+    scope.launch { bootstrap(forceHealth = true) }
+  }
+
+  fun refresh() {
+    scope.launch { bootstrap(forceHealth = true) }
+  }
+
+  fun refreshSessions(limit: Int? = null) {
+    scope.launch { fetchSessions(limit = limit) }
+  }
+
+  fun setThinkingLevel(thinkingLevel: String) {
+    val normalized = normalizeThinking(thinkingLevel)
+    if (normalized == _thinkingLevel.value) return
+    _thinkingLevel.value = normalized
+  }
+
+  fun switchSession(sessionKey: String) {
+    val key = sessionKey.trim()
+    if (key.isEmpty()) return
+    if (key == _sessionKey.value) return
+    _sessionKey.value = key
+    scope.launch { bootstrap(forceHealth = true) }
+  }
+
+  fun sendMessage(
+    message: String,
+    thinkingLevel: String,
+    attachments: List<OutgoingAttachment>,
+  ) {
+    val trimmed = message.trim()
+    if (trimmed.isEmpty() && attachments.isEmpty()) return
+    if (!_healthOk.value) {
+      _errorText.value = "Gateway health not OK; cannot send"
+      return
+    }
+
+    val runId = UUID.randomUUID().toString()
+    val text = if (trimmed.isEmpty() && attachments.isNotEmpty()) "See attached." else trimmed
+    val sessionKey = _sessionKey.value
+    val thinking = normalizeThinking(thinkingLevel)
+
+    // Optimistic user message.
+    val userContent =
+      buildList {
+        add(ChatMessageContent(type = "text", text = text))
+        for (att in attachments) {
+          add(
+            ChatMessageContent(
+              type = att.type,
+              mimeType = att.mimeType,
+              fileName = att.fileName,
+              base64 = att.base64,
+            ),
+          )
+        }
+      }
+    _messages.value =
+      _messages.value +
+        ChatMessage(
+          id = UUID.randomUUID().toString(),
+          role = "user",
+          content = userContent,
+          timestampMs = System.currentTimeMillis(),
+        )
+
+    armPendingRunTimeout(runId)
+    synchronized(pendingRuns) {
+      pendingRuns.add(runId)
+      _pendingRunCount.value = pendingRuns.size
+    }
+
+    _errorText.value = null
+    _streamingAssistantText.value = null
+    pendingToolCallsById.clear()
+    publishPendingToolCalls()
+
+    scope.launch {
+      try {
+        val params =
+          buildJsonObject {
+            put("sessionKey", JsonPrimitive(sessionKey))
+            put("message", JsonPrimitive(text))
+            put("thinking", JsonPrimitive(thinking))
+            put("timeoutMs", JsonPrimitive(30_000))
+            put("idempotencyKey", JsonPrimitive(runId))
+            if (attachments.isNotEmpty()) {
+              put(
+                "attachments",
+                JsonArray(
+                  attachments.map { att ->
+                    buildJsonObject {
+                      put("type", JsonPrimitive(att.type))
+                      put("mimeType", JsonPrimitive(att.mimeType))
+                      put("fileName", JsonPrimitive(att.fileName))
+                      put("content", JsonPrimitive(att.base64))
+                    }
+                  },
+                ),
+              )
+            }
+          }
+        val res = session.request("chat.send", params.toString())
+        val actualRunId = parseRunId(res) ?: runId
+        if (actualRunId != runId) {
+          clearPendingRun(runId)
+          armPendingRunTimeout(actualRunId)
+          synchronized(pendingRuns) {
+            pendingRuns.add(actualRunId)
+            _pendingRunCount.value = pendingRuns.size
+          }
+        }
+      } catch (err: Throwable) {
+        clearPendingRun(runId)
+        _errorText.value = err.message
+      }
+    }
+  }
+
+  fun abort() {
+    val runIds =
+      synchronized(pendingRuns) {
+        pendingRuns.toList()
+      }
+    if (runIds.isEmpty()) return
+    scope.launch {
+      for (runId in runIds) {
+        try {
+          val params =
+            buildJsonObject {
+              put("sessionKey", JsonPrimitive(_sessionKey.value))
+              put("runId", JsonPrimitive(runId))
+            }
+          session.request("chat.abort", params.toString())
+        } catch (_: Throwable) {
+          // best-effort
+        }
+      }
+    }
+  }
+
+  fun handleBridgeEvent(event: String, payloadJson: String?) {
+    when (event) {
+      "tick" -> {
+        scope.launch { pollHealthIfNeeded(force = false) }
+      }
+      "health" -> {
+        // If we receive a health snapshot, the gateway is reachable.
+        _healthOk.value = true
+      }
+      "seqGap" -> {
+        _errorText.value = "Event stream interrupted; try refreshing."
+        clearPendingRuns()
+      }
+      "chat" -> {
+        if (payloadJson.isNullOrBlank()) return
+        handleChatEvent(payloadJson)
+      }
+      "agent" -> {
+        if (payloadJson.isNullOrBlank()) return
+        handleAgentEvent(payloadJson)
+      }
+    }
+  }
+
+  private suspend fun bootstrap(forceHealth: Boolean) {
+    _errorText.value = null
+    _healthOk.value = false
+    clearPendingRuns()
+    pendingToolCallsById.clear()
+    publishPendingToolCalls()
+    _streamingAssistantText.value = null
+    _sessionId.value = null
+
+    val key = _sessionKey.value
+    try {
+      try {
+        session.sendEvent("chat.subscribe", """{"sessionKey":"$key"}""")
+      } catch (_: Throwable) {
+        // best-effort
+      }
+
+      val historyJson = session.request("chat.history", """{"sessionKey":"$key"}""")
+      val history = parseHistory(historyJson, sessionKey = key)
+      _messages.value = history.messages
+      _sessionId.value = history.sessionId
+      history.thinkingLevel?.trim()?.takeIf { it.isNotEmpty() }?.let { _thinkingLevel.value = it }
+
+      pollHealthIfNeeded(force = forceHealth)
+      fetchSessions(limit = 50)
+    } catch (err: Throwable) {
+      _errorText.value = err.message
+    }
+  }
+
+  private suspend fun fetchSessions(limit: Int?) {
+    try {
+      val params =
+        buildJsonObject {
+          put("includeGlobal", JsonPrimitive(true))
+          put("includeUnknown", JsonPrimitive(false))
+          if (limit != null && limit > 0) put("limit", JsonPrimitive(limit))
+        }
+      val res = session.request("sessions.list", params.toString())
+      _sessions.value = parseSessions(res)
+    } catch (_: Throwable) {
+      // best-effort
+    }
+  }
+
+  private suspend fun pollHealthIfNeeded(force: Boolean) {
+    val now = System.currentTimeMillis()
+    val last = lastHealthPollAtMs
+    if (!force && last != null && now - last < 10_000) return
+    lastHealthPollAtMs = now
+    try {
+      session.request("health", null)
+      _healthOk.value = true
+    } catch (_: Throwable) {
+      _healthOk.value = false
+    }
+  }
+
+  private fun handleChatEvent(payloadJson: String) {
+    val payload = json.parseToJsonElement(payloadJson).asObjectOrNull() ?: return
+    val sessionKey = payload["sessionKey"].asStringOrNull()?.trim()
+    if (!sessionKey.isNullOrEmpty() && sessionKey != _sessionKey.value) return
+
+    val runId = payload["runId"].asStringOrNull()
+    if (runId != null) {
+      val isPending =
+        synchronized(pendingRuns) {
+          pendingRuns.contains(runId)
+        }
+      if (!isPending) return
+    }
+
+    val state = payload["state"].asStringOrNull()
+    when (state) {
+      "final", "aborted", "error" -> {
+        if (state == "error") {
+          _errorText.value = payload["errorMessage"].asStringOrNull() ?: "Chat failed"
+        }
+        if (runId != null) clearPendingRun(runId) else clearPendingRuns()
+        pendingToolCallsById.clear()
+        publishPendingToolCalls()
+        _streamingAssistantText.value = null
+        scope.launch {
+          try {
+            val historyJson =
+              session.request("chat.history", """{"sessionKey":"${_sessionKey.value}"}""")
+            val history = parseHistory(historyJson, sessionKey = _sessionKey.value)
+            _messages.value = history.messages
+            _sessionId.value = history.sessionId
+            history.thinkingLevel?.trim()?.takeIf { it.isNotEmpty() }?.let { _thinkingLevel.value = it }
+          } catch (_: Throwable) {
+            // best-effort
+          }
+        }
+      }
+    }
+  }
+
+  private fun handleAgentEvent(payloadJson: String) {
+    val payload = json.parseToJsonElement(payloadJson).asObjectOrNull() ?: return
+    val runId = payload["runId"].asStringOrNull()
+    val sessionId = _sessionId.value
+    if (sessionId != null && runId != sessionId) return
+
+    val stream = payload["stream"].asStringOrNull()
+    val data = payload["data"].asObjectOrNull()
+
+    when (stream) {
+      "assistant" -> {
+        val text = data?.get("text")?.asStringOrNull()
+        if (!text.isNullOrEmpty()) {
+          _streamingAssistantText.value = text
+        }
+      }
+      "tool" -> {
+        val phase = data?.get("phase")?.asStringOrNull()
+        val name = data?.get("name")?.asStringOrNull()
+        val toolCallId = data?.get("toolCallId")?.asStringOrNull()
+        if (phase.isNullOrEmpty() || name.isNullOrEmpty() || toolCallId.isNullOrEmpty()) return
+
+        val ts = payload["ts"].asLongOrNull() ?: System.currentTimeMillis()
+        if (phase == "start") {
+          val args = data?.get("args").asObjectOrNull()
+          pendingToolCallsById[toolCallId] =
+            ChatPendingToolCall(
+              toolCallId = toolCallId,
+              name = name,
+              args = args,
+              startedAtMs = ts,
+              isError = null,
+            )
+          publishPendingToolCalls()
+        } else if (phase == "result") {
+          pendingToolCallsById.remove(toolCallId)
+          publishPendingToolCalls()
+        }
+      }
+      "error" -> {
+        _errorText.value = "Event stream interrupted; try refreshing."
+        clearPendingRuns()
+        pendingToolCallsById.clear()
+        publishPendingToolCalls()
+        _streamingAssistantText.value = null
+      }
+    }
+  }
+
+  private fun publishPendingToolCalls() {
+    _pendingToolCalls.value =
+      pendingToolCallsById.values.sortedBy { it.startedAtMs }
+  }
+
+  private fun armPendingRunTimeout(runId: String) {
+    pendingRunTimeoutJobs[runId]?.cancel()
+    pendingRunTimeoutJobs[runId] =
+      scope.launch {
+        delay(pendingRunTimeoutMs)
+        val stillPending =
+          synchronized(pendingRuns) {
+            pendingRuns.contains(runId)
+          }
+        if (!stillPending) return@launch
+        clearPendingRun(runId)
+        _errorText.value = "Timed out waiting for a reply; try again or refresh."
+      }
+  }
+
+  private fun clearPendingRun(runId: String) {
+    pendingRunTimeoutJobs.remove(runId)?.cancel()
+    synchronized(pendingRuns) {
+      pendingRuns.remove(runId)
+      _pendingRunCount.value = pendingRuns.size
+    }
+  }
+
+  private fun clearPendingRuns() {
+    for ((_, job) in pendingRunTimeoutJobs) {
+      job.cancel()
+    }
+    pendingRunTimeoutJobs.clear()
+    synchronized(pendingRuns) {
+      pendingRuns.clear()
+      _pendingRunCount.value = 0
+    }
+  }
+
+  private fun parseHistory(historyJson: String, sessionKey: String): ChatHistory {
+    val root = json.parseToJsonElement(historyJson).asObjectOrNull() ?: return ChatHistory(sessionKey, null, null, emptyList())
+    val sid = root["sessionId"].asStringOrNull()
+    val thinkingLevel = root["thinkingLevel"].asStringOrNull()
+    val array = root["messages"].asArrayOrNull() ?: JsonArray(emptyList())
+
+    val messages =
+      array.mapNotNull { item ->
+        val obj = item.asObjectOrNull() ?: return@mapNotNull null
+        val role = obj["role"].asStringOrNull() ?: return@mapNotNull null
+        val content = obj["content"].asArrayOrNull()?.mapNotNull(::parseMessageContent) ?: emptyList()
+        val ts = obj["timestamp"].asLongOrNull()
+        ChatMessage(
+          id = UUID.randomUUID().toString(),
+          role = role,
+          content = content,
+          timestampMs = ts,
+        )
+      }
+
+    return ChatHistory(sessionKey = sessionKey, sessionId = sid, thinkingLevel = thinkingLevel, messages = messages)
+  }
+
+  private fun parseMessageContent(el: JsonElement): ChatMessageContent? {
+    val obj = el.asObjectOrNull() ?: return null
+    val type = obj["type"].asStringOrNull() ?: "text"
+    return if (type == "text") {
+      ChatMessageContent(type = "text", text = obj["text"].asStringOrNull())
+    } else {
+      ChatMessageContent(
+        type = type,
+        mimeType = obj["mimeType"].asStringOrNull(),
+        fileName = obj["fileName"].asStringOrNull(),
+        base64 = obj["content"].asStringOrNull(),
+      )
+    }
+  }
+
+  private fun parseSessions(jsonString: String): List<ChatSessionEntry> {
+    val root = json.parseToJsonElement(jsonString).asObjectOrNull() ?: return emptyList()
+    val sessions = root["sessions"].asArrayOrNull() ?: return emptyList()
+    return sessions.mapNotNull { item ->
+      val obj = item.asObjectOrNull() ?: return@mapNotNull null
+      val key = obj["key"].asStringOrNull()?.trim().orEmpty()
+      if (key.isEmpty()) return@mapNotNull null
+      val updatedAt = obj["updatedAt"].asLongOrNull()
+      val displayName = obj["displayName"].asStringOrNull()?.trim()
+      ChatSessionEntry(key = key, updatedAtMs = updatedAt, displayName = displayName)
+    }
+  }
+
+  private fun parseRunId(resJson: String): String? {
+    return try {
+      json.parseToJsonElement(resJson).asObjectOrNull()?.get("runId").asStringOrNull()
+    } catch (_: Throwable) {
+      null
+    }
+  }
+
+  private fun normalizeThinking(raw: String): String {
+    return when (raw.trim().lowercase()) {
+      "low" -> "low"
+      "medium" -> "medium"
+      "high" -> "high"
+      else -> "off"
+    }
+  }
+}
+
+private fun JsonElement?.asObjectOrNull(): JsonObject? = this as? JsonObject
+
+private fun JsonElement?.asArrayOrNull(): JsonArray? = this as? JsonArray
+
+private fun JsonElement?.asStringOrNull(): String? =
+  when (this) {
+    is JsonNull -> null
+    is JsonPrimitive -> content
+    else -> null
+  }
+
+private fun JsonElement?.asLongOrNull(): Long? =
+  when (this) {
+    is JsonPrimitive -> content.toLongOrNull()
+    else -> null
+  }

apps/android/app/src/main/java/com/clawdbot/android/chat/ChatModels.kt

@@ -0,0 +1,44 @@
+package com.clawdbot.android.chat
+
+data class ChatMessage(
+  val id: String,
+  val role: String,
+  val content: List<ChatMessageContent>,
+  val timestampMs: Long?,
+)
+
+data class ChatMessageContent(
+  val type: String = "text",
+  val text: String? = null,
+  val mimeType: String? = null,
+  val fileName: String? = null,
+  val base64: String? = null,
+)
+
+data class ChatPendingToolCall(
+  val toolCallId: String,
+  val name: String,
+  val args: kotlinx.serialization.json.JsonObject? = null,
+  val startedAtMs: Long,
+  val isError: Boolean? = null,
+)
+
+data class ChatSessionEntry(
+  val key: String,
+  val updatedAtMs: Long?,
+  val displayName: String? = null,
+)
+
+data class ChatHistory(
+  val sessionKey: String,
+  val sessionId: String?,
+  val thinkingLevel: String?,
+  val messages: List<ChatMessage>,
+)
+
+data class OutgoingAttachment(
+  val type: String,
+  val mimeType: String,
+  val fileName: String,
+  val base64: String,
+)

apps/android/app/src/main/java/com/clawdbot/android/node/CameraCaptureManager.kt

@@ -0,0 +1,316 @@
+package com.clawdbot.android.node
+
+import android.Manifest
+import android.content.Context
+import android.annotation.SuppressLint
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.graphics.Matrix
+import android.util.Base64
+import android.content.pm.PackageManager
+import androidx.exifinterface.media.ExifInterface
+import androidx.lifecycle.LifecycleOwner
+import androidx.camera.core.CameraSelector
+import androidx.camera.core.ImageCapture
+import androidx.camera.core.ImageCaptureException
+import androidx.camera.lifecycle.ProcessCameraProvider
+import androidx.camera.video.FileOutputOptions
+import androidx.camera.video.Recorder
+import androidx.camera.video.Recording
+import androidx.camera.video.VideoCapture
+import androidx.camera.video.VideoRecordEvent
+import androidx.core.content.ContextCompat
+import androidx.core.content.ContextCompat.checkSelfPermission
+import androidx.core.graphics.scale
+import com.clawdbot.android.PermissionRequester
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.suspendCancellableCoroutine
+import kotlinx.coroutines.withTimeout
+import kotlinx.coroutines.withContext
+import java.io.ByteArrayOutputStream
+import java.io.File
+import java.util.concurrent.Executor
+import kotlin.math.roundToInt
+import kotlin.coroutines.resume
+import kotlin.coroutines.resumeWithException
+
+class CameraCaptureManager(private val context: Context) {
+  data class Payload(val payloadJson: String)
+
+  @Volatile private var lifecycleOwner: LifecycleOwner? = null
+  @Volatile private var permissionRequester: PermissionRequester? = null
+
+  fun attachLifecycleOwner(owner: LifecycleOwner) {
+    lifecycleOwner = owner
+  }
+
+  fun attachPermissionRequester(requester: PermissionRequester) {
+    permissionRequester = requester
+  }
+
+  private suspend fun ensureCameraPermission() {
+    val granted = checkSelfPermission(context, Manifest.permission.CAMERA) == PackageManager.PERMISSION_GRANTED
+    if (granted) return
+
+    val requester = permissionRequester
+      ?: throw IllegalStateException("CAMERA_PERMISSION_REQUIRED: grant Camera permission")
+    val results = requester.requestIfMissing(listOf(Manifest.permission.CAMERA))
+    if (results[Manifest.permission.CAMERA] != true) {
+      throw IllegalStateException("CAMERA_PERMISSION_REQUIRED: grant Camera permission")
+    }
+  }
+
+  private suspend fun ensureMicPermission() {
+    val granted = checkSelfPermission(context, Manifest.permission.RECORD_AUDIO) == PackageManager.PERMISSION_GRANTED
+    if (granted) return
+
+    val requester = permissionRequester
+      ?: throw IllegalStateException("MIC_PERMISSION_REQUIRED: grant Microphone permission")
+    val results = requester.requestIfMissing(listOf(Manifest.permission.RECORD_AUDIO))
+    if (results[Manifest.permission.RECORD_AUDIO] != true) {
+      throw IllegalStateException("MIC_PERMISSION_REQUIRED: grant Microphone permission")
+    }
+  }
+
+  suspend fun snap(paramsJson: String?): Payload =
+    withContext(Dispatchers.Main) {
+      ensureCameraPermission()
+      val owner = lifecycleOwner ?: throw IllegalStateException("UNAVAILABLE: camera not ready")
+      val facing = parseFacing(paramsJson) ?: "front"
+      val quality = (parseQuality(paramsJson) ?: 0.9).coerceIn(0.1, 1.0)
+      val maxWidth = parseMaxWidth(paramsJson)
+
+      val provider = context.cameraProvider()
+      val capture = ImageCapture.Builder().build()
+      val selector =
+        if (facing == "front") CameraSelector.DEFAULT_FRONT_CAMERA else CameraSelector.DEFAULT_BACK_CAMERA
+
+      provider.unbindAll()
+      provider.bindToLifecycle(owner, selector, capture)
+
+      val (bytes, orientation) = capture.takeJpegWithExif(context.mainExecutor())
+      val decoded = BitmapFactory.decodeByteArray(bytes, 0, bytes.size)
+        ?: throw IllegalStateException("UNAVAILABLE: failed to decode captured image")
+      val rotated = rotateBitmapByExif(decoded, orientation)
+      val scaled =
+        if (maxWidth != null && maxWidth > 0 && rotated.width > maxWidth) {
+          val h =
+            (rotated.height.toDouble() * (maxWidth.toDouble() / rotated.width.toDouble()))
+              .toInt()
+              .coerceAtLeast(1)
+          rotated.scale(maxWidth, h)
+        } else {
+          rotated
+        }
+
+      val maxPayloadBytes = 5 * 1024 * 1024
+      // Base64 inflates payloads by ~4/3; cap encoded bytes so the payload stays under 5MB (API limit).
+      val maxEncodedBytes = (maxPayloadBytes / 4) * 3
+      val result =
+        JpegSizeLimiter.compressToLimit(
+          initialWidth = scaled.width,
+          initialHeight = scaled.height,
+          startQuality = (quality * 100.0).roundToInt().coerceIn(10, 100),
+          maxBytes = maxEncodedBytes,
+          encode = { width, height, q ->
+            val bitmap =
+              if (width == scaled.width && height == scaled.height) {
+                scaled
+              } else {
+                scaled.scale(width, height)
+              }
+            val out = ByteArrayOutputStream()
+            if (!bitmap.compress(Bitmap.CompressFormat.JPEG, q, out)) {
+              if (bitmap !== scaled) bitmap.recycle()
+              throw IllegalStateException("UNAVAILABLE: failed to encode JPEG")
+            }
+            if (bitmap !== scaled) {
+              bitmap.recycle()
+            }
+            out.toByteArray()
+          },
+        )
+      val base64 = Base64.encodeToString(result.bytes, Base64.NO_WRAP)
+      Payload(
+        """{"format":"jpg","base64":"$base64","width":${result.width},"height":${result.height}}""",
+      )
+    }
+
+  @SuppressLint("MissingPermission")
+  suspend fun clip(paramsJson: String?): Payload =
+    withContext(Dispatchers.Main) {
+      ensureCameraPermission()
+      val owner = lifecycleOwner ?: throw IllegalStateException("UNAVAILABLE: camera not ready")
+      val facing = parseFacing(paramsJson) ?: "front"
+      val durationMs = (parseDurationMs(paramsJson) ?: 3_000).coerceIn(200, 60_000)
+      val includeAudio = parseIncludeAudio(paramsJson) ?: true
+      if (includeAudio) ensureMicPermission()
+
+      val provider = context.cameraProvider()
+      val recorder = Recorder.Builder().build()
+      val videoCapture = VideoCapture.withOutput(recorder)
+      val selector =
+        if (facing == "front") CameraSelector.DEFAULT_FRONT_CAMERA else CameraSelector.DEFAULT_BACK_CAMERA
+
+      provider.unbindAll()
+      provider.bindToLifecycle(owner, selector, videoCapture)
+
+      val file = File.createTempFile("clawdbot-clip-", ".mp4")
+      val outputOptions = FileOutputOptions.Builder(file).build()
+
+      val finalized = kotlinx.coroutines.CompletableDeferred<VideoRecordEvent.Finalize>()
+      val recording: Recording =
+        videoCapture.output
+          .prepareRecording(context, outputOptions)
+          .apply {
+            if (includeAudio) withAudioEnabled()
+          }
+          .start(context.mainExecutor()) { event ->
+            if (event is VideoRecordEvent.Finalize) {
+              finalized.complete(event)
+            }
+          }
+
+      try {
+        kotlinx.coroutines.delay(durationMs.toLong())
+      } finally {
+        recording.stop()
+      }
+
+      val finalizeEvent =
+        try {
+          withTimeout(10_000) { finalized.await() }
+        } catch (err: Throwable) {
+          file.delete()
+          throw IllegalStateException("UNAVAILABLE: camera clip finalize timed out")
+        }
+      if (finalizeEvent.hasError()) {
+        file.delete()
+        throw IllegalStateException("UNAVAILABLE: camera clip failed")
+      }
+
+      val bytes = file.readBytes()
+      file.delete()
+      val base64 = Base64.encodeToString(bytes, Base64.NO_WRAP)
+      Payload(
+        """{"format":"mp4","base64":"$base64","durationMs":$durationMs,"hasAudio":${includeAudio}}""",
+      )
+    }
+
+  private fun rotateBitmapByExif(bitmap: Bitmap, orientation: Int): Bitmap {
+    val matrix = Matrix()
+    when (orientation) {
+      ExifInterface.ORIENTATION_ROTATE_90 -> matrix.postRotate(90f)
+      ExifInterface.ORIENTATION_ROTATE_180 -> matrix.postRotate(180f)
+      ExifInterface.ORIENTATION_ROTATE_270 -> matrix.postRotate(270f)
+      ExifInterface.ORIENTATION_FLIP_HORIZONTAL -> matrix.postScale(-1f, 1f)
+      ExifInterface.ORIENTATION_FLIP_VERTICAL -> matrix.postScale(1f, -1f)
+      ExifInterface.ORIENTATION_TRANSPOSE -> {
+        matrix.postRotate(90f)
+        matrix.postScale(-1f, 1f)
+      }
+      ExifInterface.ORIENTATION_TRANSVERSE -> {
+        matrix.postRotate(-90f)
+        matrix.postScale(-1f, 1f)
+      }
+      else -> return bitmap
+    }
+    val rotated = Bitmap.createBitmap(bitmap, 0, 0, bitmap.width, bitmap.height, matrix, true)
+    if (rotated !== bitmap) {
+      bitmap.recycle()
+    }
+    return rotated
+  }
+
+  private fun parseFacing(paramsJson: String?): String? =
+    when {
+      paramsJson?.contains("\"front\"") == true -> "front"
+      paramsJson?.contains("\"back\"") == true -> "back"
+      else -> null
+    }
+
+  private fun parseQuality(paramsJson: String?): Double? =
+    parseNumber(paramsJson, key = "quality")?.toDoubleOrNull()
+
+  private fun parseMaxWidth(paramsJson: String?): Int? =
+    parseNumber(paramsJson, key = "maxWidth")?.toIntOrNull()
+
+  private fun parseDurationMs(paramsJson: String?): Int? =
+    parseNumber(paramsJson, key = "durationMs")?.toIntOrNull()
+
+  private fun parseIncludeAudio(paramsJson: String?): Boolean? {
+    val raw = paramsJson ?: return null
+    val key = "\"includeAudio\""
+    val idx = raw.indexOf(key)
+    if (idx < 0) return null
+    val colon = raw.indexOf(':', idx + key.length)
+    if (colon < 0) return null
+    val tail = raw.substring(colon + 1).trimStart()
+    return when {
+      tail.startsWith("true") -> true
+      tail.startsWith("false") -> false
+      else -> null
+    }
+  }
+
+  private fun parseNumber(paramsJson: String?, key: String): String? {
+    val raw = paramsJson ?: return null
+    val needle = "\"$key\""
+    val idx = raw.indexOf(needle)
+    if (idx < 0) return null
+    val colon = raw.indexOf(':', idx + needle.length)
+    if (colon < 0) return null
+    val tail = raw.substring(colon + 1).trimStart()
+    return tail.takeWhile { it.isDigit() || it == '.' }
+  }
+
+  private fun Context.mainExecutor(): Executor = ContextCompat.getMainExecutor(this)
+}
+
+private suspend fun Context.cameraProvider(): ProcessCameraProvider =
+  suspendCancellableCoroutine { cont ->
+    val future = ProcessCameraProvider.getInstance(this)
+    future.addListener(
+      {
+        try {
+          cont.resume(future.get())
+        } catch (e: Exception) {
+          cont.resumeWithException(e)
+        }
+      },
+      ContextCompat.getMainExecutor(this),
+    )
+  }
+
+/** Returns (jpegBytes, exifOrientation) so caller can rotate the decoded bitmap. */
+private suspend fun ImageCapture.takeJpegWithExif(executor: Executor): Pair<ByteArray, Int> =
+  suspendCancellableCoroutine { cont ->
+    val file = File.createTempFile("clawdbot-snap-", ".jpg")
+    val options = ImageCapture.OutputFileOptions.Builder(file).build()
+    takePicture(
+      options,
+      executor,
+      object : ImageCapture.OnImageSavedCallback {
+        override fun onError(exception: ImageCaptureException) {
+          file.delete()
+          cont.resumeWithException(exception)
+        }
+
+        override fun onImageSaved(outputFileResults: ImageCapture.OutputFileResults) {
+          try {
+            val exif = ExifInterface(file.absolutePath)
+            val orientation = exif.getAttributeInt(
+              ExifInterface.TAG_ORIENTATION,
+              ExifInterface.ORIENTATION_NORMAL,
+            )
+            val bytes = file.readBytes()
+            cont.resume(Pair(bytes, orientation))
+          } catch (e: Exception) {
+            cont.resumeWithException(e)
+          } finally {
+            file.delete()
+          }
+        }
+      },
+    )
+  }

apps/android/app/src/main/java/com/clawdbot/android/node/CanvasController.kt

@@ -0,0 +1,264 @@
+package com.clawdbot.android.node
+
+import android.graphics.Bitmap
+import android.graphics.Canvas
+import android.os.Looper
+import android.util.Log
+import android.webkit.WebView
+import androidx.core.graphics.createBitmap
+import androidx.core.graphics.scale
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.suspendCancellableCoroutine
+import kotlinx.coroutines.withContext
+import java.io.ByteArrayOutputStream
+import android.util.Base64
+import org.json.JSONObject
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import com.clawdbot.android.BuildConfig
+import kotlin.coroutines.resume
+
+class CanvasController {
+  enum class SnapshotFormat(val rawValue: String) {
+    Png("png"),
+    Jpeg("jpeg"),
+  }
+
+  @Volatile private var webView: WebView? = null
+  @Volatile private var url: String? = null
+  @Volatile private var debugStatusEnabled: Boolean = false
+  @Volatile private var debugStatusTitle: String? = null
+  @Volatile private var debugStatusSubtitle: String? = null
+
+  private val scaffoldAssetUrl = "file:///android_asset/CanvasScaffold/scaffold.html"
+
+  private fun clampJpegQuality(quality: Double?): Int {
+    val q = (quality ?: 0.82).coerceIn(0.1, 1.0)
+    return (q * 100.0).toInt().coerceIn(1, 100)
+  }
+
+  fun attach(webView: WebView) {
+    this.webView = webView
+    reload()
+    applyDebugStatus()
+  }
+
+  fun navigate(url: String) {
+    val trimmed = url.trim()
+    this.url = if (trimmed.isBlank() || trimmed == "/") null else trimmed
+    reload()
+  }
+
+  fun currentUrl(): String? = url
+
+  fun isDefaultCanvas(): Boolean = url == null
+
+  fun setDebugStatusEnabled(enabled: Boolean) {
+    debugStatusEnabled = enabled
+    applyDebugStatus()
+  }
+
+  fun setDebugStatus(title: String?, subtitle: String?) {
+    debugStatusTitle = title
+    debugStatusSubtitle = subtitle
+    applyDebugStatus()
+  }
+
+  fun onPageFinished() {
+    applyDebugStatus()
+  }
+
+  private inline fun withWebViewOnMain(crossinline block: (WebView) -> Unit) {
+    val wv = webView ?: return
+    if (Looper.myLooper() == Looper.getMainLooper()) {
+      block(wv)
+    } else {
+      wv.post { block(wv) }
+    }
+  }
+
+  private fun reload() {
+    val currentUrl = url
+    withWebViewOnMain { wv ->
+      if (currentUrl == null) {
+        if (BuildConfig.DEBUG) {
+          Log.d("ClawdbotCanvas", "load scaffold: $scaffoldAssetUrl")
+        }
+        wv.loadUrl(scaffoldAssetUrl)
+      } else {
+        if (BuildConfig.DEBUG) {
+          Log.d("ClawdbotCanvas", "load url: $currentUrl")
+        }
+        wv.loadUrl(currentUrl)
+      }
+    }
+  }
+
+  private fun applyDebugStatus() {
+    val enabled = debugStatusEnabled
+    val title = debugStatusTitle
+    val subtitle = debugStatusSubtitle
+    withWebViewOnMain { wv ->
+      val titleJs = title?.let { JSONObject.quote(it) } ?: "null"
+      val subtitleJs = subtitle?.let { JSONObject.quote(it) } ?: "null"
+      val js = """
+        (() => {
+          try {
+            const api = globalThis.__clawdbot;
+            if (!api) return;
+            if (typeof api.setDebugStatusEnabled === 'function') {
+              api.setDebugStatusEnabled(${if (enabled) "true" else "false"});
+            }
+            if (!${if (enabled) "true" else "false"}) return;
+            if (typeof api.setStatus === 'function') {
+              api.setStatus($titleJs, $subtitleJs);
+            }
+          } catch (_) {}
+        })();
+      """.trimIndent()
+      wv.evaluateJavascript(js, null)
+    }
+  }
+
+  suspend fun eval(javaScript: String): String =
+    withContext(Dispatchers.Main) {
+      val wv = webView ?: throw IllegalStateException("no webview")
+      suspendCancellableCoroutine { cont ->
+        wv.evaluateJavascript(javaScript) { result ->
+          cont.resume(result ?: "")
+        }
+      }
+    }
+
+  suspend fun snapshotPngBase64(maxWidth: Int?): String =
+    withContext(Dispatchers.Main) {
+      val wv = webView ?: throw IllegalStateException("no webview")
+      val bmp = wv.captureBitmap()
+      val scaled =
+        if (maxWidth != null && maxWidth > 0 && bmp.width > maxWidth) {
+          val h = (bmp.height.toDouble() * (maxWidth.toDouble() / bmp.width.toDouble())).toInt().coerceAtLeast(1)
+          bmp.scale(maxWidth, h)
+        } else {
+          bmp
+        }
+
+      val out = ByteArrayOutputStream()
+      scaled.compress(Bitmap.CompressFormat.PNG, 100, out)
+      Base64.encodeToString(out.toByteArray(), Base64.NO_WRAP)
+    }
+
+  suspend fun snapshotBase64(format: SnapshotFormat, quality: Double?, maxWidth: Int?): String =
+    withContext(Dispatchers.Main) {
+      val wv = webView ?: throw IllegalStateException("no webview")
+      val bmp = wv.captureBitmap()
+      val scaled =
+        if (maxWidth != null && maxWidth > 0 && bmp.width > maxWidth) {
+          val h = (bmp.height.toDouble() * (maxWidth.toDouble() / bmp.width.toDouble())).toInt().coerceAtLeast(1)
+          bmp.scale(maxWidth, h)
+        } else {
+          bmp
+        }
+
+      val out = ByteArrayOutputStream()
+      val (compressFormat, compressQuality) =
+        when (format) {
+          SnapshotFormat.Png -> Bitmap.CompressFormat.PNG to 100
+          SnapshotFormat.Jpeg -> Bitmap.CompressFormat.JPEG to clampJpegQuality(quality)
+        }
+      scaled.compress(compressFormat, compressQuality, out)
+      Base64.encodeToString(out.toByteArray(), Base64.NO_WRAP)
+    }
+
+  private suspend fun WebView.captureBitmap(): Bitmap =
+    suspendCancellableCoroutine { cont ->
+      val width = width.coerceAtLeast(1)
+      val height = height.coerceAtLeast(1)
+      val bitmap = createBitmap(width, height, Bitmap.Config.ARGB_8888)
+
+      // WebView isn't supported by PixelCopy.request(...) directly; draw() is the most reliable
+      // cross-version snapshot for this lightweight "canvas" use-case.
+      draw(Canvas(bitmap))
+      cont.resume(bitmap)
+    }
+
+  companion object {
+    data class SnapshotParams(val format: SnapshotFormat, val quality: Double?, val maxWidth: Int?)
+
+    fun parseNavigateUrl(paramsJson: String?): String {
+      val obj = parseParamsObject(paramsJson) ?: return ""
+      return obj.string("url").trim()
+    }
+
+    fun parseEvalJs(paramsJson: String?): String? {
+      val obj = parseParamsObject(paramsJson) ?: return null
+      val js = obj.string("javaScript").trim()
+      return js.takeIf { it.isNotBlank() }
+    }
+
+    fun parseSnapshotMaxWidth(paramsJson: String?): Int? {
+      val obj = parseParamsObject(paramsJson) ?: return null
+      if (!obj.containsKey("maxWidth")) return null
+      val width = obj.int("maxWidth") ?: 0
+      return width.takeIf { it > 0 }
+    }
+
+    fun parseSnapshotFormat(paramsJson: String?): SnapshotFormat {
+      val obj = parseParamsObject(paramsJson) ?: return SnapshotFormat.Jpeg
+      val raw = obj.string("format").trim().lowercase()
+      return when (raw) {
+        "png" -> SnapshotFormat.Png
+        "jpeg", "jpg" -> SnapshotFormat.Jpeg
+        "" -> SnapshotFormat.Jpeg
+        else -> SnapshotFormat.Jpeg
+      }
+    }
+
+    fun parseSnapshotQuality(paramsJson: String?): Double? {
+      val obj = parseParamsObject(paramsJson) ?: return null
+      if (!obj.containsKey("quality")) return null
+      val q = obj.double("quality") ?: Double.NaN
+      if (!q.isFinite()) return null
+      return q.coerceIn(0.1, 1.0)
+    }
+
+    fun parseSnapshotParams(paramsJson: String?): SnapshotParams {
+      return SnapshotParams(
+        format = parseSnapshotFormat(paramsJson),
+        quality = parseSnapshotQuality(paramsJson),
+        maxWidth = parseSnapshotMaxWidth(paramsJson),
+      )
+    }
+
+    private val json = Json { ignoreUnknownKeys = true }
+
+    private fun parseParamsObject(paramsJson: String?): JsonObject? {
+      val raw = paramsJson?.trim().orEmpty()
+      if (raw.isEmpty()) return null
+      return try {
+        json.parseToJsonElement(raw).asObjectOrNull()
+      } catch (_: Throwable) {
+        null
+      }
+    }
+
+    private fun JsonElement?.asObjectOrNull(): JsonObject? = this as? JsonObject
+
+    private fun JsonObject.string(key: String): String {
+      val prim = this[key] as? JsonPrimitive ?: return ""
+      val raw = prim.content
+      return raw.takeIf { it != "null" }.orEmpty()
+    }
+
+    private fun JsonObject.int(key: String): Int? {
+      val prim = this[key] as? JsonPrimitive ?: return null
+      return prim.content.toIntOrNull()
+    }
+
+    private fun JsonObject.double(key: String): Double? {
+      val prim = this[key] as? JsonPrimitive ?: return null
+      return prim.content.toDoubleOrNull()
+    }
+  }
+}

apps/android/app/src/main/java/com/clawdbot/android/node/JpegSizeLimiter.kt

@@ -0,0 +1,61 @@
+package com.clawdbot.android.node
+
+import kotlin.math.max
+import kotlin.math.min
+import kotlin.math.roundToInt
+
+internal data class JpegSizeLimiterResult(
+  val bytes: ByteArray,
+  val width: Int,
+  val height: Int,
+  val quality: Int,
+)
+
+internal object JpegSizeLimiter {
+  fun compressToLimit(
+    initialWidth: Int,
+    initialHeight: Int,
+    startQuality: Int,
+    maxBytes: Int,
+    minQuality: Int = 20,
+    minSize: Int = 256,
+    scaleStep: Double = 0.85,
+    maxScaleAttempts: Int = 6,
+    maxQualityAttempts: Int = 6,
+    encode: (width: Int, height: Int, quality: Int) -> ByteArray,
+  ): JpegSizeLimiterResult {
+    require(initialWidth > 0 && initialHeight > 0) { "Invalid image size" }
+    require(maxBytes > 0) { "Invalid maxBytes" }
+
+    var width = initialWidth
+    var height = initialHeight
+    val clampedStartQuality = startQuality.coerceIn(minQuality, 100)
+    var best = JpegSizeLimiterResult(bytes = encode(width, height, clampedStartQuality), width = width, height = height, quality = clampedStartQuality)
+    if (best.bytes.size <= maxBytes) return best
+
+    repeat(maxScaleAttempts) {
+      var quality = clampedStartQuality
+      repeat(maxQualityAttempts) {
+        val bytes = encode(width, height, quality)
+        best = JpegSizeLimiterResult(bytes = bytes, width = width, height = height, quality = quality)
+        if (bytes.size <= maxBytes) return best
+        if (quality <= minQuality) return@repeat
+        quality = max(minQuality, (quality * 0.75).roundToInt())
+      }
+
+      val minScale = (minSize.toDouble() / min(width, height).toDouble()).coerceAtMost(1.0)
+      val nextScale = max(scaleStep, minScale)
+      val nextWidth = max(minSize, (width * nextScale).roundToInt())
+      val nextHeight = max(minSize, (height * nextScale).roundToInt())
+      if (nextWidth == width && nextHeight == height) return@repeat
+      width = min(nextWidth, width)
+      height = min(nextHeight, height)
+    }
+
+    if (best.bytes.size > maxBytes) {
+      throw IllegalStateException("CAMERA_TOO_LARGE: ${best.bytes.size} bytes > $maxBytes bytes")
+    }
+
+    return best
+  }
+}

apps/android/app/src/main/java/com/clawdbot/android/node/LocationCaptureManager.kt

@@ -0,0 +1,117 @@
+package com.clawdbot.android.node
+
+import android.Manifest
+import android.content.Context
+import android.content.pm.PackageManager
+import android.location.Location
+import android.location.LocationManager
+import android.os.CancellationSignal
+import androidx.core.content.ContextCompat
+import java.time.Instant
+import java.time.format.DateTimeFormatter
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.withContext
+import kotlinx.coroutines.withTimeout
+import kotlin.coroutines.resume
+import kotlin.coroutines.resumeWithException
+import kotlinx.coroutines.suspendCancellableCoroutine
+
+class LocationCaptureManager(private val context: Context) {
+  data class Payload(val payloadJson: String)
+
+  suspend fun getLocation(
+    desiredProviders: List<String>,
+    maxAgeMs: Long?,
+    timeoutMs: Long,
+    isPrecise: Boolean,
+  ): Payload =
+    withContext(Dispatchers.Main) {
+      val manager = context.getSystemService(Context.LOCATION_SERVICE) as LocationManager
+      if (!manager.isProviderEnabled(LocationManager.GPS_PROVIDER) &&
+        !manager.isProviderEnabled(LocationManager.NETWORK_PROVIDER)
+      ) {
+        throw IllegalStateException("LOCATION_UNAVAILABLE: no location providers enabled")
+      }
+
+      val cached = bestLastKnown(manager, desiredProviders, maxAgeMs)
+      val location =
+        cached ?: requestCurrent(manager, desiredProviders, timeoutMs)
+
+      val timestamp = DateTimeFormatter.ISO_INSTANT.format(Instant.ofEpochMilli(location.time))
+      val source = location.provider
+      val altitudeMeters = if (location.hasAltitude()) location.altitude else null
+      val speedMps = if (location.hasSpeed()) location.speed.toDouble() else null
+      val headingDeg = if (location.hasBearing()) location.bearing.toDouble() else null
+      Payload(
+        buildString {
+          append("{\"lat\":")
+          append(location.latitude)
+          append(",\"lon\":")
+          append(location.longitude)
+          append(",\"accuracyMeters\":")
+          append(location.accuracy.toDouble())
+          if (altitudeMeters != null) append(",\"altitudeMeters\":").append(altitudeMeters)
+          if (speedMps != null) append(",\"speedMps\":").append(speedMps)
+          if (headingDeg != null) append(",\"headingDeg\":").append(headingDeg)
+          append(",\"timestamp\":\"").append(timestamp).append('"')
+          append(",\"isPrecise\":").append(isPrecise)
+          append(",\"source\":\"").append(source).append('"')
+          append('}')
+        },
+      )
+    }
+
+  private fun bestLastKnown(
+    manager: LocationManager,
+    providers: List<String>,
+    maxAgeMs: Long?,
+  ): Location? {
+    val fineOk =
+      ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_FINE_LOCATION) ==
+        PackageManager.PERMISSION_GRANTED
+    val coarseOk =
+      ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_COARSE_LOCATION) ==
+        PackageManager.PERMISSION_GRANTED
+    if (!fineOk && !coarseOk) {
+      throw IllegalStateException("LOCATION_PERMISSION_REQUIRED: grant Location permission")
+    }
+    val now = System.currentTimeMillis()
+    val candidates =
+      providers.mapNotNull { provider -> manager.getLastKnownLocation(provider) }
+    val freshest = candidates.maxByOrNull { it.time } ?: return null
+    if (maxAgeMs != null && now - freshest.time > maxAgeMs) return null
+    return freshest
+  }
+
+  private suspend fun requestCurrent(
+    manager: LocationManager,
+    providers: List<String>,
+    timeoutMs: Long,
+  ): Location {
+    val fineOk =
+      ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_FINE_LOCATION) ==
+        PackageManager.PERMISSION_GRANTED
+    val coarseOk =
+      ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_COARSE_LOCATION) ==
+        PackageManager.PERMISSION_GRANTED
+    if (!fineOk && !coarseOk) {
+      throw IllegalStateException("LOCATION_PERMISSION_REQUIRED: grant Location permission")
+    }
+    val resolved =
+      providers.firstOrNull { manager.isProviderEnabled(it) }
+        ?: throw IllegalStateException("LOCATION_UNAVAILABLE: no providers available")
+    return withTimeout(timeoutMs.coerceAtLeast(1)) {
+      suspendCancellableCoroutine { cont ->
+        val signal = CancellationSignal()
+        cont.invokeOnCancellation { signal.cancel() }
+        manager.getCurrentLocation(resolved, signal, context.mainExecutor) { location ->
+          if (location != null) {
+            cont.resume(location)
+          } else {
+            cont.resumeWithException(IllegalStateException("LOCATION_UNAVAILABLE: no fix"))
+          }
+        }
+      }
+    }
+  }
+}

apps/android/app/src/main/java/com/clawdbot/android/node/ScreenRecordManager.kt

@@ -0,0 +1,199 @@
+package com.clawdbot.android.node
+
+import android.content.Context
+import android.hardware.display.DisplayManager
+import android.media.MediaRecorder
+import android.media.projection.MediaProjectionManager
+import android.os.Build
+import android.util.Base64
+import com.clawdbot.android.ScreenCaptureRequester
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.delay
+import kotlinx.coroutines.withContext
+import java.io.File
+import kotlin.math.roundToInt
+
+class ScreenRecordManager(private val context: Context) {
+  data class Payload(val payloadJson: String)
+
+  @Volatile private var screenCaptureRequester: ScreenCaptureRequester? = null
+  @Volatile private var permissionRequester: com.clawdbot.android.PermissionRequester? = null
+
+  fun attachScreenCaptureRequester(requester: ScreenCaptureRequester) {
+    screenCaptureRequester = requester
+  }
+
+  fun attachPermissionRequester(requester: com.clawdbot.android.PermissionRequester) {
+    permissionRequester = requester
+  }
+
+  suspend fun record(paramsJson: String?): Payload =
+    withContext(Dispatchers.Default) {
+      val requester =
+        screenCaptureRequester
+          ?: throw IllegalStateException(
+            "SCREEN_PERMISSION_REQUIRED: grant Screen Recording permission",
+          )
+
+      val durationMs = (parseDurationMs(paramsJson) ?: 10_000).coerceIn(250, 60_000)
+      val fps = (parseFps(paramsJson) ?: 10.0).coerceIn(1.0, 60.0)
+      val fpsInt = fps.roundToInt().coerceIn(1, 60)
+      val screenIndex = parseScreenIndex(paramsJson)
+      val includeAudio = parseIncludeAudio(paramsJson) ?: true
+      val format = parseString(paramsJson, key = "format")
+      if (format != null && format.lowercase() != "mp4") {
+        throw IllegalArgumentException("INVALID_REQUEST: screen format must be mp4")
+      }
+      if (screenIndex != null && screenIndex != 0) {
+        throw IllegalArgumentException("INVALID_REQUEST: screenIndex must be 0 on Android")
+      }
+
+      val capture = requester.requestCapture()
+        ?: throw IllegalStateException(
+          "SCREEN_PERMISSION_REQUIRED: grant Screen Recording permission",
+        )
+
+      val mgr =
+        context.getSystemService(Context.MEDIA_PROJECTION_SERVICE) as MediaProjectionManager
+      val projection = mgr.getMediaProjection(capture.resultCode, capture.data)
+        ?: throw IllegalStateException("UNAVAILABLE: screen capture unavailable")
+
+      val metrics = context.resources.displayMetrics
+      val width = metrics.widthPixels
+      val height = metrics.heightPixels
+      val densityDpi = metrics.densityDpi
+
+      val file = File.createTempFile("clawdbot-screen-", ".mp4")
+      if (includeAudio) ensureMicPermission()
+
+      val recorder = createMediaRecorder()
+      var virtualDisplay: android.hardware.display.VirtualDisplay? = null
+      try {
+        if (includeAudio) {
+          recorder.setAudioSource(MediaRecorder.AudioSource.MIC)
+        }
+        recorder.setVideoSource(MediaRecorder.VideoSource.SURFACE)
+        recorder.setOutputFormat(MediaRecorder.OutputFormat.MPEG_4)
+        recorder.setVideoEncoder(MediaRecorder.VideoEncoder.H264)
+        if (includeAudio) {
+          recorder.setAudioEncoder(MediaRecorder.AudioEncoder.AAC)
+          recorder.setAudioChannels(1)
+          recorder.setAudioSamplingRate(44_100)
+          recorder.setAudioEncodingBitRate(96_000)
+        }
+        recorder.setVideoSize(width, height)
+        recorder.setVideoFrameRate(fpsInt)
+        recorder.setVideoEncodingBitRate(estimateBitrate(width, height, fpsInt))
+        recorder.setOutputFile(file.absolutePath)
+        recorder.prepare()
+
+        val surface = recorder.surface
+        virtualDisplay =
+          projection.createVirtualDisplay(
+            "clawdbot-screen",
+            width,
+            height,
+            densityDpi,
+            DisplayManager.VIRTUAL_DISPLAY_FLAG_AUTO_MIRROR,
+            surface,
+            null,
+            null,
+          )
+
+        recorder.start()
+        delay(durationMs.toLong())
+      } finally {
+        try {
+          recorder.stop()
+        } catch (_: Throwable) {
+          // ignore
+        }
+        recorder.reset()
+        recorder.release()
+        virtualDisplay?.release()
+        projection.stop()
+      }
+
+      val bytes = withContext(Dispatchers.IO) { file.readBytes() }
+      file.delete()
+      val base64 = Base64.encodeToString(bytes, Base64.NO_WRAP)
+      Payload(
+        """{"format":"mp4","base64":"$base64","durationMs":$durationMs,"fps":$fpsInt,"screenIndex":0,"hasAudio":$includeAudio}""",
+      )
+    }
+
+  private fun createMediaRecorder(): MediaRecorder = MediaRecorder(context)
+
+  private suspend fun ensureMicPermission() {
+    val granted =
+      androidx.core.content.ContextCompat.checkSelfPermission(
+        context,
+        android.Manifest.permission.RECORD_AUDIO,
+      ) == android.content.pm.PackageManager.PERMISSION_GRANTED
+    if (granted) return
+
+    val requester =
+      permissionRequester
+        ?: throw IllegalStateException("MIC_PERMISSION_REQUIRED: grant Microphone permission")
+    val results = requester.requestIfMissing(listOf(android.Manifest.permission.RECORD_AUDIO))
+    if (results[android.Manifest.permission.RECORD_AUDIO] != true) {
+      throw IllegalStateException("MIC_PERMISSION_REQUIRED: grant Microphone permission")
+    }
+  }
+
+  private fun parseDurationMs(paramsJson: String?): Int? =
+    parseNumber(paramsJson, key = "durationMs")?.toIntOrNull()
+
+  private fun parseFps(paramsJson: String?): Double? =
+    parseNumber(paramsJson, key = "fps")?.toDoubleOrNull()
+
+  private fun parseScreenIndex(paramsJson: String?): Int? =
+    parseNumber(paramsJson, key = "screenIndex")?.toIntOrNull()
+
+  private fun parseIncludeAudio(paramsJson: String?): Boolean? {
+    val raw = paramsJson ?: return null
+    val key = "\"includeAudio\""
+    val idx = raw.indexOf(key)
+    if (idx < 0) return null
+    val colon = raw.indexOf(':', idx + key.length)
+    if (colon < 0) return null
+    val tail = raw.substring(colon + 1).trimStart()
+    return when {
+      tail.startsWith("true") -> true
+      tail.startsWith("false") -> false
+      else -> null
+    }
+  }
+
+  private fun parseNumber(paramsJson: String?, key: String): String? {
+    val raw = paramsJson ?: return null
+    val needle = "\"$key\""
+    val idx = raw.indexOf(needle)
+    if (idx < 0) return null
+    val colon = raw.indexOf(':', idx + needle.length)
+    if (colon < 0) return null
+    val tail = raw.substring(colon + 1).trimStart()
+    return tail.takeWhile { it.isDigit() || it == '.' || it == '-' }
+  }
+
+  private fun parseString(paramsJson: String?, key: String): String? {
+    val raw = paramsJson ?: return null
+    val needle = "\"$key\""
+    val idx = raw.indexOf(needle)
+    if (idx < 0) return null
+    val colon = raw.indexOf(':', idx + needle.length)
+    if (colon < 0) return null
+    val tail = raw.substring(colon + 1).trimStart()
+    if (!tail.startsWith('\"')) return null
+    val rest = tail.drop(1)
+    val end = rest.indexOf('\"')
+    if (end < 0) return null
+    return rest.substring(0, end)
+  }
+
+  private fun estimateBitrate(width: Int, height: Int, fps: Int): Int {
+    val pixels = width.toLong() * height.toLong()
+    val raw = (pixels * fps.toLong() * 2L).toInt()
+    return raw.coerceIn(1_000_000, 12_000_000)
+  }
+}

apps/android/app/src/main/java/com/clawdbot/android/node/SmsManager.kt

@@ -0,0 +1,230 @@
+package com.clawdbot.android.node
+
+import android.Manifest
+import android.content.Context
+import android.content.pm.PackageManager
+import android.telephony.SmsManager as AndroidSmsManager
+import androidx.core.content.ContextCompat
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.jsonObject
+import kotlinx.serialization.encodeToString
+import com.clawdbot.android.PermissionRequester
+
+/**
+ * Sends SMS messages via the Android SMS API.
+ * Requires SEND_SMS permission to be granted.
+ */
+class SmsManager(private val context: Context) {
+
+    private val json = JsonConfig
+    @Volatile private var permissionRequester: PermissionRequester? = null
+
+    data class SendResult(
+        val ok: Boolean,
+        val to: String,
+        val message: String?,
+        val error: String? = null,
+        val payloadJson: String,
+    )
+
+    internal data class ParsedParams(
+        val to: String,
+        val message: String,
+    )
+
+    internal sealed class ParseResult {
+        data class Ok(val params: ParsedParams) : ParseResult()
+        data class Error(
+            val error: String,
+            val to: String = "",
+            val message: String? = null,
+        ) : ParseResult()
+    }
+
+    internal data class SendPlan(
+        val parts: List<String>,
+        val useMultipart: Boolean,
+    )
+
+    companion object {
+        internal val JsonConfig = Json { ignoreUnknownKeys = true }
+
+        internal fun parseParams(paramsJson: String?, json: Json = JsonConfig): ParseResult {
+            val params = paramsJson?.trim().orEmpty()
+            if (params.isEmpty()) {
+                return ParseResult.Error(error = "INVALID_REQUEST: paramsJSON required")
+            }
+
+            val obj = try {
+                json.parseToJsonElement(params).jsonObject
+            } catch (_: Throwable) {
+                null
+            }
+
+            if (obj == null) {
+                return ParseResult.Error(error = "INVALID_REQUEST: expected JSON object")
+            }
+
+            val to = (obj["to"] as? JsonPrimitive)?.content?.trim().orEmpty()
+            val message = (obj["message"] as? JsonPrimitive)?.content.orEmpty()
+
+            if (to.isEmpty()) {
+                return ParseResult.Error(
+                    error = "INVALID_REQUEST: 'to' phone number required",
+                    message = message,
+                )
+            }
+
+            if (message.isEmpty()) {
+                return ParseResult.Error(
+                    error = "INVALID_REQUEST: 'message' text required",
+                    to = to,
+                )
+            }
+
+            return ParseResult.Ok(ParsedParams(to = to, message = message))
+        }
+
+        internal fun buildSendPlan(
+            message: String,
+            divider: (String) -> List<String>,
+        ): SendPlan {
+            val parts = divider(message).ifEmpty { listOf(message) }
+            return SendPlan(parts = parts, useMultipart = parts.size > 1)
+        }
+
+        internal fun buildPayloadJson(
+            json: Json = JsonConfig,
+            ok: Boolean,
+            to: String,
+            error: String?,
+        ): String {
+            val payload =
+                mutableMapOf<String, JsonElement>(
+                    "ok" to JsonPrimitive(ok),
+                    "to" to JsonPrimitive(to),
+                )
+            if (!ok) {
+                payload["error"] = JsonPrimitive(error ?: "SMS_SEND_FAILED")
+            }
+            return json.encodeToString(JsonObject.serializer(), JsonObject(payload))
+        }
+    }
+
+    fun hasSmsPermission(): Boolean {
+        return ContextCompat.checkSelfPermission(
+            context,
+            Manifest.permission.SEND_SMS
+        ) == PackageManager.PERMISSION_GRANTED
+    }
+
+    fun canSendSms(): Boolean {
+        return hasSmsPermission() && hasTelephonyFeature()
+    }
+
+    fun hasTelephonyFeature(): Boolean {
+        return context.packageManager?.hasSystemFeature(PackageManager.FEATURE_TELEPHONY) == true
+    }
+
+    fun attachPermissionRequester(requester: PermissionRequester) {
+        permissionRequester = requester
+    }
+
+    /**
+     * Send an SMS message.
+     * 
+     * @param paramsJson JSON with "to" (phone number) and "message" (text) fields
+     * @return SendResult indicating success or failure
+     */
+    suspend fun send(paramsJson: String?): SendResult {
+        if (!hasTelephonyFeature()) {
+            return errorResult(
+                error = "SMS_UNAVAILABLE: telephony not available",
+            )
+        }
+
+        if (!ensureSmsPermission()) {
+            return errorResult(
+                error = "SMS_PERMISSION_REQUIRED: grant SMS permission",
+            )
+        }
+
+        val parseResult = parseParams(paramsJson, json)
+        if (parseResult is ParseResult.Error) {
+            return errorResult(
+                error = parseResult.error,
+                to = parseResult.to,
+                message = parseResult.message,
+            )
+        }
+        val params = (parseResult as ParseResult.Ok).params
+
+        return try {
+            val smsManager = context.getSystemService(AndroidSmsManager::class.java)
+                ?: throw IllegalStateException("SMS_UNAVAILABLE: SmsManager not available")
+
+            val plan = buildSendPlan(params.message) { smsManager.divideMessage(it) }
+            if (plan.useMultipart) {
+                smsManager.sendMultipartTextMessage(
+                    params.to,     // destination
+                    null,          // service center (null = default)
+                    ArrayList(plan.parts),    // message parts
+                    null,          // sent intents
+                    null,          // delivery intents
+                )
+            } else {
+                smsManager.sendTextMessage(
+                    params.to,     // destination
+                    null,          // service center (null = default)
+                    params.message,// message
+                    null,          // sent intent
+                    null,          // delivery intent
+                )
+            }
+
+            okResult(to = params.to, message = params.message)
+        } catch (e: SecurityException) {
+            errorResult(
+                error = "SMS_PERMISSION_REQUIRED: ${e.message}",
+                to = params.to,
+                message = params.message,
+            )
+        } catch (e: Throwable) {
+            errorResult(
+                error = "SMS_SEND_FAILED: ${e.message ?: "unknown error"}",
+                to = params.to,
+                message = params.message,
+            )
+        }
+    }
+
+    private suspend fun ensureSmsPermission(): Boolean {
+        if (hasSmsPermission()) return true
+        val requester = permissionRequester ?: return false
+        val results = requester.requestIfMissing(listOf(Manifest.permission.SEND_SMS))
+        return results[Manifest.permission.SEND_SMS] == true
+    }
+
+    private fun okResult(to: String, message: String): SendResult {
+        return SendResult(
+            ok = true,
+            to = to,
+            message = message,
+            error = null,
+            payloadJson = buildPayloadJson(json = json, ok = true, to = to, error = null),
+        )
+    }
+
+    private fun errorResult(error: String, to: String = "", message: String? = null): SendResult {
+        return SendResult(
+            ok = false,
+            to = to,
+            message = message,
+            error = error,
+            payloadJson = buildPayloadJson(json = json, ok = false, to = to, error = error),
+        )
+    }
+}

apps/android/app/src/main/java/com/clawdbot/android/protocol/ClawdbotCanvasA2UIAction.kt

@@ -0,0 +1,66 @@
+package com.clawdbot.android.protocol
+
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+
+object ClawdbotCanvasA2UIAction {
+  fun extractActionName(userAction: JsonObject): String? {
+    val name =
+      (userAction["name"] as? JsonPrimitive)
+        ?.content
+        ?.trim()
+        .orEmpty()
+    if (name.isNotEmpty()) return name
+    val action =
+      (userAction["action"] as? JsonPrimitive)
+        ?.content
+        ?.trim()
+        .orEmpty()
+    return action.ifEmpty { null }
+  }
+
+  fun sanitizeTagValue(value: String): String {
+    val trimmed = value.trim().ifEmpty { "-" }
+    val normalized = trimmed.replace(" ", "_")
+    val out = StringBuilder(normalized.length)
+    for (c in normalized) {
+      val ok =
+        c.isLetterOrDigit() ||
+          c == '_' ||
+          c == '-' ||
+          c == '.' ||
+          c == ':'
+      out.append(if (ok) c else '_')
+    }
+    return out.toString()
+  }
+
+  fun formatAgentMessage(
+    actionName: String,
+    sessionKey: String,
+    surfaceId: String,
+    sourceComponentId: String,
+    host: String,
+    instanceId: String,
+    contextJson: String?,
+  ): String {
+    val ctxSuffix = contextJson?.takeIf { it.isNotBlank() }?.let { " ctx=$it" }.orEmpty()
+    return listOf(
+      "CANVAS_A2UI",
+      "action=${sanitizeTagValue(actionName)}",
+      "session=${sanitizeTagValue(sessionKey)}",
+      "surface=${sanitizeTagValue(surfaceId)}",
+      "component=${sanitizeTagValue(sourceComponentId)}",
+      "host=${sanitizeTagValue(host)}",
+      "instance=${sanitizeTagValue(instanceId)}$ctxSuffix",
+      "default=update_canvas",
+    ).joinToString(separator = " ")
+  }
+
+  fun jsDispatchA2UIActionStatus(actionId: String, ok: Boolean, error: String?): String {
+    val err = (error ?: "").replace("\\", "\\\\").replace("\"", "\\\"")
+    val okLiteral = if (ok) "true" else "false"
+    val idEscaped = actionId.replace("\\", "\\\\").replace("\"", "\\\"")
+    return "window.dispatchEvent(new CustomEvent('clawdbot:a2ui-action-status', { detail: { id: \"${idEscaped}\", ok: ${okLiteral}, error: \"${err}\" } }));"
+  }
+}

apps/android/app/src/main/java/com/clawdbot/android/protocol/ClawdbotProtocolConstants.kt

@@ -0,0 +1,71 @@
+package com.clawdbot.android.protocol
+
+enum class ClawdbotCapability(val rawValue: String) {
+  Canvas("canvas"),
+  Camera("camera"),
+  Screen("screen"),
+  Sms("sms"),
+  VoiceWake("voiceWake"),
+  Location("location"),
+}
+
+enum class ClawdbotCanvasCommand(val rawValue: String) {
+  Present("canvas.present"),
+  Hide("canvas.hide"),
+  Navigate("canvas.navigate"),
+  Eval("canvas.eval"),
+  Snapshot("canvas.snapshot"),
+  ;
+
+  companion object {
+    const val NamespacePrefix: String = "canvas."
+  }
+}
+
+enum class ClawdbotCanvasA2UICommand(val rawValue: String) {
+  Push("canvas.a2ui.push"),
+  PushJSONL("canvas.a2ui.pushJSONL"),
+  Reset("canvas.a2ui.reset"),
+  ;
+
+  companion object {
+    const val NamespacePrefix: String = "canvas.a2ui."
+  }
+}
+
+enum class ClawdbotCameraCommand(val rawValue: String) {
+  Snap("camera.snap"),
+  Clip("camera.clip"),
+  ;
+
+  companion object {
+    const val NamespacePrefix: String = "camera."
+  }
+}
+
+enum class ClawdbotScreenCommand(val rawValue: String) {
+  Record("screen.record"),
+  ;
+
+  companion object {
+    const val NamespacePrefix: String = "screen."
+  }
+}
+
+enum class ClawdbotSmsCommand(val rawValue: String) {
+  Send("sms.send"),
+  ;
+
+  companion object {
+    const val NamespacePrefix: String = "sms."
+  }
+}
+
+enum class ClawdbotLocationCommand(val rawValue: String) {
+  Get("location.get"),
+  ;
+
+  companion object {
+    const val NamespacePrefix: String = "location."
+  }
+}

apps/android/app/src/main/java/com/clawdbot/android/tools/ToolDisplay.kt

@@ -0,0 +1,222 @@
+package com.clawdbot.android.tools
+
+import android.content.Context
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.JsonArray
+import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+import kotlinx.serialization.json.contentOrNull
+
+@Serializable
+private data class ToolDisplayActionSpec(
+  val label: String? = null,
+  val detailKeys: List<String>? = null,
+)
+
+@Serializable
+private data class ToolDisplaySpec(
+  val emoji: String? = null,
+  val title: String? = null,
+  val label: String? = null,
+  val detailKeys: List<String>? = null,
+  val actions: Map<String, ToolDisplayActionSpec>? = null,
+)
+
+@Serializable
+private data class ToolDisplayConfig(
+  val version: Int? = null,
+  val fallback: ToolDisplaySpec? = null,
+  val tools: Map<String, ToolDisplaySpec>? = null,
+)
+
+data class ToolDisplaySummary(
+  val name: String,
+  val emoji: String,
+  val title: String,
+  val label: String,
+  val verb: String?,
+  val detail: String?,
+) {
+  val detailLine: String?
+    get() {
+      val parts = mutableListOf<String>()
+      if (!verb.isNullOrBlank()) parts.add(verb)
+      if (!detail.isNullOrBlank()) parts.add(detail)
+      return if (parts.isEmpty()) null else parts.joinToString(" · ")
+    }
+
+  val summaryLine: String
+    get() = if (detailLine != null) "${emoji} ${label}: ${detailLine}" else "${emoji} ${label}"
+}
+
+object ToolDisplayRegistry {
+  private const val CONFIG_ASSET = "tool-display.json"
+
+  private val json = Json { ignoreUnknownKeys = true }
+  @Volatile private var cachedConfig: ToolDisplayConfig? = null
+
+  fun resolve(
+    context: Context,
+    name: String?,
+    args: JsonObject?,
+    meta: String? = null,
+  ): ToolDisplaySummary {
+    val trimmedName = name?.trim().orEmpty().ifEmpty { "tool" }
+    val key = trimmedName.lowercase()
+    val config = loadConfig(context)
+    val spec = config.tools?.get(key)
+    val fallback = config.fallback
+
+    val emoji = spec?.emoji ?: fallback?.emoji ?: "🧩"
+    val title = spec?.title ?: titleFromName(trimmedName)
+    val label = spec?.label ?: trimmedName
+
+    val actionRaw = args?.get("action")?.asStringOrNull()?.trim()
+    val action = actionRaw?.takeIf { it.isNotEmpty() }
+    val actionSpec = action?.let { spec?.actions?.get(it) }
+    val verb = normalizeVerb(actionSpec?.label ?: action)
+
+    var detail: String? = null
+    if (key == "read") {
+      detail = readDetail(args)
+    } else if (key == "write" || key == "edit" || key == "attach") {
+      detail = pathDetail(args)
+    }
+
+    val detailKeys = actionSpec?.detailKeys ?: spec?.detailKeys ?: fallback?.detailKeys ?: emptyList()
+    if (detail == null) {
+      detail = firstValue(args, detailKeys)
+    }
+
+    if (detail == null) {
+      detail = meta
+    }
+
+    if (detail != null) {
+      detail = shortenHomeInString(detail)
+    }
+
+    return ToolDisplaySummary(
+      name = trimmedName,
+      emoji = emoji,
+      title = title,
+      label = label,
+      verb = verb,
+      detail = detail,
+    )
+  }
+
+  private fun loadConfig(context: Context): ToolDisplayConfig {
+    val existing = cachedConfig
+    if (existing != null) return existing
+    return try {
+      val jsonString = context.assets.open(CONFIG_ASSET).bufferedReader().use { it.readText() }
+      val decoded = json.decodeFromString(ToolDisplayConfig.serializer(), jsonString)
+      cachedConfig = decoded
+      decoded
+    } catch (_: Throwable) {
+      val fallback = ToolDisplayConfig()
+      cachedConfig = fallback
+      fallback
+    }
+  }
+
+  private fun titleFromName(name: String): String {
+    val cleaned = name.replace("_", " ").trim()
+    if (cleaned.isEmpty()) return "Tool"
+    return cleaned
+      .split(Regex("\\s+"))
+      .joinToString(" ") { part ->
+        val upper = part.uppercase()
+        if (part.length <= 2 && part == upper) part
+        else upper.firstOrNull()?.toString().orEmpty() + part.lowercase().drop(1)
+      }
+  }
+
+  private fun normalizeVerb(value: String?): String? {
+    val trimmed = value?.trim().orEmpty()
+    if (trimmed.isEmpty()) return null
+    return trimmed.replace("_", " ")
+  }
+
+  private fun readDetail(args: JsonObject?): String? {
+    val path = args?.get("path")?.asStringOrNull() ?: return null
+    val offset = args["offset"].asNumberOrNull()
+    val limit = args["limit"].asNumberOrNull()
+    return if (offset != null && limit != null) {
+      val end = offset + limit
+      "${path}:${offset.toInt()}-${end.toInt()}"
+    } else {
+      path
+    }
+  }
+
+  private fun pathDetail(args: JsonObject?): String? {
+    return args?.get("path")?.asStringOrNull()
+  }
+
+  private fun firstValue(args: JsonObject?, keys: List<String>): String? {
+    for (key in keys) {
+      val value = valueForPath(args, key)
+      val rendered = renderValue(value)
+      if (!rendered.isNullOrBlank()) return rendered
+    }
+    return null
+  }
+
+  private fun valueForPath(args: JsonObject?, path: String): JsonElement? {
+    var current: JsonElement? = args
+    for (segment in path.split(".")) {
+      if (segment.isBlank()) return null
+      val obj = current as? JsonObject ?: return null
+      current = obj[segment]
+    }
+    return current
+  }
+
+  private fun renderValue(value: JsonElement?): String? {
+    if (value == null) return null
+    if (value is JsonPrimitive) {
+      if (value.isString) {
+        val trimmed = value.contentOrNull?.trim().orEmpty()
+        if (trimmed.isEmpty()) return null
+        val firstLine = trimmed.lineSequence().firstOrNull()?.trim().orEmpty()
+        if (firstLine.isEmpty()) return null
+        return if (firstLine.length > 160) "${firstLine.take(157)}…" else firstLine
+      }
+      val raw = value.contentOrNull?.trim().orEmpty()
+      raw.toBooleanStrictOrNull()?.let { return it.toString() }
+      raw.toLongOrNull()?.let { return it.toString() }
+      raw.toDoubleOrNull()?.let { return it.toString() }
+    }
+    if (value is JsonArray) {
+      val items = value.mapNotNull { renderValue(it) }
+      if (items.isEmpty()) return null
+      val preview = items.take(3).joinToString(", ")
+      return if (items.size > 3) "${preview}…" else preview
+    }
+    return null
+  }
+
+  private fun shortenHomeInString(value: String): String {
+    val home = System.getProperty("user.home")?.takeIf { it.isNotBlank() }
+      ?: System.getenv("HOME")?.takeIf { it.isNotBlank() }
+    if (home.isNullOrEmpty()) return value
+    return value.replace(home, "~")
+      .replace(Regex("/Users/[^/]+"), "~")
+      .replace(Regex("/home/[^/]+"), "~")
+  }
+
+  private fun JsonElement?.asStringOrNull(): String? {
+    val primitive = this as? JsonPrimitive ?: return null
+    return if (primitive.isString) primitive.contentOrNull else primitive.toString()
+  }
+
+  private fun JsonElement?.asNumberOrNull(): Double? {
+    val primitive = this as? JsonPrimitive ?: return null
+    val raw = primitive.contentOrNull ?: return null
+    return raw.toDoubleOrNull()
+  }
+}

apps/android/app/src/main/java/com/clawdbot/android/ui/CameraHudOverlay.kt

@@ -0,0 +1,44 @@
+package com.clawdbot.android.ui
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
+import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableFloatStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.setValue
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.alpha
+import androidx.compose.ui.graphics.Color
+import kotlinx.coroutines.delay
+
+@Composable
+fun CameraFlashOverlay(
+  token: Long,
+  modifier: Modifier = Modifier,
+) {
+  Box(modifier = modifier.fillMaxSize()) {
+    CameraFlash(token = token)
+  }
+}
+
+@Composable
+private fun CameraFlash(token: Long) {
+  var alpha by remember { mutableFloatStateOf(0f) }
+  LaunchedEffect(token) {
+    if (token == 0L) return@LaunchedEffect
+    alpha = 0.85f
+    delay(110)
+    alpha = 0f
+  }
+
+  Box(
+    modifier =
+      Modifier
+        .fillMaxSize()
+        .alpha(alpha)
+        .background(Color.White),
+  )
+}