build: prepare 2026.3.13-beta.1

docs: reorder unreleased changelog by impact
fix: keep windows onboarding logs ascii-safe
2026-03-14 04:56:02 +00:00 · 2026-03-14 04:50:36 +00:00 · 2026-03-14 04:46:47 +00:00 · 2026-03-14 04:46:47 +00:00 · 2026-03-14 04:33:37 +00:00 · 2026-03-14 04:15:34 +00:00
1183 changed files with 59552 additions and 31936 deletions
@@ -1,5 +1,11 @@
 .git
 .worktrees
+
+# Sensitive files – docker-setup.sh writes .env with OPENCLAW_GATEWAY_TOKEN
+# into the project root; keep it out of the build context.
+.env
+.env.*
+
 .bun-cache
 .bun
 .tmp
@@ -49,7 +49,7 @@ runs:
        exit 1

    - name: Setup Node.js
-      uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+      uses: actions/setup-node@v6
      with:
        node-version: ${{ inputs.node-version }}
        check-latest: false
@@ -63,7 +63,7 @@ runs:

    - name: Setup Bun
      if: inputs.install-bun == 'true'
-      uses: oven-sh/setup-bun@v2
+      uses: oven-sh/setup-bun@v2.1.3
      with:
        bun-version: "1.3.9"

@@ -61,14 +61,14 @@ runs:
    - name: Restore pnpm store cache (exact key only)
      # PRs that request sticky disks still need a safe cache restore path.
      if: inputs.use-actions-cache == 'true' && (inputs.use-sticky-disk != 'true' || github.event_name == 'pull_request') && inputs.use-restore-keys != 'true'
-      uses: actions/cache@v4
+      uses: actions/cache@v5
      with:
        path: ${{ steps.pnpm-store.outputs.path }}
        key: ${{ runner.os }}-pnpm-store-${{ inputs.cache-key-suffix }}-${{ hashFiles('pnpm-lock.yaml') }}

    - name: Restore pnpm store cache (with fallback keys)
      if: inputs.use-actions-cache == 'true' && (inputs.use-sticky-disk != 'true' || github.event_name == 'pull_request') && inputs.use-restore-keys == 'true'
-      uses: actions/cache@v4
+      uses: actions/cache@v5
      with:
        path: ${{ steps.pnpm-store.outputs.path }}
        key: ${{ runner.os }}-pnpm-store-${{ inputs.cache-key-suffix }}-${{ hashFiles('pnpm-lock.yaml') }}
@@ -5,9 +5,12 @@ on:
    types: [opened, edited, labeled]
  issue_comment:
    types: [created]
-  pull_request_target:
+  pull_request_target: # zizmor: ignore[dangerous-triggers] maintainer-owned label automation; no untrusted checkout or code execution
    types: [labeled]

+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
 permissions: {}

 jobs:
@@ -17,20 +20,20 @@ jobs:
      pull-requests: write
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
-      - uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
+      - uses: actions/create-github-app-token@v2
        id: app-token
        continue-on-error: true
        with:
          app-id: "2729701"
          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
-      - uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
+      - uses: actions/create-github-app-token@v2
        id: app-token-fallback
        if: steps.app-token.outcome == 'failure'
        with:
          app-id: "2971289"
          private-key: ${{ secrets.GH_APP_PRIVATE_KEY_FALLBACK }}
      - name: Handle labeled items
-        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+        uses: actions/github-script@v8
        with:
          github-token: ${{ steps.app-token.outputs.token || steps.app-token-fallback.outputs.token }}
          script: |
@@ -7,7 +7,10 @@ on:

 concurrency:
  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+  cancel-in-progress: true
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"

 jobs:
  # Detect docs-only changes to skip heavy jobs (test, build, Windows, macOS, Android).
@@ -19,7 +22,7 @@ jobs:
      docs_changed: ${{ steps.check.outputs.docs_changed }}
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          fetch-depth: 1
          fetch-tags: false
@@ -35,9 +38,8 @@ jobs:
        id: check
        uses: ./.github/actions/detect-docs-changes

-  # Detect which heavy areas are touched so PRs can skip unrelated expensive jobs.
-  # Push to main keeps broad coverage, but this job still needs to run so
-  # downstream jobs that list it in `needs` are not skipped.
+  # Detect which heavy areas are touched so CI can skip unrelated expensive jobs.
+  # Fail-safe: if detection fails, downstream jobs run.
  changed-scope:
    needs: [docs-scope]
    if: needs.docs-scope.outputs.docs_only != 'true'
@@ -50,7 +52,7 @@ jobs:
      run_windows: ${{ steps.scope.outputs.run_windows }}
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          fetch-depth: 1
          fetch-tags: false
@@ -79,11 +81,11 @@ jobs:
  # Build dist once for Node-relevant changes and share it with downstream jobs.
  build-artifacts:
    needs: [docs-scope, changed-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true')
+    if: github.event_name == 'push' && needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_node == 'true'
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          submodules: false

@@ -98,13 +100,13 @@ jobs:
        uses: ./.github/actions/setup-node-env
        with:
          install-bun: "false"
-          use-sticky-disk: "true"
+          use-sticky-disk: "false"

      - name: Build dist
        run: pnpm build

      - name: Upload dist artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
        with:
          name: dist-build
          path: dist/
@@ -117,7 +119,7 @@ jobs:
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          submodules: false

@@ -125,10 +127,10 @@ jobs:
        uses: ./.github/actions/setup-node-env
        with:
          install-bun: "false"
-          use-sticky-disk: "true"
+          use-sticky-disk: "false"

      - name: Download dist artifact
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
        with:
          name: dist-build
          path: dist/
@@ -138,7 +140,7 @@ jobs:

  checks:
    needs: [docs-scope, changed-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true')
+    if: needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_node == 'true'
    runs-on: blacksmith-16vcpu-ubuntu-2404
    strategy:
      fail-fast: false
@@ -146,6 +148,13 @@ jobs:
        include:
          - runtime: node
            task: test
+            shard_index: 1
+            shard_count: 2
+            command: pnpm canvas:a2ui:bundle && pnpm test
+          - runtime: node
+            task: test
+            shard_index: 2
+            shard_count: 2
            command: pnpm canvas:a2ui:bundle && pnpm test
          - runtime: node
            task: extensions
@@ -157,44 +166,51 @@ jobs:
            task: test
            command: pnpm canvas:a2ui:bundle && bunx vitest run --config vitest.unit.config.ts
    steps:
-      - name: Skip bun lane on push
-        if: github.event_name == 'push' && matrix.runtime == 'bun'
-        run: echo "Skipping bun test lane on push events."
+      - name: Skip bun lane on pull requests
+        if: github.event_name == 'pull_request' && matrix.runtime == 'bun'
+        run: echo "Skipping Bun compatibility lane on pull requests."

      - name: Checkout
-        if: github.event_name != 'push' || matrix.runtime != 'bun'
-        uses: actions/checkout@v4
+        if: github.event_name != 'pull_request' || matrix.runtime != 'bun'
+        uses: actions/checkout@v6
        with:
          submodules: false

      - name: Setup Node environment
-        if: matrix.runtime != 'bun' || github.event_name != 'push'
+        if: matrix.runtime != 'bun' || github.event_name != 'pull_request'
        uses: ./.github/actions/setup-node-env
        with:
          install-bun: "${{ matrix.runtime == 'bun' }}"
-          use-sticky-disk: "true"
+          use-sticky-disk: "false"

      - name: Configure Node test resources
-        if: (github.event_name != 'push' || matrix.runtime != 'bun') && matrix.task == 'test' && matrix.runtime == 'node'
+        if: (github.event_name != 'pull_request' || matrix.runtime != 'bun') && matrix.task == 'test' && matrix.runtime == 'node'
+        env:
+          SHARD_COUNT: ${{ matrix.shard_count || '' }}
+          SHARD_INDEX: ${{ matrix.shard_index || '' }}
        run: |
          # `pnpm test` runs `scripts/test-parallel.mjs`, which spawns multiple Node processes.
          # Default heap limits have been too low on Linux CI (V8 OOM near 4GB).
          echo "OPENCLAW_TEST_WORKERS=2" >> "$GITHUB_ENV"
          echo "OPENCLAW_TEST_MAX_OLD_SPACE_SIZE_MB=6144" >> "$GITHUB_ENV"
+          if [ -n "$SHARD_COUNT" ] && [ -n "$SHARD_INDEX" ]; then
+            echo "OPENCLAW_TEST_SHARDS=$SHARD_COUNT" >> "$GITHUB_ENV"
+            echo "OPENCLAW_TEST_SHARD_INDEX=$SHARD_INDEX" >> "$GITHUB_ENV"
+          fi

      - name: Run ${{ matrix.task }} (${{ matrix.runtime }})
-        if: matrix.runtime != 'bun' || github.event_name != 'push'
+        if: matrix.runtime != 'bun' || github.event_name != 'pull_request'
        run: ${{ matrix.command }}

  # Types, lint, and format check.
  check:
    name: "check"
    needs: [docs-scope, changed-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true')
+    if: needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_node == 'true'
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          submodules: false

@@ -202,7 +218,7 @@ jobs:
        uses: ./.github/actions/setup-node-env
        with:
          install-bun: "false"
-          use-sticky-disk: "true"
+          use-sticky-disk: "false"

      - name: Check types and lint and oxfmt
        run: pnpm check
@@ -220,7 +236,7 @@ jobs:
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          submodules: false

@@ -228,7 +244,7 @@ jobs:
        uses: ./.github/actions/setup-node-env
        with:
          install-bun: "false"
-          use-sticky-disk: "true"
+          use-sticky-disk: "false"

      - name: Check docs
        run: pnpm check:docs
@@ -236,11 +252,11 @@ jobs:
  compat-node22:
    name: "compat-node22"
    needs: [docs-scope, changed-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true')
+    if: github.event_name == 'push' && needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_node == 'true'
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          submodules: false

@@ -250,7 +266,7 @@ jobs:
          node-version: "22.x"
          cache-key-suffix: "node22"
          install-bun: "false"
-          use-sticky-disk: "true"
+          use-sticky-disk: "false"

      - name: Configure Node 22 test resources
        run: |
@@ -269,16 +285,16 @@ jobs:

  skills-python:
    needs: [docs-scope, changed-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_node == 'true' || needs.changed-scope.outputs.run_skills_python == 'true')
+    if: needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_skills_python == 'true'
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          submodules: false

      - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
        with:
          python-version: "3.12"

@@ -297,7 +313,7 @@ jobs:
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          submodules: false

@@ -316,7 +332,7 @@ jobs:

      - name: Setup Python
        id: setup-python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
        with:
          python-version: "3.12"
          cache: "pip"
@@ -326,7 +342,7 @@ jobs:
            .github/workflows/ci.yml

      - name: Restore pre-commit cache
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: ~/.cache/pre-commit
          key: pre-commit-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('.pre-commit-config.yaml') }}
@@ -362,7 +378,7 @@ jobs:

  checks-windows:
    needs: [docs-scope, changed-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_windows == 'true')
+    if: needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_windows == 'true'
    runs-on: blacksmith-32vcpu-windows-2025
    timeout-minutes: 45
    env:
@@ -409,7 +425,7 @@ jobs:
            command: pnpm test
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          submodules: false

@@ -433,7 +449,7 @@ jobs:
          }

      - name: Setup Node.js
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        uses: actions/setup-node@v6
        with:
          node-version: 24.x
          check-latest: false
@@ -495,7 +511,7 @@ jobs:
    runs-on: macos-latest
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          submodules: false

@@ -531,7 +547,7 @@ jobs:
          swiftformat --lint apps/macos/Sources --config .swiftformat

      - name: Cache SwiftPM
-        uses: actions/cache@v4
+        uses: actions/cache@v5
        with:
          path: ~/Library/Caches/org.swift.swiftpm
          key: ${{ runner.os }}-swiftpm-${{ hashFiles('apps/macos/Package.resolved') }}
@@ -567,7 +583,7 @@ jobs:
    runs-on: macos-latest
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          submodules: false

@@ -724,7 +740,7 @@ jobs:

  android:
    needs: [docs-scope, changed-scope]
-    if: needs.docs-scope.outputs.docs_only != 'true' && (github.event_name == 'push' || needs.changed-scope.outputs.run_android == 'true')
+    if: needs.docs-scope.outputs.docs_only != 'true' && needs.changed-scope.outputs.run_android == 'true'
    runs-on: blacksmith-16vcpu-ubuntu-2404
    strategy:
      fail-fast: false
@@ -736,31 +752,45 @@ jobs:
            command: ./gradlew --no-daemon :app:assembleDebug
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          submodules: false

      - name: Setup Java
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@v5
        with:
          distribution: temurin
-          # setup-android's sdkmanager currently crashes on JDK 21 in CI.
+          # Keep sdkmanager on the stable JDK path for Linux CI runners.
          java-version: 17

-      - name: Setup Android SDK
-        uses: android-actions/setup-android@v3
-        with:
-          accept-android-sdk-licenses: false
+      - name: Setup Android SDK cmdline-tools
+        run: |
+          set -euo pipefail
+          ANDROID_SDK_ROOT="$HOME/.android-sdk"
+          CMDLINE_TOOLS_VERSION="12266719"
+          ARCHIVE="commandlinetools-linux-${CMDLINE_TOOLS_VERSION}_latest.zip"
+          URL="https://dl.google.com/android/repository/${ARCHIVE}"
+
+          mkdir -p "$ANDROID_SDK_ROOT/cmdline-tools"
+          curl -fsSL "$URL" -o "/tmp/${ARCHIVE}"
+          rm -rf "$ANDROID_SDK_ROOT/cmdline-tools/latest"
+          unzip -q "/tmp/${ARCHIVE}" -d "$ANDROID_SDK_ROOT/cmdline-tools"
+          mv "$ANDROID_SDK_ROOT/cmdline-tools/cmdline-tools" "$ANDROID_SDK_ROOT/cmdline-tools/latest"
+
+          echo "ANDROID_SDK_ROOT=$ANDROID_SDK_ROOT" >> "$GITHUB_ENV"
+          echo "ANDROID_HOME=$ANDROID_SDK_ROOT" >> "$GITHUB_ENV"
+          echo "$ANDROID_SDK_ROOT/cmdline-tools/latest/bin" >> "$GITHUB_PATH"
+          echo "$ANDROID_SDK_ROOT/platform-tools" >> "$GITHUB_PATH"

      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v4
+        uses: gradle/actions/setup-gradle@v5
        with:
          gradle-version: 8.11.1

      - name: Install Android SDK packages
        run: |
-          yes | sdkmanager --licenses >/dev/null
-          sdkmanager --install \
+          yes | sdkmanager --sdk_root="${ANDROID_SDK_ROOT}" --licenses >/dev/null
+          sdkmanager --sdk_root="${ANDROID_SDK_ROOT}" --install \
            "platform-tools" \
            "platforms;android-36" \
            "build-tools;36.0.0"
@@ -7,6 +7,9 @@ concurrency:
  group: codeql-${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
 permissions:
  actions: read
  contents: read
@@ -67,7 +70,7 @@ jobs:
            config_file: ""
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          submodules: false

@@ -76,17 +79,17 @@ jobs:
        uses: ./.github/actions/setup-node-env
        with:
          install-bun: "false"
-          use-sticky-disk: "true"
+          use-sticky-disk: "false"

      - name: Setup Python
        if: matrix.needs_python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
        with:
          python-version: "3.12"

      - name: Setup Java
        if: matrix.needs_java
-        uses: actions/setup-java@v4
+        uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: "21"
@@ -18,6 +18,7 @@ concurrency:
  cancel-in-progress: false

 env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

@@ -33,13 +34,13 @@ jobs:
      slim-digest: ${{ steps.build-slim.outputs.digest }}
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Set up Docker Builder
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4

      - name: Login to GitHub Container Registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.repository_owner }}
@@ -134,13 +135,13 @@ jobs:
      slim-digest: ${{ steps.build-slim.outputs.digest }}
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Set up Docker Builder
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4

      - name: Login to GitHub Container Registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.repository_owner }}
@@ -233,10 +234,10 @@ jobs:
    needs: [build-amd64, build-arm64]
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Login to GitHub Container Registry
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.repository_owner }}
@@ -10,6 +10,9 @@ concurrency:
  group: install-smoke-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
 jobs:
  docs-scope:
    runs-on: blacksmith-16vcpu-ubuntu-2404
@@ -17,7 +20,7 @@ jobs:
      docs_only: ${{ steps.check.outputs.docs_only }}
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          fetch-depth: 1
          fetch-tags: false
@@ -38,10 +41,10 @@ jobs:
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
      - name: Checkout CLI
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Set up Docker Builder
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4

      # Blacksmith can fall back to the local docker driver, which rejects gha
      # cache export/import. Keep smoke builds driver-agnostic.
@@ -1,7 +1,7 @@
 name: Labeler

 on:
-  pull_request_target:
+  pull_request_target: # zizmor: ignore[dangerous-triggers] maintainer-owned triage workflow; no untrusted checkout or PR code execution
    types: [opened, synchronize, reopened]
  issues:
    types: [opened]
@@ -16,6 +16,9 @@ on:
        required: false
        default: "50"

+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
 permissions: {}

 jobs:
@@ -25,25 +28,25 @@ jobs:
      pull-requests: write
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
-      - uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
+      - uses: actions/create-github-app-token@v2
        id: app-token
        continue-on-error: true
        with:
          app-id: "2729701"
          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
-      - uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
+      - uses: actions/create-github-app-token@v2
        id: app-token-fallback
        if: steps.app-token.outcome == 'failure'
        with:
          app-id: "2971289"
          private-key: ${{ secrets.GH_APP_PRIVATE_KEY_FALLBACK }}
-      - uses: actions/labeler@8558fd74291d67161a8a78ce36a881fa63b766a9 # v5
+      - uses: actions/labeler@v6
        with:
          configuration-path: .github/labeler.yml
          repo-token: ${{ steps.app-token.outputs.token || steps.app-token-fallback.outputs.token }}
          sync-labels: true
      - name: Apply PR size label
-        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+        uses: actions/github-script@v8
        with:
          github-token: ${{ steps.app-token.outputs.token || steps.app-token-fallback.outputs.token }}
          script: |
@@ -132,7 +135,7 @@ jobs:
              labels: [targetSizeLabel],
            });
      - name: Apply maintainer or trusted-contributor label
-        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+        uses: actions/github-script@v8
        with:
          github-token: ${{ steps.app-token.outputs.token || steps.app-token-fallback.outputs.token }}
          script: |
@@ -203,7 +206,7 @@ jobs:
            //   });
            // }
      - name: Apply too-many-prs label
-        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+        uses: actions/github-script@v8
        with:
          github-token: ${{ steps.app-token.outputs.token || steps.app-token-fallback.outputs.token }}
          script: |
@@ -381,20 +384,20 @@ jobs:
      pull-requests: write
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
-      - uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
+      - uses: actions/create-github-app-token@v2
        id: app-token
        continue-on-error: true
        with:
          app-id: "2729701"
          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
-      - uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
+      - uses: actions/create-github-app-token@v2
        id: app-token-fallback
        if: steps.app-token.outcome == 'failure'
        with:
          app-id: "2971289"
          private-key: ${{ secrets.GH_APP_PRIVATE_KEY_FALLBACK }}
      - name: Backfill PR labels
-        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+        uses: actions/github-script@v8
        with:
          github-token: ${{ steps.app-token.outputs.token || steps.app-token-fallback.outputs.token }}
          script: |
@@ -629,20 +632,20 @@ jobs:
      issues: write
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
-      - uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
+      - uses: actions/create-github-app-token@v2
        id: app-token
        continue-on-error: true
        with:
          app-id: "2729701"
          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
-      - uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
+      - uses: actions/create-github-app-token@v2
        id: app-token-fallback
        if: steps.app-token.outcome == 'failure'
        with:
          app-id: "2971289"
          private-key: ${{ secrets.GH_APP_PRIVATE_KEY_FALLBACK }}
      - name: Apply maintainer or trusted-contributor label
-        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+        uses: actions/github-script@v8
        with:
          github-token: ${{ steps.app-token.outputs.token || steps.app-token-fallback.outputs.token }}
          script: |
@@ -10,6 +10,7 @@ concurrency:
  cancel-in-progress: false

 env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
  NODE_VERSION: "24.x"
  PNPM_VERSION: "10.23.0"

@@ -22,7 +23,7 @@ jobs:
      id-token: write
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          fetch-depth: 0

@@ -17,17 +17,20 @@ concurrency:
  group: sandbox-common-smoke-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
 jobs:
  sandbox-common-smoke:
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
        with:
          submodules: false

      - name: Set up Docker Builder
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4

      - name: Build minimal sandbox base (USER sandbox)
        shell: bash
@@ -5,6 +5,9 @@ on:
    - cron: "17 3 * * *"
  workflow_dispatch:

+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
 permissions: {}

 jobs:
@@ -14,13 +17,13 @@ jobs:
      pull-requests: write
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
-      - uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
+      - uses: actions/create-github-app-token@v2
        id: app-token
        continue-on-error: true
        with:
          app-id: "2729701"
          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
-      - uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
+      - uses: actions/create-github-app-token@v2
        id: app-token-fallback
        continue-on-error: true
        with:
@@ -29,7 +32,7 @@ jobs:
      - name: Mark stale issues and pull requests (primary)
        id: stale-primary
        continue-on-error: true
-        uses: actions/stale@v9
+        uses: actions/stale@v10
        with:
          repo-token: ${{ steps.app-token.outputs.token || steps.app-token-fallback.outputs.token }}
          days-before-issue-stale: 7
@@ -62,7 +65,7 @@ jobs:
      - name: Check stale state cache
        id: stale-state
        if: always()
-        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+        uses: actions/github-script@v8
        with:
          github-token: ${{ steps.app-token-fallback.outputs.token || steps.app-token.outputs.token }}
          script: |
@@ -85,7 +88,7 @@ jobs:
            }
      - name: Mark stale issues and pull requests (fallback)
        if: (steps.stale-primary.outcome == 'failure' || steps.stale-state.outputs.has_state == 'true') && steps.app-token-fallback.outputs.token != ''
-        uses: actions/stale@v9
+        uses: actions/stale@v10
        with:
          repo-token: ${{ steps.app-token-fallback.outputs.token }}
          days-before-issue-stale: 7
@@ -121,13 +124,13 @@ jobs:
      issues: write
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
-      - uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
+      - uses: actions/create-github-app-token@v2
        id: app-token
        with:
          app-id: "2729701"
          private-key: ${{ secrets.GH_APP_PRIVATE_KEY }}
      - name: Lock closed issues after 48h of no comments
-        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+        uses: actions/github-script@v8
        with:
          github-token: ${{ steps.app-token.outputs.token }}
          script: |
@@ -9,12 +9,15 @@ concurrency:
  group: workflow-sanity-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
 jobs:
  no-tabs:
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Fail on tabs in workflow files
        run: |
@@ -45,7 +48,7 @@ jobs:
    runs-on: blacksmith-16vcpu-ubuntu-2404
    steps:
      - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6

      - name: Install actionlint
        shell: bash
@@ -1,6 +1,7 @@
 node_modules
 **/node_modules/
 .env
+docker-compose.override.yml
 docker-compose.extra.yml
 dist
 pnpm-lock.yaml
@@ -128,6 +129,7 @@ docs/superpowers/specs/2026-03-10-collapsed-side-nav-design.md
 .gitignore
 test/config-form.analyze.telegram.test.ts
 ui/src/ui/theme-variants.browser.test.ts
-ui/src/ui/__screenshots__/navigation.browser.test.ts/control-UI-routing-auto-scrolls-chat-history-to-the-latest-message-1.png
-ui/src/ui/__screenshots__/navigation.browser.test.ts/control-UI-routing-auto-scrolls-chat-history-to-the-latest-message-1.png
-ui/src/ui/__screenshots__/navigation.browser.test.ts/control-UI-routing-auto-scrolls-chat-history-to-the-latest-message-1.png
+ui/src/ui/__screenshots__
+ui/src/ui/views/__screenshots__
+ui/.vitest-attachments
+docs/superpowers
@@ -0,0 +1,16 @@
+{
+  "gitignore": true,
+  "noSymlinks": true,
+  "ignore": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "dist/**",
+    "**/.git/**",
+    "**/coverage/**",
+    "**/build/**",
+    "**/.build/**",
+    "**/.artifacts/**",
+    "docs/zh-CN/**",
+    "**/CHANGELOG.md"
+  ]
+}
@@ -132,6 +132,7 @@
 - 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.
+- For targeted/local debugging, keep using the wrapper: `pnpm test -- <path-or-filter> [vitest args...]` (for example `pnpm test -- src/commands/onboard-search.test.ts -t "shows registered plugin providers"`); do not default to raw `pnpm vitest run ...` because it bypasses wrapper config/profile/pool routing.
 - Do not set test workers above 16; tried already.
 - If local Vitest runs cause memory pressure (common on non-Mac-Studio hosts), use `OPENCLAW_TEST_PROFILE=low OPENCLAW_TEST_SERIAL_GATEWAY=1 pnpm test` for land/gate runs.
 - Live tests (real keys): `CLAWDBOT_LIVE_TEST=1 pnpm test:live` (OpenClaw-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`.
@@ -201,6 +202,42 @@
 ## Agent-Specific Notes

 - Vocabulary: "makeup" = "mac app".
+- Parallels macOS retests: use the snapshot most closely named like `macOS 26.3.1 fresh` when the user asks for a clean/fresh macOS rerun; avoid older Tahoe snapshots unless explicitly requested.
+- Parallels macOS smoke playbook:
+  - `prlctl exec` is fine for deterministic repo commands, but it can misrepresent interactive shell behavior (`PATH`, `HOME`, `curl | bash`, shebang resolution). For installer parity or shell-sensitive repros, prefer the guest Terminal or `prlctl enter`.
+  - Fresh Tahoe snapshot current reality: `brew` exists, `node` may not be on `PATH` in noninteractive guest exec. Use absolute `/opt/homebrew/bin/node` for repo/CLI runs when needed.
+  - Preferred automation entrypoint: `pnpm test:parallels:macos`. It restores the snapshot most closely matching `macOS 26.3.1 fresh`, serves the current `main` tarball from the host, then runs fresh-install and latest-release-to-main smoke lanes.
+  - Gateway verification in smoke runs should use `openclaw gateway status --deep --require-rpc`, not plain `--deep`, so probe failures go non-zero.
+  - Latest-release pre-upgrade diagnostics still need compatibility fallback: stable `2026.3.12` does not know `--require-rpc`, so precheck status dumps should fall back to plain `gateway status --deep` until the guest is upgraded.
+  - Harness output: pass `--json` for machine-readable summary; per-phase logs land under `/tmp/openclaw-parallels-smoke.*`.
+  - All-OS parallel runs should share the host `dist` build via `/tmp/openclaw-parallels-build.lock` instead of rebuilding three times.
+  - Current expected outcome on latest stable pre-upgrade: `precheck=latest-ref-fail` is normal on `2026.3.12`; treat it as a baseline signal, not a regression, unless the post-upgrade `main` lane also fails.
+  - Fresh host-served tgz install: restore fresh snapshot, install tgz as guest root with `HOME=/var/root`, then run onboarding as the desktop user via `prlctl exec --current-user`.
+  - For `openclaw onboard --non-interactive --secret-input-mode ref --install-daemon`, expect env-backed auth-profile refs (for example `OPENAI_API_KEY`) to be copied into the service env at install time; this path was fixed and should stay green.
+  - Don’t run local + gateway agent turns in parallel on the same fresh workspace/session; they can collide on the session lock. Run sequentially.
+  - Root-installed tarball smoke on Tahoe can still log plugin blocks for world-writable `extensions/*` under `/opt/homebrew/lib/node_modules/openclaw`; treat that as separate from onboarding/gateway health unless the task is plugin loading.
+- Parallels Windows smoke playbook:
+  - Preferred automation entrypoint: `pnpm test:parallels:windows`. It restores the snapshot most closely matching `pre-openclaw-native-e2e-2026-03-12`, serves the current `main` tarball from the host, then runs fresh-install and latest-release-to-main smoke lanes.
+  - Gateway verification in smoke runs should use `openclaw gateway status --deep --require-rpc`, not plain `--deep`, so probe failures go non-zero.
+  - Latest-release pre-upgrade diagnostics still need compatibility fallback: stable `2026.3.12` does not know `--require-rpc`, so precheck status dumps should fall back to plain `gateway status --deep` until the guest is upgraded.
+  - Always use `prlctl exec --current-user` for Windows guest runs; plain `prlctl exec` lands in `NT AUTHORITY\SYSTEM` and does not match the real desktop-user install path.
+  - Prefer explicit `npm.cmd` / `openclaw.cmd`. Bare `npm` / `openclaw` in PowerShell can hit the `.ps1` shim and fail under restrictive execution policy.
+  - Use PowerShell only as the transport (`powershell.exe -NoProfile -ExecutionPolicy Bypass`) and call the `.cmd` shims explicitly from inside it.
+  - Harness output: pass `--json` for machine-readable summary; per-phase logs land under `/tmp/openclaw-parallels-windows.*`.
+  - Current expected outcome on latest stable pre-upgrade: `precheck=latest-ref-fail` is normal on `2026.3.12`; treat it as a baseline signal, not a regression, unless the post-upgrade `main` lane also fails.
+  - Keep Windows onboarding/status text ASCII-clean in logs. Fancy punctuation in banners shows up as mojibake through the current guest PowerShell capture path.
+- Parallels Linux smoke playbook:
+  - Preferred automation entrypoint: `pnpm test:parallels:linux`. It restores the snapshot most closely matching `fresh` on `Ubuntu 24.04.3 ARM64`, serves the current `main` tarball from the host, then runs fresh-install and latest-release-to-main smoke lanes.
+  - Use plain `prlctl exec` on this snapshot. `--current-user` is not the right transport there.
+  - Fresh snapshot reality: `curl` is missing and `apt-get update` can fail on clock skew. Bootstrap with `apt-get -o Acquire::Check-Date=false update` and install `curl ca-certificates` before testing installer paths.
+  - Fresh `main` tgz smoke on Linux still needs the latest-release installer first, because this snapshot has no Node/npm before bootstrap. The harness does stable bootstrap first, then overlays current `main`.
+  - This snapshot does not have a usable `systemd --user` session. Treat managed daemon install as unsupported here; use `--skip-health`, then verify with direct `openclaw gateway run --bind loopback --port 18789 --force`.
+  - Env-backed auth refs are still fine, but any direct shell launch (`openclaw gateway run`, `openclaw agent --local`, Linux `gateway status --deep` against that direct run) must inherit the referenced env vars in the same shell.
+  - `prlctl exec` reaps detached Linux child processes on this snapshot, so a background `openclaw gateway run` launched from automation is not a trustworthy smoke path. The harness verifies installer + `agent --local`; do direct gateway checks only from an interactive guest shell when needed.
+  - When you do run Linux gateway checks manually from an interactive guest shell, use `openclaw gateway status --deep --require-rpc` so an RPC miss is a hard failure.
+  - Prefer direct argv guest commands for fetch/install steps (`curl`, `npm install -g`, `openclaw ...`) over nested `bash -lc` quoting; Linux guest quoting through Parallels was the flaky part.
+  - Harness output: pass `--json` for machine-readable summary; per-phase logs land under `/tmp/openclaw-parallels-linux.*`.
+  - Current expected outcome on Linux smoke: fresh + upgrade should pass installer and `agent --local`; gateway remains `skipped-no-detached-linux-gateway` on this snapshot and should not be treated as a regression by itself.
 - Never edit `node_modules` (global/Homebrew/npm/git installs too). Updates overwrite. Skill notes go in `tools.md` or `AGENTS.md`.
 - When adding a new `AGENTS.md` anywhere in the repo, also add a `CLAUDE.md` symlink pointing to it (example: `ln -s AGENTS.md CLAUDE.md`).
 - Signal: "update fly" => `fly ssh console -a flawd-bot -C "bash -lc 'cd /data/clawd/openclaw && git pull --rebase origin main'"` then `fly machines restart e825232f34d058 -a flawd-bot`.
@@ -4,6 +4,68 @@ Docs: https://docs.openclaw.ai

 ## Unreleased

+### Changes
+
+- Android/chat settings: redesign the chat settings sheet with grouped device and media sections, refresh the Connect and Voice tabs, and tighten the chat composer/session header for a denser mobile layout. (#44894) Thanks @obviyus.
+- iOS/onboarding: add a first-run welcome pager before gateway setup, stop auto-opening the QR scanner, and show `/pair qr` instructions on the connect step. (#45054) Thanks @ngutman.
+- Browser/existing-session: add an official Chrome DevTools MCP attach mode for signed-in live Chrome sessions, with docs for `chrome://inspect/#remote-debugging` enablement and direct backlinks to Chrome’s own setup guides.
+- Browser/agents: add built-in `profile="user"` for the logged-in host browser and `profile="chrome-relay"` for the extension relay, so agent browser calls can prefer the real signed-in browser without the extra `browserSession` selector.
+- Browser/act automation: add batched actions, selector targeting, and delayed clicks for browser act requests with normalized batch dispatch. Thanks @vincentkoc.
+- Docker/timezone override: add `OPENCLAW_TZ` so `docker-setup.sh` can pin gateway and CLI containers to a chosen IANA timezone instead of inheriting the daemon default. (#34119) Thanks @Lanfei.
+- Dependencies/pi: bump `@mariozechner/pi-agent-core`, `@mariozechner/pi-ai`, `@mariozechner/pi-coding-agent`, and `@mariozechner/pi-tui` to `0.58.0`.
+
+### Fixes
+
+- Dashboard/chat UI: stop reloading full chat history on every live tool result in dashboard v2 so tool-heavy runs no longer trigger UI freeze/re-render storms while the final event still refreshes persisted history. (#45541) Thanks @BunsDev.
+- Ollama/reasoning visibility: stop promoting native `thinking` and `reasoning` fields into final assistant text so local reasoning models no longer leak internal thoughts in normal replies. (#45330) Thanks @xi7ang.
+- Android/onboarding QR scan: switch setup QR scanning to Google Code Scanner so onboarding uses a more reliable scanner instead of the legacy embedded ZXing flow. (#45021) Thanks @obviyus.
+- Browser/existing-session: harden driver validation and session lifecycle so transport errors trigger reconnects while tool-level errors preserve the session, and extract shared ARIA role sets to deduplicate Playwright and Chrome MCP snapshot paths. (#45682) Thanks @odysseus0.
+- Browser/existing-session: accept text-only `list_pages` and `new_page` responses from Chrome DevTools MCP so live-session tab discovery and new-tab open flows keep working when the server omits structured page metadata.
+- Control UI/insecure auth: preserve explicit shared token and password auth on plain-HTTP Control UI connects so LAN and reverse-proxy sessions no longer drop shared auth before the first WebSocket handshake. (#45088) Thanks @velvet-shark.
+- Gateway/session reset: preserve `lastAccountId` and `lastThreadId` across gateway session resets so replies keep routing back to the same account and thread after `/reset`. (#44773) Thanks @Lanfei.
+- macOS/onboarding: avoid self-restarting freshly bootstrapped launchd gateways and give new daemon installs longer to become healthy, so `openclaw onboard --install-daemon` no longer false-fails on slower Macs and fresh VM snapshots.
+- Gateway/status: add `openclaw gateway status --require-rpc` and clearer Linux non-interactive daemon-install failure reporting so automation can fail hard on probe misses instead of treating a printed RPC error as green.
+- macOS/exec approvals: respect per-agent exec approval settings in the gateway prompter, including allowlist fallback when the native prompt cannot be shown, so gateway-triggered `system.run` requests follow configured policy instead of always prompting or denying unexpectedly. (#13707) Thanks @sliekens.
+- Telegram/media downloads: thread the same direct or proxy transport policy into SSRF-guarded file fetches so inbound attachments keep working when Telegram falls back between env-proxy and direct networking. (#44639) Thanks @obviyus.
+- Telegram/inbound media IPv4 fallback: retry SSRF-guarded Telegram file downloads once with the same IPv4 fallback policy as Bot API calls so fresh installs on IPv6-broken hosts no longer fail to download inbound images.
+- Windows/gateway install: bound `schtasks` calls and fall back to the Startup-folder login item when task creation hangs, so native `openclaw gateway install` fails fast instead of wedging forever on broken Scheduled Task setups.
+- Windows/gateway stop: resolve Startup-folder fallback listeners from the installed `gateway.cmd` port, so `openclaw gateway stop` now actually kills fallback-launched gateway processes before restart.
+- Windows/gateway status: reuse the installed service command environment when reading runtime status, so startup-fallback gateways keep reporting the configured port and running state in `gateway status --json` instead of falling back to `gateway port unknown`.
+- Windows/gateway auth: stop attaching device identity on local loopback shared-token and password gateway calls, so native Windows agent replies no longer log stale `device signature expired` fallback noise before succeeding.
+- Discord/gateway startup: treat plain-text and transient `/gateway/bot` metadata fetch failures as transient startup errors so Discord gateway boot no longer crashes on unhandled rejections. (#44397) Thanks @jalehman.
+- Slack/probe: keep `auth.test()` bot and team metadata mapping stable while simplifying the probe result path. (#44775) Thanks @Cafexss.
+- Dashboard/chat UI: render oversized plain-text replies as normal paragraphs instead of capped gray code blocks, so long desktop chat responses stay readable without tab-switching refreshes.
+- Dashboard/chat UI: restore the `chat-new-messages` class on the New messages scroll pill so the button uses its existing compact styling instead of rendering as a full-screen SVG overlay. (#44856) Thanks @Astro-Han.
+- Gateway/Control UI: restore the operator-only device-auth bypass and classify browser connect failures so origin and device-identity problems no longer show up as auth errors in the Control UI and web chat. (#45512) thanks @sallyom.
+- macOS/voice wake: stop crashing wake-word command extraction when speech segment ranges come from a different transcript instance.
+- Discord/allowlists: honor raw `guild_id` when hydrated guild objects are missing so allowlisted channels and threads like `#maintainers` no longer get false-dropped before channel allowlist checks.
+- macOS/runtime locator: require Node >=22.16.0 during macOS runtime discovery so the app no longer accepts Node versions that the main runtime guard rejects later. Thanks @sumleo.
+- Agents/custom providers: preserve blank API keys for loopback OpenAI-compatible custom providers by clearing the synthetic Authorization header at runtime, while keeping explicit apiKey and oauth/token config from silently downgrading into fake bearer auth. (#45631) Thanks @xinhuagu.
+- Models/google-vertex Gemini flash-lite normalization: apply existing bare-ID preview normalization to `google-vertex` model refs and provider configs so `google-vertex/gemini-3.1-flash-lite` resolves as `gemini-3.1-flash-lite-preview`. (#42435) thanks @scoootscooob.
+- iMessage/remote attachments: reject unsafe remote attachment paths before spawning SCP, so sender-controlled filenames can no longer inject shell metacharacters into remote media staging. Thanks @lintsinghua.
+- Telegram/webhook auth: validate the Telegram webhook secret before reading or parsing request bodies, so unauthenticated requests are rejected immediately instead of consuming up to 1 MB first. Thanks @space08.
+- Security/device pairing: make bootstrap setup codes single-use so pending device pairing requests cannot be silently replayed and widened to admin before approval. Thanks @tdjackey.
+- Security/external content: strip zero-width and soft-hyphen marker-splitting characters during boundary sanitization so spoofed `EXTERNAL_UNTRUSTED_CONTENT` markers fall back to the existing hardening path instead of bypassing marker normalization.
+- Security/exec approvals: unwrap more `pnpm` runtime forms during approval binding, including `pnpm --reporter ... exec` and direct `pnpm node` file runs, with matching regression coverage and docs updates.
+- Security/exec approvals: fail closed for Perl `-M` and `-I` approval flows so preload and load-path module resolution stays outside approval-backed runtime execution unless the operator uses a broader explicit trust path.
+- Security/exec approvals: recognize PowerShell `-File` and `-f` wrapper forms during inline-command extraction so approval and command-analysis paths treat file-based PowerShell launches like the existing `-Command` variants.
+- Security/exec approvals: unwrap `env` dispatch wrappers inside shell-segment allowlist resolution on macOS so `env FOO=bar /path/to/bin` resolves against the effective executable instead of the wrapper token.
+- Security/exec approvals: treat backslash-newline as shell line continuation during macOS shell-chain parsing so line-continued `$(` substitutions fail closed instead of slipping past command-substitution checks.
+- Security/exec approvals: bind macOS skill auto-allow trust to both executable name and resolved path so same-basename binaries no longer inherit trust from unrelated skill bins.
+- Build/plugin-sdk bundling: bundle plugin-sdk subpath entries in one shared build pass so published packages stop duplicating shared chunks and avoid the recent plugin-sdk memory blow-up. (#45426) Thanks @TarasShyn.
+- Cron/isolated sessions: route nested cron-triggered embedded runner work onto the nested lane so isolated cron jobs no longer deadlock when compaction or other queued inner work runs. Thanks @vincentkoc.
+- Agents/OpenAI-compatible compat overrides: respect explicit user `models[].compat` opt-ins for non-native `openai-completions` endpoints so usage-in-streaming capability overrides no longer get forced off when the endpoint actually supports them. (#44432) Thanks @cheapestinference.
+- Agents/Azure OpenAI startup prompts: rephrase the built-in `/new`, `/reset`, and post-compaction startup instruction so Azure OpenAI deployments no longer hit HTTP 400 false positives from the content filter. (#43403) Thanks @xingsy97.
+- Agents/memory bootstrap: load only one root memory file, preferring `MEMORY.md` and using `memory.md` as a fallback, so case-insensitive Docker mounts no longer inject duplicate memory context. (#26054) Thanks @Lanfei.
+- Agents/compaction: compare post-compaction token sanity checks against full-session pre-compaction totals and skip the check when token estimation fails, so sessions with large bootstrap context keep real token counts instead of falling back to unknown. (#28347) thanks @efe-arv.
+- Agents/compaction: preserve safeguard compaction summary language continuity via default and configurable custom instructions so persona drift is reduced after auto-compaction. (#10456) Thanks @keepitmello.
+- Agents/tool warnings: distinguish gated core tools like `apply_patch` from plugin-only unknown entries in `tools.profile` warnings, so unavailable core tools now report current runtime/provider/model/config gating instead of suggesting a missing plugin.
+- Config/validation: accept documented `agents.list[].params` per-agent overrides in strict config validation so `openclaw config validate` no longer rejects runtime-supported `cacheRetention`, `temperature`, and `maxTokens` settings. (#41171) Thanks @atian8179.
+- Config/web fetch: restore runtime validation for documented `tools.web.fetch.readability` and `tools.web.fetch.firecrawl` settings so valid web fetch configs no longer fail with unrecognized-key errors. (#42583) Thanks @stim64045-spec.
+- Signal/config validation: add `channels.signal.groups` schema support so per-group `requireMention`, `tools`, and `toolsBySender` overrides no longer get rejected during config validation. (#27199) Thanks @unisone.
+- Config/discovery: accept `discovery.wideArea.domain` in strict config validation so unicast DNS-SD gateway configs no longer fail with an unrecognized-key error. (#35615) Thanks @ingyukoh.
+- Telegram/media errors: redact Telegram file URLs before building media fetch errors so failed inbound downloads do not leak bot tokens into logs. Thanks @space08.
+
 ## 2026.3.12

 ### Changes
@@ -15,6 +77,7 @@ Docs: https://docs.openclaw.ai
 - Docs/Kubernetes: Add a starter K8s install path with raw manifests, Kind setup, and deployment docs. Thanks @sallyom @dzianisv @egkristi
 - Agents/subagents: add `sessions_yield` so orchestrators can end the current turn immediately, skip queued tool work, and carry a hidden follow-up payload into the next session turn. (#36537) thanks @jriff
 - Slack/agent replies: support `channelData.slack.blocks` in the shared reply delivery path so agents can send Block Kit messages through standard Slack outbound delivery. (#44592) Thanks @vincentkoc.
+- Slack/interactive replies: add opt-in Slack button and select reply directives behind `channels.slack.capabilities.interactiveReplies`, disabled by default unless explicitly enabled. (#44607) Thanks @vincentkoc.

 ### Fixes

@@ -71,13 +134,16 @@ Docs: https://docs.openclaw.ai
 - Gateway/session stores: regenerate the Swift push-test protocol models and align Windows native session-store realpath handling so protocol checks and sync session discovery stop drifting on Windows. (#44266) thanks @jalehman.
 - Context engine/session routing: forward optional `sessionKey` through context-engine lifecycle calls so plugins can see structured routing metadata during bootstrap, assembly, post-turn ingestion, and compaction. (#44157) thanks @jalehman.
 - Agents/failover: classify z.ai `network_error` stop reasons as retryable timeouts so provider connectivity failures trigger fallback instead of surfacing raw unhandled-stop-reason errors. (#43884) Thanks @hougangdev.
+- Config/Anthropic startup: inline Anthropic alias normalization during config load so gateway startup no longer crashes on dated Anthropic model refs like `anthropic/claude-sonnet-4-20250514`. (#45520) Thanks @BunsDev.
 - Memory/session sync: add mode-aware post-compaction session reindexing with `agents.defaults.compaction.postIndexSync` plus `agents.defaults.memorySearch.sync.sessions.postCompactionForce`, so compacted session memory can refresh immediately without forcing every deployment into synchronous reindexing. (#25561) thanks @rodrigouroz.
 - Telegram/model picker: make inline model button selections persist the chosen session model correctly, clear overrides when selecting the configured default, and include effective fallback models in `/models` button validation. (#40105) Thanks @avirweb.
 - Telegram/native command sync: suppress expected `BOT_COMMANDS_TOO_MUCH` retry error noise, add a final fallback summary log, and document the difference between command-menu overflow and real Telegram network failures.
 - Mattermost/reply media delivery: pass agent-scoped `mediaLocalRoots` through shared reply delivery so allowed local files upload correctly from button, slash-command, and model-picker replies. (#44021) Thanks @LyleLiu666.
 - Plugins/env-scoped roots: fix plugin discovery/load caches and provenance tracking so same-process `HOME`/`OPENCLAW_HOME` changes no longer reuse stale plugin state or misreport `~/...` plugins as untracked. (#44046) thanks @gumadeiras.
 - Gateway/session discovery: discover disk-only and retired ACP session stores under custom templated `session.store` roots so ACP reconciliation, session-id/session-label targeting, and run-id fallback keep working after restart. (#44176) thanks @gumadeiras.
+- Browser/existing-session: stop reporting fake CDP ports/URLs for live attached Chrome sessions, render `transport: chrome-mcp` in CLI/status output instead of `port: 0`, and keep timeout diagnostics transport-aware when no direct CDP URL exists.
 - Models/OpenRouter native ids: canonicalize native OpenRouter model keys across config writes, runtime lookups, fallback management, and `models list --plain`, and migrate legacy duplicated `openrouter/openrouter/...` config entries forward on write.
+- Feishu/event dedupe: keep early duplicate suppression aligned with the shared Feishu message-id contract and release the pre-queue dedupe marker after failed dispatch so retried events can recover instead of being dropped until the short TTL expires. (#43762) Thanks @yunweibang.
 - Gateway/hooks: bucket hook auth failures by forwarded client IP behind trusted proxies and warn when `hooks.allowedAgentIds` leaves hook routing unrestricted.
 - Agents/compaction: skip the post-compaction `cache-ttl` marker write when a compaction completed in the same attempt, preventing the next turn from immediately triggering a second tiny compaction. (#28548) thanks @MoerAI.
 - Native chat/macOS: add `/new`, `/reset`, and `/clear` reset triggers, keep shared main-session aliases aligned, and ignore stale model-selection completions so native chat state stays in sync across reset and fast model changes. (#10898) Thanks @Nachx639.
@@ -85,6 +151,11 @@ Docs: https://docs.openclaw.ai
 - Cron/doctor: stop flagging canonical `agentTurn` and `systemEvent` payload kinds as legacy cron storage, while still normalizing whitespace-padded and non-canonical variants. (#44012) Thanks @shuicici.
 - ACP/client final-message delivery: preserve terminal assistant text snapshots before resolving `end_turn`, so ACP clients no longer drop the last visible reply when the gateway sends the final message body on the terminal chat event. (#17615) Thanks @pjeby.
 - Telegram/Discord status reactions: show a temporary compacting reaction during auto-compaction pauses and restore thinking afterward so the bot no longer appears frozen while context is being compacted. (#35474) thanks @Cypherm.
+- Delivery/dedupe: trim completed direct-cron delivery cache correctly and keep mirrored transcript dedupe active even when transcript files contain malformed lines. (#44666) thanks @frankekn.
+- CLI/thinking help: add the missing `xhigh` level hints to `openclaw cron add`, `openclaw cron edit`, and `openclaw agent` so the help text matches the levels already accepted at runtime. (#44819) Thanks @kiki830621.
+- Agents/Anthropic replay: drop replayed assistant thinking blocks for native Anthropic and Bedrock Claude providers so persisted follow-up turns no longer fail on stored thinking blocks. (#44843) Thanks @jmcte.
+- Docs/Brave pricing: escape literal dollar signs in Brave Search cost text so the docs render the free credit and per-request pricing correctly. (#44989) Thanks @keelanfh.
+- Feishu/file uploads: preserve literal UTF-8 filenames in `im.file.create` so Chinese and other non-ASCII filenames no longer appear percent-encoded in chat. (#34262) Thanks @fabiaodemianyang and @KangShuaiFu.

 ## 2026.3.11

@@ -225,6 +296,7 @@ Docs: https://docs.openclaw.ai
 - Agents/failover: classify ZenMux quota-refresh `402` responses as `rate_limit` so model fallback retries continue instead of stopping on a temporary subscription window. (#43917) thanks @bwjoke.
 - Agents/failover: classify HTTP 422 malformed-request responses as `format` and recognize OpenRouter "requires more credits" billing errors so provider fallback triggers instead of surfacing raw errors. (#43823) thanks @jnMetaCode.
 - Memory/QMD Windows: fail closed when `qmd.cmd` or `mcporter.cmd` wrappers cannot be resolved to a direct entrypoint, so memory search no longer falls back to shell execution on Windows.
+- macOS/remote gateway: stop PortGuardian from killing Docker Desktop and other external listeners on the gateway port in remote mode, so containerized and tunneled gateway setups no longer lose their port-forward owner on app startup. (#6755) Thanks @teslamint.

 ## 2026.3.8

@@ -303,6 +375,7 @@ Docs: https://docs.openclaw.ai
 - Telegram/model picker: make inline model button selections persist the chosen session model correctly, clear overrides when selecting the configured default, and include effective fallback models in `/models` button validation. (#40105) Thanks @avirweb.
 - Agents/embedded runner: carry provider-observed overflow token counts into compaction so overflow retries and diagnostics use the rejected live prompt size instead of only transcript estimates. (#40357) thanks @rabsef-bicrym.
 - Agents/compaction transcript updates: emit a transcript-update event immediately after successful embedded compaction so downstream listeners observe the post-compact transcript without waiting for a later write. (#25558) thanks @rodrigouroz.
+- Agents/sessions_spawn: use the target agent workspace for cross-agent spawned runs instead of inheriting the caller workspace, so child sessions load the correct workspace-scoped instructions and persona files. (#40176) Thanks @moshehbenavraham.

 ## 2026.3.7

@@ -3227,7 +3300,7 @@ Docs: https://docs.openclaw.ai
 - Agents: add CLI log hint to "agent failed before reply" messages. (#1550) Thanks @sweepies.
 - Agents: warn and ignore tool allowlists that only reference unknown or unloaded plugin tools. (#1566)
 - Agents: treat plugin-only tool allowlists as opt-ins; keep core tools enabled. (#1467)
- Agents: honor enqueue overrides for embedded runs to avoid queue deadlocks in tests. (commit 084002998)
+- Agents: honor enqueue overrides for embedded runs to avoid queue deadlocks in tests. (#45459) Thanks @LyttonFeng and @vincentkoc.
 - Slack: honor open groupPolicy for unlisted channels in message + slash gating. (#1563) Thanks @itsjaydesu.
 - Discord: limit autoThread mention bypass to bot-owned threads; keep ack reactions mention-gated. (#1511) Thanks @pvoo.
 - Discord: retry rate-limited allowlist resolution + command deploy to avoid gateway crashes. (commit f70ac0c7c)
@@ -23,7 +23,7 @@ Welcome to the lobster tank! 🦞
 - **Jos** - Telegram, API, Nix mode
  - GitHub: [@joshp123](https://github.com/joshp123) · X: [@jjpcodes](https://x.com/jjpcodes)

- **Ayaan Zaidi** - Telegram subsystem, iOS app
+- **Ayaan Zaidi** - Telegram subsystem, Android app
  - GitHub: [@obviyus](https://github.com/obviyus) · X: [@0bviyus](https://x.com/0bviyus)

 - **Tyler Yust** - Agents/subagents, cron, BlueBubbles, macOS app
@@ -132,6 +132,7 @@ WORKDIR /app
 RUN --mount=type=cache,id=openclaw-bookworm-apt-cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,id=openclaw-bookworm-apt-lists,target=/var/lib/apt,sharing=locked \
    apt-get update && \
+    DEBIAN_FRONTEND=noninteractive apt-get upgrade -y --no-install-recommends && \
    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
      procps hostname curl git openssl

@@ -7,6 +7,7 @@ ENV DEBIAN_FRONTEND=noninteractive
 RUN --mount=type=cache,id=openclaw-sandbox-bookworm-apt-cache,target=/var/cache/apt,sharing=locked \
  --mount=type=cache,id=openclaw-sandbox-bookworm-apt-lists,target=/var/lib/apt,sharing=locked \
  apt-get update \
+  && apt-get upgrade -y --no-install-recommends \
  && apt-get install -y --no-install-recommends \
    bash \
    ca-certificates \
@@ -7,6 +7,7 @@ ENV DEBIAN_FRONTEND=noninteractive
 RUN --mount=type=cache,id=openclaw-sandbox-bookworm-apt-cache,target=/var/cache/apt,sharing=locked \
  --mount=type=cache,id=openclaw-sandbox-bookworm-apt-lists,target=/var/lib/apt,sharing=locked \
  apt-get update \
+  && apt-get upgrade -y --no-install-recommends \
  && apt-get install -y --no-install-recommends \
    bash \
    ca-certificates \
@@ -24,6 +24,7 @@ ENV PATH=${BUN_INSTALL_DIR}/bin:${BREW_INSTALL_DIR}/bin:${BREW_INSTALL_DIR}/sbin
 RUN --mount=type=cache,id=openclaw-sandbox-common-apt-cache,target=/var/cache/apt,sharing=locked \
  --mount=type=cache,id=openclaw-sandbox-common-apt-lists,target=/var/lib/apt,sharing=locked \
  apt-get update \
+  && apt-get upgrade -y --no-install-recommends \
  && apt-get install -y --no-install-recommends ${PACKAGES}

 RUN if [ "${INSTALL_PNPM}" = "1" ]; then npm install -g pnpm; fi
@@ -101,25 +101,19 @@ public enum WakeWordGate {
    }

    public static func commandText(
-        transcript: String,
+        transcript _: String,
        segments: [WakeWordSegment],
        triggerEndTime: TimeInterval)
    -> String {
        let threshold = triggerEndTime + 0.001
+        var commandWords: [String] = []
+        commandWords.reserveCapacity(segments.count)
        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 normalized = normalizeToken(segment.text)
+            if normalized.isEmpty { continue }
+            commandWords.append(segment.text)
        }
-
-        let text = segments
-            .filter { $0.start >= threshold && !normalizeToken($0.text).isEmpty }
-            .map(\.text)
-            .joined(separator: " ")
-        return text.trimmingCharacters(in: Self.whitespaceAndPunctuation)
+        return commandWords.joined(separator: " ").trimmingCharacters(in: Self.whitespaceAndPunctuation)
    }

    public static func matchesTextOnly(text: String, triggers: [String]) -> Bool {
@@ -46,6 +46,25 @@ import Testing
        let match = WakeWordGate.match(transcript: transcript, segments: segments, config: config)
        #expect(match?.command == "do it")
    }
+
+    @Test func commandTextHandlesForeignRangeIndices() {
+        let transcript = "hey clawd do thing"
+        let other = "do thing"
+        let foreignRange = other.range(of: "do")
+        let segments = [
+            WakeWordSegment(text: "hey", start: 0.0, duration: 0.1, range: transcript.range(of: "hey")),
+            WakeWordSegment(text: "clawd", start: 0.2, duration: 0.1, range: transcript.range(of: "clawd")),
+            WakeWordSegment(text: "do", start: 0.9, duration: 0.1, range: foreignRange),
+            WakeWordSegment(text: "thing", start: 1.1, duration: 0.1, range: nil),
+        ]
+
+        let command = WakeWordGate.commandText(
+            transcript: transcript,
+            segments: segments,
+            triggerEndTime: 0.3)
+
+        #expect(command == "do thing")
+    }
 }

 private func makeSegments(
@@ -30,8 +30,12 @@ cd apps/android
 ./gradlew :app:assembleDebug
 ./gradlew :app:installDebug
 ./gradlew :app:testDebugUnitTest
+cd ../..
+bun run android:bundle:release
 ```

+`bun run android:bundle:release` auto-bumps Android `versionName`/`versionCode` in `apps/android/app/build.gradle.kts`, then builds a signed release `.aab`.
+
 ## Kotlin Lint + Format

 ```bash
@@ -1,5 +1,7 @@
 import com.android.build.api.variant.impl.VariantOutputImpl

+val dnsjavaInetAddressResolverService = "META-INF/services/java.net.spi.InetAddressResolverProvider"
+
 val androidStoreFile = providers.gradleProperty("OPENCLAW_ANDROID_STORE_FILE").orNull?.takeIf { it.isNotBlank() }
 val androidStorePassword = providers.gradleProperty("OPENCLAW_ANDROID_STORE_PASSWORD").orNull?.takeIf { it.isNotBlank() }
 val androidKeyAlias = providers.gradleProperty("OPENCLAW_ANDROID_KEY_ALIAS").orNull?.takeIf { it.isNotBlank() }
@@ -63,8 +65,8 @@ android {
        applicationId = "ai.openclaw.app"
        minSdk = 31
        targetSdk = 36
-        versionCode = 202603120
-        versionName = "2026.3.12"
+        versionCode = 2026031400
+        versionName = "2026.3.14"
        ndk {
            // Support all major ABIs — native libs are tiny (~47 KB per ABI)
            abiFilters += listOf("armeabi-v7a", "arm64-v8a", "x86", "x86_64")
@@ -78,6 +80,9 @@ android {
            }
            isMinifyEnabled = true
            isShrinkResources = true
+            ndk {
+                debugSymbolLevel = "SYMBOL_TABLE"
+            }
            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
        }
        debug {
@@ -104,6 +109,10 @@ android {
                    "/META-INF/LICENSE*.txt",
                    "DebugProbesKt.bin",
                    "kotlin-tooling-metadata.json",
+                    "org/bouncycastle/pqc/crypto/picnic/lowmcL1.bin.properties",
+                    "org/bouncycastle/pqc/crypto/picnic/lowmcL3.bin.properties",
+                    "org/bouncycastle/pqc/crypto/picnic/lowmcL5.bin.properties",
+                    "org/bouncycastle/x509/CertPathReviewerMessages*.properties",
                )
        }
    }
@@ -168,7 +177,6 @@ dependencies {
    // material-icons-extended pulled in full icon set (~20 MB DEX). Only ~18 icons used.
    // R8 will tree-shake unused icons when minify is enabled on release builds.
    implementation("androidx.compose.material:material-icons-extended")
-    implementation("androidx.navigation:navigation-compose:2.9.7")

    debugImplementation("androidx.compose.ui:ui-tooling")

@@ -193,8 +201,7 @@ dependencies {
    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")
-    implementation("com.journeyapps:zxing-android-embedded:4.3.0")
+    implementation("com.google.android.gms:play-services-code-scanner:16.1.0")

    // Unicast DNS-SD (Wide-Area Bonjour) for tailnet discovery domains.
    implementation("dnsjava:dnsjava:3.6.4")
@@ -211,3 +218,45 @@ dependencies {
 tasks.withType<Test>().configureEach {
    useJUnitPlatform()
 }
+
+val stripReleaseDnsjavaServiceDescriptor =
+    tasks.register("stripReleaseDnsjavaServiceDescriptor") {
+        val mergedJar =
+            layout.buildDirectory.file(
+                "intermediates/merged_java_res/release/mergeReleaseJavaResource/base.jar",
+            )
+
+        inputs.file(mergedJar)
+        outputs.file(mergedJar)
+
+        doLast {
+            val jarFile = mergedJar.get().asFile
+            if (!jarFile.exists()) {
+                return@doLast
+            }
+
+            val unpackDir = temporaryDir.resolve("merged-java-res")
+            delete(unpackDir)
+            copy {
+                from(zipTree(jarFile))
+                into(unpackDir)
+                exclude(dnsjavaInetAddressResolverService)
+            }
+            delete(jarFile)
+            ant.invokeMethod(
+                "zip",
+                mapOf(
+                    "destfile" to jarFile.absolutePath,
+                    "basedir" to unpackDir.absolutePath,
+                ),
+            )
+        }
+    }
+
+tasks.matching { it.name == "stripReleaseDnsjavaServiceDescriptor" }.configureEach {
+    dependsOn("mergeReleaseJavaResource")
+}
+
+tasks.matching { it.name == "minifyReleaseWithR8" }.configureEach {
+    dependsOn(stripReleaseDnsjavaServiceDescriptor)
+}
@@ -1,26 +1,6 @@
-# ── App classes ───────────────────────────────────────────────────
-keep class ai.openclaw.app.** { *; }
-
-# ── Bouncy Castle ─────────────────────────────────────────────────
-keep class org.bouncycastle.** { *; }
 -dontwarn org.bouncycastle.**
-
-# ── CameraX ───────────────────────────────────────────────────────
-keep class androidx.camera.** { *; }
-
-# ── kotlinx.serialization ────────────────────────────────────────
-keep class kotlinx.serialization.** { *; }
-keepclassmembers class * {
-    @kotlinx.serialization.Serializable *;
-}
-keepattributes *Annotation*, InnerClasses
-
-# ── OkHttp ────────────────────────────────────────────────────────
 -dontwarn okhttp3.**
 -dontwarn okio.**
-keep class okhttp3.internal.platform.** { *; }
-
-# ── Misc suppressions ────────────────────────────────────────────
 -dontwarn com.sun.jna.**
 -dontwarn javax.naming.**
 -dontwarn lombok.Generated
@@ -8,6 +8,7 @@ import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.PaddingValues
 import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
 import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.height
 import androidx.compose.foundation.layout.padding
@@ -18,8 +19,11 @@ import androidx.compose.foundation.shape.RoundedCornerShape
 import androidx.compose.foundation.text.KeyboardOptions
 import androidx.compose.foundation.verticalScroll
 import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.filled.Cloud
 import androidx.compose.material.icons.filled.ExpandLess
 import androidx.compose.material.icons.filled.ExpandMore
+import androidx.compose.material.icons.filled.Link
+import androidx.compose.material.icons.filled.PowerSettingsNew
 import androidx.compose.material3.AlertDialog
 import androidx.compose.material3.Button
 import androidx.compose.material3.ButtonDefaults
@@ -128,96 +132,142 @@ fun ConnectTabScreen(viewModel: MainViewModel) {
    verticalArrangement = Arrangement.spacedBy(14.dp),
  ) {
    Column(verticalArrangement = Arrangement.spacedBy(6.dp)) {
-      Text("Connection Control", style = mobileCaption1.copy(fontWeight = FontWeight.Bold), color = mobileAccent)
      Text("Gateway Connection", style = mobileTitle1, color = mobileText)
      Text(
-        "One primary action. Open advanced controls only when needed.",
+        if (isConnected) "Your gateway is active and ready." else "Connect to your gateway to get started.",
        style = mobileCallout,
        color = mobileTextSecondary,
      )
    }

+    // Status cards in a unified card group
    Surface(
      modifier = Modifier.fillMaxWidth(),
      shape = RoundedCornerShape(14.dp),
-      color = mobileSurface,
+      color = Color.White,
      border = BorderStroke(1.dp, mobileBorder),
    ) {
-      Column(modifier = Modifier.padding(horizontal = 14.dp, vertical = 12.dp), verticalArrangement = Arrangement.spacedBy(4.dp)) {
-        Text("Active endpoint", style = mobileCaption1.copy(fontWeight = FontWeight.SemiBold), color = mobileTextSecondary)
-        Text(activeEndpoint, style = mobileBody.copy(fontFamily = FontFamily.Monospace), color = mobileText)
+      Column {
+        Row(
+          modifier = Modifier.fillMaxWidth().padding(horizontal = 14.dp, vertical = 12.dp),
+          verticalAlignment = Alignment.CenterVertically,
+          horizontalArrangement = Arrangement.spacedBy(12.dp),
+        ) {
+          Surface(
+            shape = RoundedCornerShape(10.dp),
+            color = mobileAccentSoft,
+          ) {
+            Icon(
+              imageVector = Icons.Default.Link,
+              contentDescription = null,
+              modifier = Modifier.padding(8.dp).size(18.dp),
+              tint = mobileAccent,
+            )
+          }
+          Column(verticalArrangement = Arrangement.spacedBy(2.dp)) {
+            Text("Endpoint", style = mobileCaption1.copy(fontWeight = FontWeight.SemiBold), color = mobileTextSecondary)
+            Text(activeEndpoint, style = mobileBody.copy(fontFamily = FontFamily.Monospace), color = mobileText)
+          }
+        }
+        HorizontalDivider(color = mobileBorder)
+        Row(
+          modifier = Modifier.fillMaxWidth().padding(horizontal = 14.dp, vertical = 12.dp),
+          verticalAlignment = Alignment.CenterVertically,
+          horizontalArrangement = Arrangement.spacedBy(12.dp),
+        ) {
+          Surface(
+            shape = RoundedCornerShape(10.dp),
+            color = if (isConnected) mobileSuccessSoft else mobileSurface,
+          ) {
+            Icon(
+              imageVector = Icons.Default.Cloud,
+              contentDescription = null,
+              modifier = Modifier.padding(8.dp).size(18.dp),
+              tint = if (isConnected) mobileSuccess else mobileTextTertiary,
+            )
+          }
+          Column(verticalArrangement = Arrangement.spacedBy(2.dp)) {
+            Text("Status", style = mobileCaption1.copy(fontWeight = FontWeight.SemiBold), color = mobileTextSecondary)
+            Text(statusText, style = mobileBody, color = if (isConnected) mobileSuccess else mobileText)
+          }
+        }
      }
    }

-    Surface(
-      modifier = Modifier.fillMaxWidth(),
-      shape = RoundedCornerShape(14.dp),
-      color = mobileSurface,
-      border = BorderStroke(1.dp, mobileBorder),
-    ) {
-      Column(modifier = Modifier.padding(horizontal = 14.dp, vertical = 12.dp), verticalArrangement = Arrangement.spacedBy(4.dp)) {
-        Text("Gateway state", style = mobileCaption1.copy(fontWeight = FontWeight.SemiBold), color = mobileTextSecondary)
-        Text(statusText, style = mobileBody, color = mobileText)
-      }
-    }
-
-    Button(
-      onClick = {
-        if (isConnected) {
+    if (isConnected) {
+      // Outlined secondary button when connected — don't scream "danger"
+      Button(
+        onClick = {
          viewModel.disconnect()
          validationText = null
-          return@Button
-        }
-        if (statusText.contains("operator offline", ignoreCase = true)) {
+        },
+        modifier = Modifier.fillMaxWidth().height(48.dp),
+        shape = RoundedCornerShape(14.dp),
+        colors =
+          ButtonDefaults.buttonColors(
+            containerColor = Color.White,
+            contentColor = mobileDanger,
+          ),
+        border = BorderStroke(1.dp, mobileDanger.copy(alpha = 0.4f)),
+      ) {
+        Icon(Icons.Default.PowerSettingsNew, contentDescription = null, modifier = Modifier.size(18.dp))
+        Spacer(modifier = Modifier.width(8.dp))
+        Text("Disconnect", style = mobileHeadline.copy(fontWeight = FontWeight.SemiBold))
+      }
+    } else {
+      Button(
+        onClick = {
+          if (statusText.contains("operator offline", ignoreCase = true)) {
+            validationText = null
+            viewModel.refreshGatewayConnection()
+            return@Button
+          }
+
+          val config =
+            resolveGatewayConnectConfig(
+              useSetupCode = inputMode == ConnectInputMode.SetupCode,
+              setupCode = setupCode,
+              manualHost = manualHostInput,
+              manualPort = manualPortInput,
+              manualTls = manualTlsInput,
+              fallbackToken = gatewayToken,
+              fallbackPassword = passwordInput,
+            )
+
+          if (config == null) {
+            validationText =
+              if (inputMode == ConnectInputMode.SetupCode) {
+                "Paste a valid setup code to connect."
+              } else {
+                "Enter a valid manual host and port to connect."
+              }
+            return@Button
+          }
+
          validationText = null
-          viewModel.refreshGatewayConnection()
-          return@Button
-        }
-
-        val config =
-          resolveGatewayConnectConfig(
-            useSetupCode = inputMode == ConnectInputMode.SetupCode,
-            setupCode = setupCode,
-            manualHost = manualHostInput,
-            manualPort = manualPortInput,
-            manualTls = manualTlsInput,
-            fallbackToken = gatewayToken,
-            fallbackPassword = passwordInput,
-          )
-
-        if (config == null) {
-          validationText =
-            if (inputMode == ConnectInputMode.SetupCode) {
-              "Paste a valid setup code to connect."
-            } else {
-              "Enter a valid manual host and port to connect."
-            }
-          return@Button
-        }
-
-        validationText = null
-        viewModel.setManualEnabled(true)
-        viewModel.setManualHost(config.host)
-        viewModel.setManualPort(config.port)
-        viewModel.setManualTls(config.tls)
-        viewModel.setGatewayBootstrapToken(config.bootstrapToken)
-        if (config.token.isNotBlank()) {
-          viewModel.setGatewayToken(config.token)
-        } else if (config.bootstrapToken.isNotBlank()) {
-          viewModel.setGatewayToken("")
-        }
-        viewModel.setGatewayPassword(config.password)
-        viewModel.connectManual()
-      },
-      modifier = Modifier.fillMaxWidth().height(52.dp),
-      shape = RoundedCornerShape(14.dp),
-      colors =
-        ButtonDefaults.buttonColors(
-          containerColor = if (isConnected) mobileDanger else mobileAccent,
-          contentColor = Color.White,
-        ),
-    ) {
-      Text(primaryLabel, style = mobileHeadline.copy(fontWeight = FontWeight.Bold))
+          viewModel.setManualEnabled(true)
+          viewModel.setManualHost(config.host)
+          viewModel.setManualPort(config.port)
+          viewModel.setManualTls(config.tls)
+          viewModel.setGatewayBootstrapToken(config.bootstrapToken)
+          if (config.token.isNotBlank()) {
+            viewModel.setGatewayToken(config.token)
+          } else if (config.bootstrapToken.isNotBlank()) {
+            viewModel.setGatewayToken("")
+          }
+          viewModel.setGatewayPassword(config.password)
+          viewModel.connectManual()
+        },
+        modifier = Modifier.fillMaxWidth().height(52.dp),
+        shape = RoundedCornerShape(14.dp),
+        colors =
+          ButtonDefaults.buttonColors(
+            containerColor = mobileAccent,
+            contentColor = Color.White,
+          ),
+      ) {
+        Text("Connect Gateway", style = mobileHeadline.copy(fontWeight = FontWeight.Bold))
+      }
    }

    Surface(
@@ -97,7 +97,7 @@ internal fun parseGatewayEndpoint(rawInput: String): GatewayEndpointConfig? {
      "wss", "https" -> true
      else -> true
    }
-  val port = uri.port.takeIf { it in 1..65535 } ?: 18789
+  val port = uri.port.takeIf { it in 1..65535 } ?: if (tls) 443 else 18789
  val displayUrl = "${if (tls) "https" else "http"}://$host:$port"

  return GatewayEndpointConfig(host = host, port = port, tls = tls, displayUrl = displayUrl)
@@ -57,8 +57,16 @@ import androidx.compose.material3.Text
 import androidx.compose.material3.TextButton
 import androidx.compose.material.icons.Icons
 import androidx.compose.material.icons.automirrored.filled.ArrowBack
+import androidx.compose.material.icons.filled.ChatBubble
+import androidx.compose.material.icons.filled.CheckCircle
+import androidx.compose.material.icons.filled.Cloud
 import androidx.compose.material.icons.filled.ExpandLess
 import androidx.compose.material.icons.filled.ExpandMore
+import androidx.compose.material.icons.filled.Link
+import androidx.compose.material.icons.filled.Security
+import androidx.compose.material.icons.filled.Tune
+import androidx.compose.material.icons.filled.Wifi
+import androidx.compose.ui.graphics.vector.ImageVector
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.DisposableEffect
 import androidx.compose.runtime.collectAsState
@@ -68,6 +76,7 @@ import androidx.compose.runtime.remember
 import androidx.compose.runtime.saveable.rememberSaveable
 import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
+import androidx.compose.ui.draw.clip
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.graphics.Brush
 import androidx.compose.ui.graphics.Color
@@ -87,8 +96,9 @@ import ai.openclaw.app.LocationMode
 import ai.openclaw.app.MainViewModel
 import ai.openclaw.app.R
 import ai.openclaw.app.node.DeviceNotificationListenerService
-import com.journeyapps.barcodescanner.ScanContract
-import com.journeyapps.barcodescanner.ScanOptions
+import com.google.mlkit.vision.barcode.common.Barcode
+import com.google.mlkit.vision.codescanner.GmsBarcodeScannerOptions
+import com.google.mlkit.vision.codescanner.GmsBarcodeScanning

 private enum class OnboardingStep(val index: Int, val label: String) {
  Welcome(1, "Welcome"),
@@ -232,6 +242,13 @@ fun OnboardingFlow(viewModel: MainViewModel, modifier: Modifier = Modifier) {
  var attemptedConnect by rememberSaveable { mutableStateOf(false) }

  val lifecycleOwner = LocalLifecycleOwner.current
+  val qrScannerOptions =
+    remember {
+      GmsBarcodeScannerOptions.Builder()
+        .setBarcodeFormats(Barcode.FORMAT_QR_CODE)
+        .build()
+    }
+  val qrScanner = remember(context, qrScannerOptions) { GmsBarcodeScanning.getClient(context, qrScannerOptions) }

  val smsAvailable =
    remember(context) {
@@ -451,23 +468,6 @@ fun OnboardingFlow(viewModel: MainViewModel, modifier: Modifier = Modifier) {
    onDispose { lifecycleOwner.lifecycle.removeObserver(observer) }
  }

-  val qrScanLauncher =
-    rememberLauncherForActivityResult(ScanContract()) { result ->
-      val contents = result.contents?.trim().orEmpty()
-      if (contents.isEmpty()) {
-        return@rememberLauncherForActivityResult
-      }
-      val scannedSetupCode = resolveScannedSetupCode(contents)
-      if (scannedSetupCode == null) {
-        gatewayError = "QR code did not contain a valid setup code."
-        return@rememberLauncherForActivityResult
-      }
-      setupCode = scannedSetupCode
-      gatewayInputMode = GatewayInputMode.SetupCode
-      gatewayError = null
-      attemptedConnect = false
-    }
-
  if (pendingTrust != null) {
    val prompt = pendingTrust!!
    AlertDialog(
@@ -513,25 +513,20 @@ fun OnboardingFlow(viewModel: MainViewModel, modifier: Modifier = Modifier) {
      ) {
        Column(
          modifier = Modifier.padding(top = 12.dp),
-          verticalArrangement = Arrangement.spacedBy(8.dp),
+          verticalArrangement = Arrangement.spacedBy(4.dp),
        ) {
          Text(
-            "FIRST RUN",
-            style = onboardingCaption1Style.copy(fontWeight = FontWeight.Bold, letterSpacing = 1.5.sp),
-            color = onboardingAccent,
-          )
-          Text(
-            "OpenClaw\nMobile Setup",
-            style = onboardingDisplayStyle.copy(lineHeight = 38.sp),
+            "OpenClaw",
+            style = onboardingDisplayStyle,
            color = onboardingText,
          )
          Text(
-            "Step ${step.index} of 4",
-            style = onboardingCaption1Style,
-            color = onboardingAccent,
+            "Mobile Setup",
+            style = onboardingTitle1Style,
+            color = onboardingTextSecondary,
          )
        }
-        StepRailWrap(current = step)
+        StepRail(current = step)

        when (step) {
          OnboardingStep.Welcome -> WelcomeStep()
@@ -548,14 +543,28 @@ fun OnboardingFlow(viewModel: MainViewModel, modifier: Modifier = Modifier) {
              gatewayError = gatewayError,
              onScanQrClick = {
                gatewayError = null
-                qrScanLauncher.launch(
-                  ScanOptions().apply {
-                    setDesiredBarcodeFormats(ScanOptions.QR_CODE)
-                    setPrompt("Scan OpenClaw onboarding QR")
-                    setBeepEnabled(false)
-                    setOrientationLocked(false)
-                  },
-                )
+                qrScanner.startScan()
+                  .addOnSuccessListener { barcode ->
+                    val contents = barcode.rawValue?.trim().orEmpty()
+                    if (contents.isEmpty()) {
+                      return@addOnSuccessListener
+                    }
+                    val scannedSetupCode = resolveScannedSetupCode(contents)
+                    if (scannedSetupCode == null) {
+                      gatewayError = "QR code did not contain a valid setup code."
+                      return@addOnSuccessListener
+                    }
+                    setupCode = scannedSetupCode
+                    gatewayInputMode = GatewayInputMode.SetupCode
+                    gatewayError = null
+                    attemptedConnect = false
+                  }
+                  .addOnCanceledListener {
+                    // User dismissed the scanner; preserve current form state.
+                  }
+                  .addOnFailureListener {
+                    gatewayError = qrScannerErrorMessage()
+                  }
              },
              onAdvancedOpenChange = { gatewayAdvancedOpen = it },
              onInputModeChange = {
@@ -892,15 +901,6 @@ fun OnboardingFlow(viewModel: MainViewModel, modifier: Modifier = Modifier) {
  }
 }

-@Composable
-private fun StepRailWrap(current: OnboardingStep) {
-  Column(verticalArrangement = Arrangement.spacedBy(10.dp)) {
-    HorizontalDivider(color = onboardingBorder)
-    StepRail(current = current)
-    HorizontalDivider(color = onboardingBorder)
-  }
-}
-
@Composable
 private fun StepRail(current: OnboardingStep) {
  val steps = OnboardingStep.entries
@@ -942,11 +942,31 @@ private fun StepRail(current: OnboardingStep) {

@Composable
 private fun WelcomeStep() {
-  StepShell(title = "What You Get") {
-    Bullet("Control the gateway and operator chat from one mobile surface.")
-    Bullet("Connect with setup code and recover pairing with CLI commands.")
-    Bullet("Enable only the permissions and capabilities you want.")
-    Bullet("Finish with a real connection check before entering the app.")
+  Column(verticalArrangement = Arrangement.spacedBy(10.dp)) {
+    FeatureCard(
+      icon = Icons.Default.Wifi,
+      title = "Connect to your gateway",
+      subtitle = "Scan a QR code or enter your host manually",
+      accentColor = onboardingAccent,
+    )
+    FeatureCard(
+      icon = Icons.Default.Tune,
+      title = "Choose your permissions",
+      subtitle = "Enable only what you need, change anytime",
+      accentColor = Color(0xFF7C5AC7),
+    )
+    FeatureCard(
+      icon = Icons.Default.ChatBubble,
+      title = "Chat, voice, and screen",
+      subtitle = "Full operator control from your phone",
+      accentColor = onboardingSuccess,
+    )
+    FeatureCard(
+      icon = Icons.Default.CheckCircle,
+      title = "Verify your connection",
+      subtitle = "Live check before you enter the app",
+      accentColor = Color(0xFFC8841A),
+    )
  }
 }

@@ -975,11 +995,12 @@ private fun GatewayStep(
  val manualResolvedEndpoint = remember(manualHost, manualPort, manualTls) { composeGatewayManualUrl(manualHost, manualPort, manualTls)?.let { parseGatewayEndpoint(it)?.displayUrl } }

  StepShell(title = "Gateway Connection") {
-    GuideBlock(title = "Scan onboarding QR") {
-      Text("Run these on the gateway host:", style = onboardingCalloutStyle, color = onboardingTextSecondary)
-      CommandBlock("openclaw qr")
-      Text("Then scan with this device.", style = onboardingCalloutStyle, color = onboardingTextSecondary)
-    }
+    Text(
+      "Run `openclaw qr` on your gateway host, then scan the code with this device.",
+      style = onboardingCalloutStyle,
+      color = onboardingTextSecondary,
+    )
+    CommandBlock("openclaw qr")
    Button(
      onClick = onScanQrClick,
      modifier = Modifier.fillMaxWidth().height(48.dp),
@@ -1023,21 +1044,6 @@ private fun GatewayStep(

    AnimatedVisibility(visible = advancedOpen) {
      Column(verticalArrangement = Arrangement.spacedBy(12.dp)) {
-        GuideBlock(title = "Manual setup commands") {
-          Text("Run these on the gateway host:", style = onboardingCalloutStyle, color = onboardingTextSecondary)
-          CommandBlock("openclaw qr --setup-code-only")
-          CommandBlock("openclaw qr --json")
-          Text(
-            "`--json` prints `setupCode` and `gatewayUrl`.",
-            style = onboardingCalloutStyle,
-            color = onboardingTextSecondary,
-          )
-          Text(
-            "Auto URL discovery is not wired yet. Android emulator uses `10.0.2.2`; real devices need LAN/Tailscale host.",
-            style = onboardingCalloutStyle,
-            color = onboardingTextSecondary,
-          )
-        }
        GatewayModeToggle(inputMode = inputMode, onInputModeChange = onInputModeChange)

        if (inputMode == GatewayInputMode.SetupCode) {
@@ -1306,13 +1312,9 @@ private fun StepShell(
  title: String,
  content: @Composable ColumnScope.() -> Unit,
 ) {
-  Column(verticalArrangement = Arrangement.spacedBy(0.dp)) {
-    HorizontalDivider(color = onboardingBorder)
-    Column(modifier = Modifier.padding(vertical = 14.dp), verticalArrangement = Arrangement.spacedBy(12.dp)) {
-      Text(title, style = onboardingTitle1Style, color = onboardingText)
-      content()
-    }
-    HorizontalDivider(color = onboardingBorder)
+  Column(modifier = Modifier.padding(vertical = 4.dp), verticalArrangement = Arrangement.spacedBy(12.dp)) {
+    Text(title, style = onboardingTitle1Style, color = onboardingText)
+    content()
  }
 }

@@ -1378,13 +1380,15 @@ private fun PermissionsStep(

  StepShell(title = "Permissions") {
    Text(
-      "Enable only what you need now. You can change everything later in Settings.",
+      "Enable only what you need. You can change these anytime in Settings.",
      style = onboardingCalloutStyle,
      color = onboardingTextSecondary,
    )
+
+    PermissionSectionHeader("System")
    PermissionToggleRow(
      title = "Gateway discovery",
-      subtitle = if (Build.VERSION.SDK_INT >= 33) "Nearby devices" else "Location (for NSD)",
+      subtitle = "Find gateways on your local network",
      checked = enableDiscovery,
      granted = isPermissionGranted(context, discoveryPermission),
      onCheckedChange = onDiscoveryChange,
@@ -1392,7 +1396,7 @@ private fun PermissionsStep(
    InlineDivider()
    PermissionToggleRow(
      title = "Location",
-      subtitle = "location.get (while app is open)",
+      subtitle = "Share device location while app is open",
      checked = enableLocation,
      granted = locationGranted,
      onCheckedChange = onLocationChange,
@@ -1401,7 +1405,7 @@ private fun PermissionsStep(
    if (Build.VERSION.SDK_INT >= 33) {
      PermissionToggleRow(
        title = "Notifications",
-        subtitle = "system.notify and foreground alerts",
+        subtitle = "Alerts and foreground service notices",
        checked = enableNotifications,
        granted = isPermissionGranted(context, Manifest.permission.POST_NOTIFICATIONS),
        onCheckedChange = onNotificationsChange,
@@ -1410,15 +1414,16 @@ private fun PermissionsStep(
    }
    PermissionToggleRow(
      title = "Notification listener",
-      subtitle = "notifications.list and notifications.actions (opens Android Settings)",
+      subtitle = "Read and act on your notifications",
      checked = enableNotificationListener,
      granted = notificationListenerGranted,
      onCheckedChange = onNotificationListenerChange,
    )
-    InlineDivider()
+
+    PermissionSectionHeader("Media")
    PermissionToggleRow(
      title = "Microphone",
-      subtitle = "Foreground Voice tab transcription",
+      subtitle = "Voice transcription in the Voice tab",
      checked = enableMicrophone,
      granted = isPermissionGranted(context, Manifest.permission.RECORD_AUDIO),
      onCheckedChange = onMicrophoneChange,
@@ -1426,7 +1431,7 @@ private fun PermissionsStep(
    InlineDivider()
    PermissionToggleRow(
      title = "Camera",
-      subtitle = "camera.snap and camera.clip",
+      subtitle = "Take photos and short video clips",
      checked = enableCamera,
      granted = isPermissionGranted(context, Manifest.permission.CAMERA),
      onCheckedChange = onCameraChange,
@@ -1434,15 +1439,16 @@ private fun PermissionsStep(
    InlineDivider()
    PermissionToggleRow(
      title = "Photos",
-      subtitle = "photos.latest",
+      subtitle = "Access your recent photos",
      checked = enablePhotos,
      granted = isPermissionGranted(context, photosPermission),
      onCheckedChange = onPhotosChange,
    )
-    InlineDivider()
+
+    PermissionSectionHeader("Personal Data")
    PermissionToggleRow(
      title = "Contacts",
-      subtitle = "contacts.search and contacts.add",
+      subtitle = "Search and add contacts",
      checked = enableContacts,
      granted = contactsGranted,
      onCheckedChange = onContactsChange,
@@ -1450,7 +1456,7 @@ private fun PermissionsStep(
    InlineDivider()
    PermissionToggleRow(
      title = "Calendar",
-      subtitle = "calendar.events and calendar.add",
+      subtitle = "Read and create calendar events",
      checked = enableCalendar,
      granted = calendarGranted,
      onCheckedChange = onCalendarChange,
@@ -1458,7 +1464,7 @@ private fun PermissionsStep(
    InlineDivider()
    PermissionToggleRow(
      title = "Motion",
-      subtitle = "motion.activity and motion.pedometer",
+      subtitle = "Activity and step tracking",
      checked = enableMotion,
      granted = motionGranted,
      onCheckedChange = onMotionChange,
@@ -1469,16 +1475,25 @@ private fun PermissionsStep(
      InlineDivider()
      PermissionToggleRow(
        title = "SMS",
-        subtitle = "Allow gateway-triggered SMS sending",
+        subtitle = "Send text messages via the gateway",
        checked = enableSms,
        granted = isPermissionGranted(context, Manifest.permission.SEND_SMS),
        onCheckedChange = onSmsChange,
      )
    }
-    Text("All settings can be changed later in Settings.", style = onboardingCalloutStyle, color = onboardingTextSecondary)
  }
 }

+@Composable
+private fun PermissionSectionHeader(title: String) {
+  Text(
+    title.uppercase(),
+    style = onboardingCaption1Style.copy(fontWeight = FontWeight.Bold, letterSpacing = 1.2.sp),
+    color = onboardingAccent,
+    modifier = Modifier.padding(top = 8.dp),
+  )
+}
+
@Composable
 private fun PermissionToggleRow(
  title: String,
@@ -1489,6 +1504,12 @@ private fun PermissionToggleRow(
  statusOverride: String? = null,
  onCheckedChange: (Boolean) -> Unit,
 ) {
+  val statusText = statusOverride ?: if (granted) "Granted" else "Not granted"
+  val statusColor = when {
+    statusOverride != null -> onboardingTextTertiary
+    granted -> onboardingSuccess
+    else -> onboardingWarning
+  }
  Row(
    modifier = Modifier.fillMaxWidth().heightIn(min = 50.dp),
    verticalAlignment = Alignment.CenterVertically,
@@ -1497,11 +1518,7 @@ private fun PermissionToggleRow(
    Column(modifier = Modifier.weight(1f), verticalArrangement = Arrangement.spacedBy(2.dp)) {
      Text(title, style = onboardingHeadlineStyle, color = onboardingText)
      Text(subtitle, style = onboardingCalloutStyle.copy(lineHeight = 18.sp), color = onboardingTextSecondary)
-      Text(
-        statusOverride ?: if (granted) "Granted" else "Not granted",
-        style = onboardingCaption1Style,
-        color = if (granted) onboardingSuccess else onboardingTextSecondary,
-      )
+      Text(statusText, style = onboardingCaption1Style, color = statusColor)
    }
    Switch(
      checked = checked,
@@ -1529,20 +1546,131 @@ private fun FinalStep(
  enabledPermissions: String,
  methodLabel: String,
 ) {
-  StepShell(title = "Review") {
-    SummaryField(label = "Method", value = methodLabel)
-    SummaryField(label = "Gateway", value = parsedGateway?.displayUrl ?: "Invalid gateway URL")
-    SummaryField(label = "Enabled Permissions", value = enabledPermissions)
+  Column(verticalArrangement = Arrangement.spacedBy(10.dp)) {
+    Text("Review", style = onboardingTitle1Style, color = onboardingText)
+
+    SummaryCard(
+      icon = Icons.Default.Link,
+      label = "Method",
+      value = methodLabel,
+      accentColor = onboardingAccent,
+    )
+    SummaryCard(
+      icon = Icons.Default.Cloud,
+      label = "Gateway",
+      value = parsedGateway?.displayUrl ?: "Invalid gateway URL",
+      accentColor = Color(0xFF7C5AC7),
+    )
+    SummaryCard(
+      icon = Icons.Default.Security,
+      label = "Permissions",
+      value = enabledPermissions,
+      accentColor = onboardingSuccess,
+    )

    if (!attemptedConnect) {
-      Text("Press Connect to verify gateway reachability and auth.", style = onboardingCalloutStyle, color = onboardingTextSecondary)
+      Surface(
+        modifier = Modifier.fillMaxWidth(),
+        shape = RoundedCornerShape(14.dp),
+        color = onboardingAccentSoft,
+        border = androidx.compose.foundation.BorderStroke(1.dp, onboardingAccent.copy(alpha = 0.2f)),
+      ) {
+        Row(
+          modifier = Modifier.padding(14.dp),
+          horizontalArrangement = Arrangement.spacedBy(12.dp),
+          verticalAlignment = Alignment.CenterVertically,
+        ) {
+          Box(
+            modifier =
+              Modifier
+                .size(42.dp)
+                .background(onboardingAccent.copy(alpha = 0.1f), RoundedCornerShape(11.dp)),
+            contentAlignment = Alignment.Center,
+          ) {
+            Icon(
+              imageVector = Icons.Default.Wifi,
+              contentDescription = null,
+              tint = onboardingAccent,
+              modifier = Modifier.size(22.dp),
+            )
+          }
+          Text(
+            "Tap Connect to verify your gateway is reachable.",
+            style = onboardingCalloutStyle,
+            color = onboardingAccent,
+          )
+        }
+      }
+    } else if (isConnected) {
+      Surface(
+        modifier = Modifier.fillMaxWidth(),
+        shape = RoundedCornerShape(14.dp),
+        color = Color(0xFFEEF9F3),
+        border = androidx.compose.foundation.BorderStroke(1.dp, onboardingSuccess.copy(alpha = 0.2f)),
+      ) {
+        Row(
+          modifier = Modifier.padding(14.dp),
+          horizontalArrangement = Arrangement.spacedBy(12.dp),
+          verticalAlignment = Alignment.CenterVertically,
+        ) {
+          Box(
+            modifier =
+              Modifier
+                .size(42.dp)
+                .background(onboardingSuccess.copy(alpha = 0.1f), RoundedCornerShape(11.dp)),
+            contentAlignment = Alignment.Center,
+          ) {
+            Icon(
+              imageVector = Icons.Default.CheckCircle,
+              contentDescription = null,
+              tint = onboardingSuccess,
+              modifier = Modifier.size(22.dp),
+            )
+          }
+          Column(verticalArrangement = Arrangement.spacedBy(2.dp)) {
+            Text("Connected", style = onboardingHeadlineStyle, color = onboardingSuccess)
+            Text(
+              serverName ?: remoteAddress ?: "gateway",
+              style = onboardingCalloutStyle,
+              color = onboardingSuccess.copy(alpha = 0.8f),
+            )
+          }
+        }
+      }
    } else {
-      Text("Status: $statusText", style = onboardingCalloutStyle, color = if (isConnected) onboardingSuccess else onboardingTextSecondary)
-      if (isConnected) {
-        Text("Connected to ${serverName ?: remoteAddress ?: "gateway"}", style = onboardingCalloutStyle, color = onboardingSuccess)
-      } else {
-        GuideBlock(title = "Pairing Required") {
-          Text("Run these on the gateway host:", style = onboardingCalloutStyle, color = onboardingTextSecondary)
+      Surface(
+        modifier = Modifier.fillMaxWidth(),
+        shape = RoundedCornerShape(14.dp),
+        color = Color(0xFFFFF8EC),
+        border = androidx.compose.foundation.BorderStroke(1.dp, onboardingWarning.copy(alpha = 0.2f)),
+      ) {
+        Column(
+          modifier = Modifier.padding(14.dp),
+          verticalArrangement = Arrangement.spacedBy(10.dp),
+        ) {
+          Row(
+            horizontalArrangement = Arrangement.spacedBy(12.dp),
+            verticalAlignment = Alignment.CenterVertically,
+          ) {
+            Box(
+              modifier =
+                Modifier
+                  .size(42.dp)
+                  .background(onboardingWarning.copy(alpha = 0.1f), RoundedCornerShape(11.dp)),
+              contentAlignment = Alignment.Center,
+            ) {
+              Icon(
+                imageVector = Icons.Default.Link,
+                contentDescription = null,
+                tint = onboardingWarning,
+                modifier = Modifier.size(22.dp),
+              )
+            }
+            Column(verticalArrangement = Arrangement.spacedBy(2.dp)) {
+              Text("Pairing Required", style = onboardingHeadlineStyle, color = onboardingWarning)
+              Text("Run these on your gateway host:", style = onboardingCalloutStyle, color = onboardingTextSecondary)
+            }
+          }
          CommandBlock("openclaw devices list")
          CommandBlock("openclaw devices approve <requestId>")
          Text("Then tap Connect again.", style = onboardingCalloutStyle, color = onboardingTextSecondary)
@@ -1553,15 +1681,46 @@ private fun FinalStep(
 }

@Composable
-private fun SummaryField(label: String, value: String) {
-  Column(verticalArrangement = Arrangement.spacedBy(4.dp)) {
-    Text(
-      label,
-      style = onboardingCaption2Style.copy(fontWeight = FontWeight.SemiBold, letterSpacing = 0.6.sp),
-      color = onboardingTextSecondary,
-    )
-    Text(value, style = onboardingHeadlineStyle, color = onboardingText)
-    HorizontalDivider(color = onboardingBorder)
+private fun SummaryCard(
+  icon: ImageVector,
+  label: String,
+  value: String,
+  accentColor: Color,
+) {
+  Surface(
+    modifier = Modifier.fillMaxWidth(),
+    shape = RoundedCornerShape(14.dp),
+    color = onboardingSurface,
+    border = androidx.compose.foundation.BorderStroke(1.dp, onboardingBorder),
+  ) {
+    Row(
+      modifier = Modifier.padding(14.dp),
+      horizontalArrangement = Arrangement.spacedBy(14.dp),
+      verticalAlignment = Alignment.Top,
+    ) {
+      Box(
+        modifier =
+          Modifier
+            .size(42.dp)
+            .background(accentColor.copy(alpha = 0.1f), RoundedCornerShape(11.dp)),
+        contentAlignment = Alignment.Center,
+      ) {
+        Icon(
+          imageVector = icon,
+          contentDescription = null,
+          tint = accentColor,
+          modifier = Modifier.size(22.dp),
+        )
+      }
+      Column(modifier = Modifier.weight(1f), verticalArrangement = Arrangement.spacedBy(2.dp)) {
+        Text(
+          label.uppercase(),
+          style = onboardingCaption1Style.copy(fontWeight = FontWeight.Bold, letterSpacing = 0.8.sp),
+          color = onboardingTextSecondary,
+        )
+        Text(value, style = onboardingHeadlineStyle, color = onboardingText)
+      }
+    }
  }
 }

@@ -1571,10 +1730,12 @@ private fun CommandBlock(command: String) {
    modifier =
      Modifier
        .fillMaxWidth()
-        .background(onboardingCommandBg, RoundedCornerShape(12.dp))
+        .height(IntrinsicSize.Min)
+        .clip(RoundedCornerShape(12.dp))
+        .background(onboardingCommandBg)
        .border(width = 1.dp, color = onboardingCommandBorder, shape = RoundedCornerShape(12.dp)),
  ) {
-    Box(modifier = Modifier.width(3.dp).height(42.dp).background(onboardingCommandAccent))
+    Box(modifier = Modifier.width(3.dp).fillMaxHeight().background(onboardingCommandAccent))
    Text(
      command,
      modifier = Modifier.padding(horizontal = 12.dp, vertical = 10.dp),
@@ -1586,23 +1747,42 @@ private fun CommandBlock(command: String) {
 }

@Composable
-private fun Bullet(text: String) {
-  Row(horizontalArrangement = Arrangement.spacedBy(10.dp), verticalAlignment = Alignment.Top) {
-    Box(
-      modifier =
-        Modifier
-          .padding(top = 7.dp)
-          .size(8.dp)
-          .background(onboardingAccentSoft, CircleShape),
-    )
-    Box(
-      modifier =
-        Modifier
-          .padding(top = 9.dp)
-          .size(4.dp)
-          .background(onboardingAccent, CircleShape),
-    )
-    Text(text, style = onboardingBodyStyle, color = onboardingTextSecondary, modifier = Modifier.weight(1f))
+private fun FeatureCard(
+  icon: ImageVector,
+  title: String,
+  subtitle: String,
+  accentColor: Color,
+) {
+  Surface(
+    modifier = Modifier.fillMaxWidth(),
+    shape = RoundedCornerShape(14.dp),
+    color = onboardingSurface,
+    border = androidx.compose.foundation.BorderStroke(1.dp, onboardingBorder),
+  ) {
+    Row(
+      modifier = Modifier.padding(14.dp),
+      horizontalArrangement = Arrangement.spacedBy(14.dp),
+      verticalAlignment = Alignment.CenterVertically,
+    ) {
+      Box(
+        modifier =
+          Modifier
+            .size(42.dp)
+            .background(accentColor.copy(alpha = 0.1f), RoundedCornerShape(11.dp)),
+        contentAlignment = Alignment.Center,
+      ) {
+        Icon(
+          imageVector = icon,
+          contentDescription = null,
+          tint = accentColor,
+          modifier = Modifier.size(22.dp),
+        )
+      }
+      Column(verticalArrangement = Arrangement.spacedBy(2.dp)) {
+        Text(title, style = onboardingHeadlineStyle, color = onboardingText)
+        Text(subtitle, style = onboardingCalloutStyle, color = onboardingTextSecondary)
+      }
+    }
  }
 }

@@ -1610,6 +1790,10 @@ private fun isPermissionGranted(context: Context, permission: String): Boolean {
  return ContextCompat.checkSelfPermission(context, permission) == PackageManager.PERMISSION_GRANTED
 }

+private fun qrScannerErrorMessage(): String {
+  return "Google Code Scanner could not start. Update Google Play services or use the setup code manually."
+}
+
 private fun isNotificationListenerEnabled(context: Context): Boolean {
  return DeviceNotificationListenerService.isAccessEnabled(context)
 }
@@ -345,179 +345,90 @@ fun SettingsSheet(viewModel: MainViewModel) {
      contentPadding = PaddingValues(horizontal = 20.dp, vertical = 16.dp),
      verticalArrangement = Arrangement.spacedBy(8.dp),
    ) {
-      item {
-        Column(verticalArrangement = Arrangement.spacedBy(6.dp)) {
-          Text(
-            "SETTINGS",
-            style = mobileCaption1.copy(fontWeight = FontWeight.Bold, letterSpacing = 1.sp),
-            color = mobileAccent,
-          )
-          Text("Device Configuration", style = mobileTitle2, color = mobileText)
-          Text(
-            "Manage capabilities, permissions, and diagnostics.",
-            style = mobileCallout,
-            color = mobileTextSecondary,
-          )
-        }
-      }
-      item { HorizontalDivider(color = mobileBorder) }
-
-    // Order parity: Node → Voice → Camera → Messaging → Location → Screen.
+      // ── Node ──
      item {
        Text(
-          "NODE",
-          style = mobileCaption1.copy(fontWeight = FontWeight.Bold, letterSpacing = 1.sp),
-          color = mobileAccent,
-        )
-      }
-    item {
-      OutlinedTextField(
-        value = displayName,
-        onValueChange = viewModel::setDisplayName,
-        label = { Text("Name", style = mobileCaption1, color = mobileTextSecondary) },
-        modifier = Modifier.fillMaxWidth(),
-        textStyle = mobileBody.copy(color = mobileText),
-        colors = settingsTextFieldColors(),
-      )
-    }
-      item { Text("Instance ID: $instanceId", style = mobileCallout.copy(fontFamily = FontFamily.Monospace), color = mobileTextSecondary) }
-      item { Text("Device: $deviceModel", style = mobileCallout, color = mobileTextSecondary) }
-      item { Text("Version: $appVersion", style = mobileCallout, color = mobileTextSecondary) }
-
-      item { HorizontalDivider(color = mobileBorder) }
-
-      // Voice
-      item {
-        Text(
-          "VOICE",
+          "DEVICE",
          style = mobileCaption1.copy(fontWeight = FontWeight.Bold, letterSpacing = 1.sp),
          color = mobileAccent,
        )
      }
      item {
-        ListItem(
-          modifier = Modifier.settingsRowModifier(),
-          colors = listItemColors,
-          headlineContent = { Text("Microphone permission", style = mobileHeadline) },
-          supportingContent = {
+        Column(modifier = Modifier.settingsRowModifier()) {
+          OutlinedTextField(
+            value = displayName,
+            onValueChange = viewModel::setDisplayName,
+            label = { Text("Name", style = mobileCaption1, color = mobileTextSecondary) },
+            modifier = Modifier.fillMaxWidth().padding(horizontal = 14.dp, vertical = 10.dp),
+            textStyle = mobileBody.copy(color = mobileText),
+            colors = settingsTextFieldColors(),
+          )
+          HorizontalDivider(color = mobileBorder)
+          Column(
+            modifier = Modifier.padding(horizontal = 14.dp, vertical = 10.dp),
+            verticalArrangement = Arrangement.spacedBy(2.dp),
+          ) {
+            Text("$deviceModel · $appVersion", style = mobileCallout, color = mobileTextSecondary)
            Text(
-              if (micPermissionGranted) {
-                "Granted. Use the Voice tab mic button to capture transcript while the app is open."
-              } else {
-                "Required for foreground Voice tab transcription."
-              },
-              style = mobileCallout,
+              instanceId.take(8) + "…",
+              style = mobileCaption1.copy(fontFamily = FontFamily.Monospace),
+              color = mobileTextTertiary,
            )
-          },
-          trailingContent = {
-            Button(
-              onClick = {
-                if (micPermissionGranted) {
-                  openAppSettings(context)
-                } else {
-                  audioPermissionLauncher.launch(Manifest.permission.RECORD_AUDIO)
-                }
-              },
-              colors = settingsPrimaryButtonColors(),
-              shape = RoundedCornerShape(14.dp),
-            ) {
-              Text(
-                if (micPermissionGranted) "Manage" else "Grant",
-                style = mobileCallout.copy(fontWeight = FontWeight.Bold),
-              )
-            }
-          },
-        )
-      }
-      item {
-        Text(
-          "Voice wake and talk modes were removed. Voice now uses one mic on/off flow in the Voice tab while the app is open.",
-          style = mobileCallout,
-          color = mobileTextSecondary,
-        )
-      }
-
-      item { HorizontalDivider(color = mobileBorder) }
-
-    // Camera
-      item {
-        Text(
-          "CAMERA",
-          style = mobileCaption1.copy(fontWeight = FontWeight.Bold, letterSpacing = 1.sp),
-          color = mobileAccent,
-        )
-      }
-    item {
-      ListItem(
-        modifier = Modifier.settingsRowModifier(),
-        colors = listItemColors,
-        headlineContent = { Text("Allow Camera", style = mobileHeadline) },
-        supportingContent = { Text("Allows the gateway to request photos or short video clips (foreground only).", style = mobileCallout) },
-        trailingContent = { Switch(checked = cameraEnabled, onCheckedChange = ::setCameraEnabledChecked) },
-      )
-    }
-    item {
-      Text(
-        "Tip: grant Microphone permission for video clips with audio.",
-        style = mobileCallout,
-        color = mobileTextSecondary,
-      )
-    }
-
-      item { HorizontalDivider(color = mobileBorder) }
-
-    // Messaging
-      item {
-        Text(
-          "MESSAGING",
-          style = mobileCaption1.copy(fontWeight = FontWeight.Bold, letterSpacing = 1.sp),
-          color = mobileAccent,
-        )
-      }
-    item {
-      val buttonLabel =
-        when {
-          !smsPermissionAvailable -> "Unavailable"
-          smsPermissionGranted -> "Manage"
-          else -> "Grant"
+          }
        }
-      ListItem(
-        modifier = Modifier.settingsRowModifier(),
-        colors = listItemColors,
-        headlineContent = { Text("SMS Permission", style = mobileHeadline) },
-        supportingContent = {
-          Text(
-            if (smsPermissionAvailable) {
-              "Allow the gateway to send SMS from this device."
-            } else {
-              "SMS requires a device with telephony hardware."
+      }
+
+      // ── Media ──
+      item {
+        Text(
+          "MEDIA",
+          style = mobileCaption1.copy(fontWeight = FontWeight.Bold, letterSpacing = 1.sp),
+          color = mobileAccent,
+        )
+      }
+      item {
+        Column(modifier = Modifier.settingsRowModifier()) {
+          ListItem(
+            modifier = Modifier.fillMaxWidth(),
+            colors = listItemColors,
+            headlineContent = { Text("Microphone", style = mobileHeadline) },
+            supportingContent = {
+              Text(
+                if (micPermissionGranted) "Granted" else "Required for voice transcription.",
+                style = mobileCallout,
+              )
            },
-            style = mobileCallout,
-          )
-        },
-        trailingContent = {
-          Button(
-            onClick = {
-              if (!smsPermissionAvailable) return@Button
-              if (smsPermissionGranted) {
-                openAppSettings(context)
-              } else {
-                smsPermissionLauncher.launch(Manifest.permission.SEND_SMS)
+            trailingContent = {
+              Button(
+                onClick = {
+                  if (micPermissionGranted) {
+                    openAppSettings(context)
+                  } else {
+                    audioPermissionLauncher.launch(Manifest.permission.RECORD_AUDIO)
+                  }
+                },
+                colors = settingsPrimaryButtonColors(),
+                shape = RoundedCornerShape(14.dp),
+              ) {
+                Text(
+                  if (micPermissionGranted) "Manage" else "Grant",
+                  style = mobileCallout.copy(fontWeight = FontWeight.Bold),
+                )
              }
            },
-            enabled = smsPermissionAvailable,
-            colors = settingsPrimaryButtonColors(),
-            shape = RoundedCornerShape(14.dp),
-          ) {
-            Text(buttonLabel, style = mobileCallout.copy(fontWeight = FontWeight.Bold))
-          }
-        },
-      )
-    }
+          )
+          HorizontalDivider(color = mobileBorder)
+          ListItem(
+            modifier = Modifier.fillMaxWidth(),
+            colors = listItemColors,
+            headlineContent = { Text("Camera", style = mobileHeadline) },
+            supportingContent = { Text("Photos and video clips (foreground only).", style = mobileCallout) },
+            trailingContent = { Switch(checked = cameraEnabled, onCheckedChange = ::setCameraEnabledChecked) },
+          )
+        }
+      }

-      item { HorizontalDivider(color = mobileBorder) }
-
-    // Notifications
+      // ── Notifications & Messaging ──
      item {
        Text(
          "NOTIFICATIONS",
@@ -526,67 +437,87 @@ fun SettingsSheet(viewModel: MainViewModel) {
        )
      }
      item {
-        val buttonLabel =
-          if (notificationsPermissionGranted) {
-            "Manage"
-          } else {
-            "Grant"
-          }
-        ListItem(
-          modifier = Modifier.settingsRowModifier(),
-          colors = listItemColors,
-          headlineContent = { Text("System Notifications", style = mobileHeadline) },
-          supportingContent = {
-            Text(
-              "Required for `system.notify` and Android foreground service alerts.",
-              style = mobileCallout,
-            )
-          },
-          trailingContent = {
-            Button(
-              onClick = {
-                if (notificationsPermissionGranted || Build.VERSION.SDK_INT < 33) {
-                  openAppSettings(context)
-                } else {
-                  notificationsPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
+        Column(modifier = Modifier.settingsRowModifier()) {
+          ListItem(
+            modifier = Modifier.fillMaxWidth(),
+            colors = listItemColors,
+            headlineContent = { Text("System Notifications", style = mobileHeadline) },
+            supportingContent = {
+              Text("Alerts and foreground service.", style = mobileCallout)
+            },
+            trailingContent = {
+              Button(
+                onClick = {
+                  if (notificationsPermissionGranted || Build.VERSION.SDK_INT < 33) {
+                    openAppSettings(context)
+                  } else {
+                    notificationsPermissionLauncher.launch(Manifest.permission.POST_NOTIFICATIONS)
+                  }
+                },
+                colors = settingsPrimaryButtonColors(),
+                shape = RoundedCornerShape(14.dp),
+              ) {
+                Text(
+                  if (notificationsPermissionGranted) "Manage" else "Grant",
+                  style = mobileCallout.copy(fontWeight = FontWeight.Bold),
+                )
+              }
+            },
+          )
+          HorizontalDivider(color = mobileBorder)
+          ListItem(
+            modifier = Modifier.fillMaxWidth(),
+            colors = listItemColors,
+            headlineContent = { Text("Notification Listener", style = mobileHeadline) },
+            supportingContent = {
+              Text("Read and interact with notifications.", style = mobileCallout)
+            },
+            trailingContent = {
+              Button(
+                onClick = { openNotificationListenerSettings(context) },
+                colors = settingsPrimaryButtonColors(),
+                shape = RoundedCornerShape(14.dp),
+              ) {
+                Text(
+                  if (notificationListenerEnabled) "Manage" else "Enable",
+                  style = mobileCallout.copy(fontWeight = FontWeight.Bold),
+                )
+              }
+            },
+          )
+          if (smsPermissionAvailable) {
+            HorizontalDivider(color = mobileBorder)
+            ListItem(
+              modifier = Modifier.fillMaxWidth(),
+              colors = listItemColors,
+              headlineContent = { Text("SMS", style = mobileHeadline) },
+              supportingContent = {
+                Text("Send SMS from this device.", style = mobileCallout)
+              },
+              trailingContent = {
+                Button(
+                  onClick = {
+                    if (smsPermissionGranted) {
+                      openAppSettings(context)
+                    } else {
+                      smsPermissionLauncher.launch(Manifest.permission.SEND_SMS)
+                    }
+                  },
+                  colors = settingsPrimaryButtonColors(),
+                  shape = RoundedCornerShape(14.dp),
+                ) {
+                  Text(
+                    if (smsPermissionGranted) "Manage" else "Grant",
+                    style = mobileCallout.copy(fontWeight = FontWeight.Bold),
+                  )
                }
              },
-              colors = settingsPrimaryButtonColors(),
-              shape = RoundedCornerShape(14.dp),
-            ) {
-              Text(buttonLabel, style = mobileCallout.copy(fontWeight = FontWeight.Bold))
-            }
-          },
-        )
-      }
-      item {
-        ListItem(
-          modifier = Modifier.settingsRowModifier(),
-          colors = listItemColors,
-          headlineContent = { Text("Notification Listener Access", style = mobileHeadline) },
-          supportingContent = {
-            Text(
-              "Required for `notifications.list` and `notifications.actions`.",
-              style = mobileCallout,
            )
-          },
-          trailingContent = {
-            Button(
-              onClick = { openNotificationListenerSettings(context) },
-              colors = settingsPrimaryButtonColors(),
-              shape = RoundedCornerShape(14.dp),
-            ) {
-              Text(
-                if (notificationListenerEnabled) "Manage" else "Enable",
-                style = mobileCallout.copy(fontWeight = FontWeight.Bold),
-              )
-            }
-          },
-        )
+          }
+        }
      }
-      item { HorizontalDivider(color = mobileBorder) }

-    // Data access
+      // ── Data Access ──
      item {
        Text(
          "DATA ACCESS",
@@ -595,142 +526,115 @@ fun SettingsSheet(viewModel: MainViewModel) {
        )
      }
      item {
-        ListItem(
-          modifier = Modifier.settingsRowModifier(),
-          colors = listItemColors,
-          headlineContent = { Text("Photos Permission", style = mobileHeadline) },
-          supportingContent = {
-            Text(
-              "Required for `photos.latest`.",
-              style = mobileCallout,
-            )
-          },
-          trailingContent = {
-            Button(
-              onClick = {
-                if (photosPermissionGranted) {
-                  openAppSettings(context)
-                } else {
-                  photosPermissionLauncher.launch(photosPermission)
+        Column(modifier = Modifier.settingsRowModifier()) {
+          ListItem(
+            modifier = Modifier.fillMaxWidth(),
+            colors = listItemColors,
+            headlineContent = { Text("Photos", style = mobileHeadline) },
+            supportingContent = { Text("Access recent photos.", style = mobileCallout) },
+            trailingContent = {
+              Button(
+                onClick = {
+                  if (photosPermissionGranted) {
+                    openAppSettings(context)
+                  } else {
+                    photosPermissionLauncher.launch(photosPermission)
+                  }
+                },
+                colors = settingsPrimaryButtonColors(),
+                shape = RoundedCornerShape(14.dp),
+              ) {
+                Text(
+                  if (photosPermissionGranted) "Manage" else "Grant",
+                  style = mobileCallout.copy(fontWeight = FontWeight.Bold),
+                )
+              }
+            },
+          )
+          HorizontalDivider(color = mobileBorder)
+          ListItem(
+            modifier = Modifier.fillMaxWidth(),
+            colors = listItemColors,
+            headlineContent = { Text("Contacts", style = mobileHeadline) },
+            supportingContent = { Text("Search and add contacts.", style = mobileCallout) },
+            trailingContent = {
+              Button(
+                onClick = {
+                  if (contactsPermissionGranted) {
+                    openAppSettings(context)
+                  } else {
+                    contactsPermissionLauncher.launch(arrayOf(Manifest.permission.READ_CONTACTS, Manifest.permission.WRITE_CONTACTS))
+                  }
+                },
+                colors = settingsPrimaryButtonColors(),
+                shape = RoundedCornerShape(14.dp),
+              ) {
+                Text(
+                  if (contactsPermissionGranted) "Manage" else "Grant",
+                  style = mobileCallout.copy(fontWeight = FontWeight.Bold),
+                )
+              }
+            },
+          )
+          HorizontalDivider(color = mobileBorder)
+          ListItem(
+            modifier = Modifier.fillMaxWidth(),
+            colors = listItemColors,
+            headlineContent = { Text("Calendar", style = mobileHeadline) },
+            supportingContent = { Text("Read and create events.", style = mobileCallout) },
+            trailingContent = {
+              Button(
+                onClick = {
+                  if (calendarPermissionGranted) {
+                    openAppSettings(context)
+                  } else {
+                    calendarPermissionLauncher.launch(arrayOf(Manifest.permission.READ_CALENDAR, Manifest.permission.WRITE_CALENDAR))
+                  }
+                },
+                colors = settingsPrimaryButtonColors(),
+                shape = RoundedCornerShape(14.dp),
+              ) {
+                Text(
+                  if (calendarPermissionGranted) "Manage" else "Grant",
+                  style = mobileCallout.copy(fontWeight = FontWeight.Bold),
+                )
+              }
+            },
+          )
+          if (motionAvailable) {
+            HorizontalDivider(color = mobileBorder)
+            ListItem(
+              modifier = Modifier.fillMaxWidth(),
+              colors = listItemColors,
+              headlineContent = { Text("Motion", style = mobileHeadline) },
+              supportingContent = { Text("Track steps and activity.", style = mobileCallout) },
+              trailingContent = {
+                val motionButtonLabel =
+                  when {
+                    !motionPermissionRequired -> "Manage"
+                    motionPermissionGranted -> "Manage"
+                    else -> "Grant"
+                  }
+                Button(
+                  onClick = {
+                    if (!motionPermissionRequired || motionPermissionGranted) {
+                      openAppSettings(context)
+                    } else {
+                      motionPermissionLauncher.launch(Manifest.permission.ACTIVITY_RECOGNITION)
+                    }
+                  },
+                  colors = settingsPrimaryButtonColors(),
+                  shape = RoundedCornerShape(14.dp),
+                ) {
+                  Text(motionButtonLabel, style = mobileCallout.copy(fontWeight = FontWeight.Bold))
                }
              },
-              colors = settingsPrimaryButtonColors(),
-              shape = RoundedCornerShape(14.dp),
-            ) {
-              Text(
-                if (photosPermissionGranted) "Manage" else "Grant",
-                style = mobileCallout.copy(fontWeight = FontWeight.Bold),
-              )
-            }
-          },
-        )
-      }
-      item {
-        ListItem(
-          modifier = Modifier.settingsRowModifier(),
-          colors = listItemColors,
-          headlineContent = { Text("Contacts Permission", style = mobileHeadline) },
-          supportingContent = {
-            Text(
-              "Required for `contacts.search` and `contacts.add`.",
-              style = mobileCallout,
            )
-          },
-          trailingContent = {
-            Button(
-              onClick = {
-                if (contactsPermissionGranted) {
-                  openAppSettings(context)
-                } else {
-                  contactsPermissionLauncher.launch(arrayOf(Manifest.permission.READ_CONTACTS, Manifest.permission.WRITE_CONTACTS))
-                }
-              },
-              colors = settingsPrimaryButtonColors(),
-              shape = RoundedCornerShape(14.dp),
-            ) {
-              Text(
-                if (contactsPermissionGranted) "Manage" else "Grant",
-                style = mobileCallout.copy(fontWeight = FontWeight.Bold),
-              )
-            }
-          },
-        )
-      }
-      item {
-        ListItem(
-          modifier = Modifier.settingsRowModifier(),
-          colors = listItemColors,
-          headlineContent = { Text("Calendar Permission", style = mobileHeadline) },
-          supportingContent = {
-            Text(
-              "Required for `calendar.events` and `calendar.add`.",
-              style = mobileCallout,
-            )
-          },
-          trailingContent = {
-            Button(
-              onClick = {
-                if (calendarPermissionGranted) {
-                  openAppSettings(context)
-                } else {
-                  calendarPermissionLauncher.launch(arrayOf(Manifest.permission.READ_CALENDAR, Manifest.permission.WRITE_CALENDAR))
-                }
-              },
-              colors = settingsPrimaryButtonColors(),
-              shape = RoundedCornerShape(14.dp),
-            ) {
-              Text(
-                if (calendarPermissionGranted) "Manage" else "Grant",
-                style = mobileCallout.copy(fontWeight = FontWeight.Bold),
-              )
-            }
-          },
-        )
-      }
-      item {
-        val motionButtonLabel =
-          when {
-            !motionAvailable -> "Unavailable"
-            !motionPermissionRequired -> "Manage"
-            motionPermissionGranted -> "Manage"
-            else -> "Grant"
          }
-        ListItem(
-          modifier = Modifier.settingsRowModifier(),
-          colors = listItemColors,
-          headlineContent = { Text("Motion Permission", style = mobileHeadline) },
-          supportingContent = {
-            Text(
-              if (!motionAvailable) {
-                "This device does not expose accelerometer or step-counter motion sensors."
-              } else {
-                "Required for `motion.activity` and `motion.pedometer`."
-              },
-              style = mobileCallout,
-            )
-          },
-          trailingContent = {
-            Button(
-              onClick = {
-                if (!motionAvailable) return@Button
-                if (!motionPermissionRequired || motionPermissionGranted) {
-                  openAppSettings(context)
-                } else {
-                  motionPermissionLauncher.launch(Manifest.permission.ACTIVITY_RECOGNITION)
-                }
-              },
-              enabled = motionAvailable,
-              colors = settingsPrimaryButtonColors(),
-              shape = RoundedCornerShape(14.dp),
-            ) {
-              Text(motionButtonLabel, style = mobileCallout.copy(fontWeight = FontWeight.Bold))
-            }
-          },
-        )
+        }
      }
-      item { HorizontalDivider(color = mobileBorder) }

-    // Location
+      // ── Location ──
      item {
        Text(
          "LOCATION",
@@ -739,7 +643,7 @@ fun SettingsSheet(viewModel: MainViewModel) {
        )
      }
      item {
-        Column(modifier = Modifier.settingsRowModifier(), verticalArrangement = Arrangement.spacedBy(0.dp)) {
+        Column(modifier = Modifier.settingsRowModifier()) {
          ListItem(
            modifier = Modifier.fillMaxWidth(),
            colors = listItemColors,
@@ -781,50 +685,39 @@ fun SettingsSheet(viewModel: MainViewModel) {
          )
        }
      }
-      item { HorizontalDivider(color = mobileBorder) }

-    // Screen
+      // ── Preferences ──
      item {
        Text(
-          "SCREEN",
+          "PREFERENCES",
          style = mobileCaption1.copy(fontWeight = FontWeight.Bold, letterSpacing = 1.sp),
          color = mobileAccent,
        )
      }
-    item {
-      ListItem(
-        modifier = Modifier.settingsRowModifier(),
-        colors = listItemColors,
-        headlineContent = { Text("Prevent Sleep", style = mobileHeadline) },
-        supportingContent = { Text("Keeps the screen awake while OpenClaw is open.", style = mobileCallout) },
-        trailingContent = { Switch(checked = preventSleep, onCheckedChange = viewModel::setPreventSleep) },
-      )
-    }
-
-      item { HorizontalDivider(color = mobileBorder) }
-
-    // Debug
      item {
-        Text(
-          "DEBUG",
-          style = mobileCaption1.copy(fontWeight = FontWeight.Bold, letterSpacing = 1.sp),
-          color = mobileAccent,
-        )
-      }
-    item {
-      ListItem(
-        modifier = Modifier.settingsRowModifier(),
-        colors = listItemColors,
-        headlineContent = { Text("Debug Canvas Status", style = mobileHeadline) },
-        supportingContent = { Text("Show status text in the canvas when debug is enabled.", style = mobileCallout) },
-        trailingContent = {
-          Switch(
-            checked = canvasDebugStatusEnabled,
-            onCheckedChange = viewModel::setCanvasDebugStatusEnabled,
+        Column(modifier = Modifier.settingsRowModifier()) {
+          ListItem(
+            modifier = Modifier.fillMaxWidth(),
+            colors = listItemColors,
+            headlineContent = { Text("Prevent Sleep", style = mobileHeadline) },
+            supportingContent = { Text("Keep screen awake while open.", style = mobileCallout) },
+            trailingContent = { Switch(checked = preventSleep, onCheckedChange = viewModel::setPreventSleep) },
          )
-        },
-      )
-    }
+          HorizontalDivider(color = mobileBorder)
+          ListItem(
+            modifier = Modifier.fillMaxWidth(),
+            colors = listItemColors,
+            headlineContent = { Text("Debug Canvas", style = mobileHeadline) },
+            supportingContent = { Text("Show status overlay on canvas.", style = mobileCallout) },
+            trailingContent = {
+              Switch(
+                checked = canvasDebugStatusEnabled,
+                onCheckedChange = viewModel::setCanvasDebugStatusEnabled,
+              )
+            },
+          )
+        }
+      }

      item { Spacer(modifier = Modifier.height(24.dp)) }
    }
@@ -17,10 +17,12 @@ import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.Column
 import androidx.compose.foundation.layout.PaddingValues
 import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.Spacer
 import androidx.compose.foundation.layout.WindowInsets
 import androidx.compose.foundation.layout.WindowInsetsSides
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
 import androidx.compose.foundation.layout.imePadding
 import androidx.compose.foundation.layout.only
 import androidx.compose.foundation.layout.padding
@@ -212,19 +214,26 @@ fun VoiceTabScreen(viewModel: MainViewModel) {
        verticalAlignment = Alignment.CenterVertically,
      ) {
        // Speaker toggle
-        IconButton(
-          onClick = { viewModel.setSpeakerEnabled(!speakerEnabled) },
-          modifier = Modifier.size(48.dp),
-          colors =
-            IconButtonDefaults.iconButtonColors(
-              containerColor = if (speakerEnabled) mobileSurface else mobileDangerSoft,
-            ),
-        ) {
-          Icon(
-            imageVector = if (speakerEnabled) Icons.AutoMirrored.Filled.VolumeUp else Icons.AutoMirrored.Filled.VolumeOff,
-            contentDescription = if (speakerEnabled) "Mute speaker" else "Unmute speaker",
-            modifier = Modifier.size(22.dp),
-            tint = if (speakerEnabled) mobileTextSecondary else mobileDanger,
+        Column(horizontalAlignment = Alignment.CenterHorizontally, verticalArrangement = Arrangement.spacedBy(4.dp)) {
+          IconButton(
+            onClick = { viewModel.setSpeakerEnabled(!speakerEnabled) },
+            modifier = Modifier.size(48.dp),
+            colors =
+              IconButtonDefaults.iconButtonColors(
+                containerColor = if (speakerEnabled) mobileSurface else mobileDangerSoft,
+              ),
+          ) {
+            Icon(
+              imageVector = if (speakerEnabled) Icons.AutoMirrored.Filled.VolumeUp else Icons.AutoMirrored.Filled.VolumeOff,
+              contentDescription = if (speakerEnabled) "Mute speaker" else "Unmute speaker",
+              modifier = Modifier.size(22.dp),
+              tint = if (speakerEnabled) mobileTextSecondary else mobileDanger,
+            )
+          }
+          Text(
+            if (speakerEnabled) "Speaker" else "Muted",
+            style = mobileCaption2,
+            color = if (speakerEnabled) mobileTextTertiary else mobileDanger,
          )
        }

@@ -278,8 +287,12 @@ fun VoiceTabScreen(viewModel: MainViewModel) {
          }
        }

-        // Invisible spacer to balance the row (same size as speaker button)
-        Box(modifier = Modifier.size(48.dp))
+        // Invisible spacer to balance the row (matches speaker column width)
+        Column(horizontalAlignment = Alignment.CenterHorizontally) {
+          Box(modifier = Modifier.size(48.dp))
+          Spacer(modifier = Modifier.height(4.dp))
+          Text("", style = mobileCaption2)
+        }
      }

      // Status + labels
@@ -292,11 +305,24 @@ fun VoiceTabScreen(viewModel: MainViewModel) {
          micEnabled -> "Listening"
          else -> "Mic off"
        }
-      Text(
-        "$gatewayStatus · $stateText",
-        style = mobileCaption1,
-        color = mobileTextSecondary,
-      )
+      val stateColor =
+        when {
+          micEnabled -> mobileSuccess
+          micIsSending -> mobileAccent
+          else -> mobileTextSecondary
+        }
+      Surface(
+        shape = RoundedCornerShape(999.dp),
+        color = if (micEnabled) mobileSuccessSoft else mobileSurface,
+        border = BorderStroke(1.dp, if (micEnabled) mobileSuccess.copy(alpha = 0.3f) else mobileBorder),
+      ) {
+        Text(
+          "$gatewayStatus · $stateText",
+          style = mobileCallout.copy(fontWeight = FontWeight.SemiBold),
+          color = stateColor,
+          modifier = Modifier.padding(horizontal = 14.dp, vertical = 6.dp),
+        )
+      }

      if (!hasMicPermission) {
        val showRationale =
@@ -26,7 +26,6 @@ import androidx.compose.material3.ButtonDefaults
 import androidx.compose.material3.CircularProgressIndicator
 import androidx.compose.material3.DropdownMenu
 import androidx.compose.material3.DropdownMenuItem
-import androidx.compose.material3.HorizontalDivider
 import androidx.compose.material3.Icon
 import androidx.compose.material3.MaterialTheme
 import androidx.compose.material3.OutlinedTextField
@@ -78,65 +77,15 @@ fun ChatComposer(
  val sendBusy = pendingRunCount > 0

  Column(modifier = Modifier.fillMaxWidth(), verticalArrangement = Arrangement.spacedBy(8.dp)) {
-    Row(
-      modifier = Modifier.fillMaxWidth(),
-      verticalAlignment = Alignment.CenterVertically,
-      horizontalArrangement = Arrangement.spacedBy(8.dp),
-    ) {
-      Box(modifier = Modifier.weight(1f)) {
-        Surface(
-          onClick = { showThinkingMenu = true },
-          shape = RoundedCornerShape(14.dp),
-          color = mobileAccentSoft,
-          border = BorderStroke(1.dp, mobileBorderStrong),
-        ) {
-          Row(
-            modifier = Modifier.fillMaxWidth().padding(horizontal = 12.dp, vertical = 8.dp),
-            verticalAlignment = Alignment.CenterVertically,
-            horizontalArrangement = Arrangement.SpaceBetween,
-          ) {
-            Text(
-              text = "Thinking: ${thinkingLabel(thinkingLevel)}",
-              style = mobileCaption1.copy(fontWeight = FontWeight.SemiBold),
-              color = mobileText,
-            )
-            Icon(Icons.Default.ArrowDropDown, contentDescription = "Select thinking level", tint = mobileTextSecondary)
-          }
-        }
-
-        DropdownMenu(expanded = showThinkingMenu, onDismissRequest = { showThinkingMenu = false }) {
-          ThinkingMenuItem("off", thinkingLevel, onSetThinkingLevel) { showThinkingMenu = false }
-          ThinkingMenuItem("low", thinkingLevel, onSetThinkingLevel) { showThinkingMenu = false }
-          ThinkingMenuItem("medium", thinkingLevel, onSetThinkingLevel) { showThinkingMenu = false }
-          ThinkingMenuItem("high", thinkingLevel, onSetThinkingLevel) { showThinkingMenu = false }
-        }
-      }
-
-      SecondaryActionButton(
-        label = "Attach",
-        icon = Icons.Default.AttachFile,
-        enabled = true,
-        onClick = onPickImages,
-      )
-    }
-
    if (attachments.isNotEmpty()) {
      AttachmentsStrip(attachments = attachments, onRemoveAttachment = onRemoveAttachment)
    }

-    HorizontalDivider(color = mobileBorder)
-
-    Text(
-      text = "MESSAGE",
-      style = mobileCaption1.copy(fontWeight = FontWeight.Bold, letterSpacing = 0.9.sp),
-      color = mobileTextSecondary,
-    )
-
    OutlinedTextField(
      value = input,
      onValueChange = { input = it },
-      modifier = Modifier.fillMaxWidth().height(92.dp),
-      placeholder = { Text("Type a message", style = mobileBodyStyle(), color = mobileTextTertiary) },
+      modifier = Modifier.fillMaxWidth(),
+      placeholder = { Text("Type a message…", style = mobileBodyStyle(), color = mobileTextTertiary) },
      minLines = 2,
      maxLines = 5,
      textStyle = mobileBodyStyle().copy(color = mobileText),
@@ -155,26 +104,62 @@ fun ChatComposer(
    Row(
      modifier = Modifier.fillMaxWidth(),
      verticalAlignment = Alignment.CenterVertically,
-      horizontalArrangement = Arrangement.spacedBy(10.dp),
+      horizontalArrangement = Arrangement.spacedBy(8.dp),
    ) {
-      Row(horizontalArrangement = Arrangement.spacedBy(8.dp)) {
-        SecondaryActionButton(
-          label = "Refresh",
-          icon = Icons.Default.Refresh,
-          enabled = true,
-          compact = true,
-          onClick = onRefresh,
-        )
+      Box {
+        Surface(
+          onClick = { showThinkingMenu = true },
+          shape = RoundedCornerShape(14.dp),
+          color = Color.White,
+          border = BorderStroke(1.dp, mobileBorderStrong),
+        ) {
+          Row(
+            modifier = Modifier.padding(horizontal = 10.dp, vertical = 10.dp),
+            verticalAlignment = Alignment.CenterVertically,
+          ) {
+            Text(
+              text = thinkingLabel(thinkingLevel),
+              style = mobileCaption1.copy(fontWeight = FontWeight.SemiBold),
+              color = mobileTextSecondary,
+            )
+            Icon(Icons.Default.ArrowDropDown, contentDescription = "Select thinking level", modifier = Modifier.size(18.dp), tint = mobileTextTertiary)
+          }
+        }

-        SecondaryActionButton(
-          label = "Abort",
-          icon = Icons.Default.Stop,
-          enabled = pendingRunCount > 0,
-          compact = true,
-          onClick = onAbort,
-        )
+        DropdownMenu(expanded = showThinkingMenu, onDismissRequest = { showThinkingMenu = false }) {
+          ThinkingMenuItem("off", thinkingLevel, onSetThinkingLevel) { showThinkingMenu = false }
+          ThinkingMenuItem("low", thinkingLevel, onSetThinkingLevel) { showThinkingMenu = false }
+          ThinkingMenuItem("medium", thinkingLevel, onSetThinkingLevel) { showThinkingMenu = false }
+          ThinkingMenuItem("high", thinkingLevel, onSetThinkingLevel) { showThinkingMenu = false }
+        }
      }

+      SecondaryActionButton(
+        label = "Attach",
+        icon = Icons.Default.AttachFile,
+        enabled = true,
+        compact = true,
+        onClick = onPickImages,
+      )
+
+      SecondaryActionButton(
+        label = "Refresh",
+        icon = Icons.Default.Refresh,
+        enabled = true,
+        compact = true,
+        onClick = onRefresh,
+      )
+
+      SecondaryActionButton(
+        label = "Abort",
+        icon = Icons.Default.Stop,
+        enabled = pendingRunCount > 0,
+        compact = true,
+        onClick = onAbort,
+      )
+
+      Spacer(modifier = Modifier.weight(1f))
+
      Button(
        onClick = {
          val text = input
@@ -182,8 +167,9 @@ fun ChatComposer(
          onSend(text)
        },
        enabled = canSend,
-        modifier = Modifier.weight(1f).height(48.dp),
+        modifier = Modifier.height(44.dp),
        shape = RoundedCornerShape(14.dp),
+        contentPadding = PaddingValues(horizontal = 20.dp),
        colors =
          ButtonDefaults.buttonColors(
            containerColor = mobileAccent,
@@ -198,7 +184,7 @@ fun ChatComposer(
        } else {
          Icon(Icons.AutoMirrored.Filled.Send, contentDescription = null, modifier = Modifier.size(16.dp))
        }
-        Spacer(modifier = Modifier.width(8.dp))
+        Spacer(modifier = Modifier.width(6.dp))
        Text(
          text = "Send",
          style = mobileHeadline.copy(fontWeight = FontWeight.Bold),
@@ -151,7 +151,7 @@ fun ChatPendingToolsBubble(toolCalls: List<ChatPendingToolCall>) {

  ChatBubbleContainer(
    style = bubbleStyle("assistant"),
-    roleLabel = "TOOLS",
+    roleLabel = "Tools",
  ) {
    Column(verticalArrangement = Arrangement.spacedBy(4.dp)) {
      Text("Running tools...", style = mobileCaption1.copy(fontWeight = FontWeight.SemiBold), color = mobileTextSecondary)
@@ -188,7 +188,7 @@ fun ChatPendingToolsBubble(toolCalls: List<ChatPendingToolCall>) {
 fun ChatStreamingAssistantBubble(text: String) {
  ChatBubbleContainer(
    style = bubbleStyle("assistant").copy(borderColor = mobileAccent),
-    roleLabel = "ASSISTANT · LIVE",
+    roleLabel = "OpenClaw · Live",
  ) {
    ChatMarkdown(text = text, textColor = mobileText)
  }
@@ -224,9 +224,9 @@ private fun bubbleStyle(role: String): ChatBubbleStyle {

 private fun roleLabel(role: String): String {
  return when (role) {
-    "user" -> "USER"
-    "system" -> "SYSTEM"
-    else -> "ASSISTANT"
+    "user" -> "You"
+    "system" -> "System"
+    else -> "OpenClaw"
  }
 }

@@ -42,12 +42,8 @@ import ai.openclaw.app.ui.mobileCallout
 import ai.openclaw.app.ui.mobileCaption1
 import ai.openclaw.app.ui.mobileCaption2
 import ai.openclaw.app.ui.mobileDanger
-import ai.openclaw.app.ui.mobileSuccess
-import ai.openclaw.app.ui.mobileSuccessSoft
 import ai.openclaw.app.ui.mobileText
 import ai.openclaw.app.ui.mobileTextSecondary
-import ai.openclaw.app.ui.mobileWarning
-import ai.openclaw.app.ui.mobileWarningSoft
 import java.io.ByteArrayOutputStream
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.launch
@@ -106,7 +102,6 @@ fun ChatSheetContent(viewModel: MainViewModel) {
      sessionKey = sessionKey,
      sessions = sessions,
      mainSessionKey = mainSessionKey,
-      healthOk = healthOk,
      onSelectSession = { key -> viewModel.switchChatSession(key) },
    )

@@ -160,77 +155,34 @@ private fun ChatThreadSelector(
  sessionKey: String,
  sessions: List<ChatSessionEntry>,
  mainSessionKey: String,
-  healthOk: Boolean,
  onSelectSession: (String) -> Unit,
 ) {
  val sessionOptions = resolveSessionChoices(sessionKey, sessions, mainSessionKey = mainSessionKey)
-  val currentSessionLabel =
-    friendlySessionName(sessionOptions.firstOrNull { it.key == sessionKey }?.displayName ?: sessionKey)

-  Column(modifier = Modifier.fillMaxWidth(), verticalArrangement = Arrangement.spacedBy(8.dp)) {
-    Row(
-      modifier = Modifier.fillMaxWidth(),
-      horizontalArrangement = Arrangement.SpaceBetween,
-      verticalAlignment = androidx.compose.ui.Alignment.CenterVertically,
-    ) {
-      Text(
-        text = "SESSION",
-        style = mobileCaption1.copy(fontWeight = FontWeight.Bold, letterSpacing = 0.8.sp),
-        color = mobileTextSecondary,
-      )
-      Row(horizontalArrangement = Arrangement.spacedBy(6.dp), verticalAlignment = androidx.compose.ui.Alignment.CenterVertically) {
+  Row(
+    modifier = Modifier.fillMaxWidth().horizontalScroll(rememberScrollState()),
+    horizontalArrangement = Arrangement.spacedBy(8.dp),
+  ) {
+    for (entry in sessionOptions) {
+      val active = entry.key == sessionKey
+      Surface(
+        onClick = { onSelectSession(entry.key) },
+        shape = RoundedCornerShape(14.dp),
+        color = if (active) mobileAccent else Color.White,
+        border = BorderStroke(1.dp, if (active) Color(0xFF154CAD) else mobileBorderStrong),
+        tonalElevation = 0.dp,
+        shadowElevation = 0.dp,
+      ) {
        Text(
-          text = currentSessionLabel,
-          style = mobileCallout.copy(fontWeight = FontWeight.SemiBold),
-          color = mobileText,
+          text = friendlySessionName(entry.displayName ?: entry.key),
+          style = mobileCaption1.copy(fontWeight = if (active) FontWeight.Bold else FontWeight.SemiBold),
+          color = if (active) Color.White else mobileText,
          maxLines = 1,
          overflow = TextOverflow.Ellipsis,
+          modifier = Modifier.padding(horizontal = 12.dp, vertical = 8.dp),
        )
-        ChatConnectionPill(healthOk = healthOk)
      }
    }
-
-    Row(
-      modifier = Modifier.fillMaxWidth().horizontalScroll(rememberScrollState()),
-      horizontalArrangement = Arrangement.spacedBy(8.dp),
-    ) {
-      for (entry in sessionOptions) {
-        val active = entry.key == sessionKey
-        Surface(
-          onClick = { onSelectSession(entry.key) },
-          shape = RoundedCornerShape(14.dp),
-          color = if (active) mobileAccent else Color.White,
-          border = BorderStroke(1.dp, if (active) Color(0xFF154CAD) else mobileBorderStrong),
-          tonalElevation = 0.dp,
-          shadowElevation = 0.dp,
-        ) {
-          Text(
-            text = friendlySessionName(entry.displayName ?: entry.key),
-            style = mobileCaption1.copy(fontWeight = if (active) FontWeight.Bold else FontWeight.SemiBold),
-            color = if (active) Color.White else mobileText,
-            maxLines = 1,
-            overflow = TextOverflow.Ellipsis,
-            modifier = Modifier.padding(horizontal = 12.dp, vertical = 8.dp),
-          )
-        }
-      }
-    }
-  }
-}
-
-@Composable
-private fun ChatConnectionPill(healthOk: Boolean) {
-  Surface(
-    shape = RoundedCornerShape(999.dp),
-    color = if (healthOk) mobileSuccessSoft else mobileWarningSoft,
-    border = BorderStroke(1.dp, if (healthOk) mobileSuccess.copy(alpha = 0.35f) else mobileWarning.copy(alpha = 0.35f)),
-  ) {
-    Text(
-      text = if (healthOk) "Connected" else "Offline",
-      style = mobileCaption1.copy(fontWeight = FontWeight.SemiBold),
-      color = if (healthOk) mobileSuccess else mobileWarning,
-      modifier = Modifier.padding(horizontal = 8.dp, vertical = 3.dp),
-    )
  }
 }

@@ -79,26 +79,30 @@ internal object TalkModeVoiceResolver {
    return withContext(Dispatchers.IO) {
      val url = URL("https://api.elevenlabs.io/v1/voices")
      val conn = url.openConnection() as HttpURLConnection
-      conn.requestMethod = "GET"
-      conn.connectTimeout = 15_000
-      conn.readTimeout = 15_000
-      conn.setRequestProperty("xi-api-key", apiKey)
+      try {
+        conn.requestMethod = "GET"
+        conn.connectTimeout = 15_000
+        conn.readTimeout = 15_000
+        conn.setRequestProperty("xi-api-key", apiKey)

-      val code = conn.responseCode
-      val stream = if (code >= 400) conn.errorStream else conn.inputStream
-      val data = stream.readBytes()
-      if (code >= 400) {
-        val message = data.toString(Charsets.UTF_8)
-        throw IllegalStateException("ElevenLabs voices failed: $code $message")
-      }
+        val code = conn.responseCode
+        val stream = if (code >= 400) conn.errorStream else conn.inputStream
+        val data = stream?.use { it.readBytes() } ?: byteArrayOf()
+        if (code >= 400) {
+          val message = data.toString(Charsets.UTF_8)
+          throw IllegalStateException("ElevenLabs voices failed: $code $message")
+        }

-      val root = json.parseToJsonElement(data.toString(Charsets.UTF_8)).asObjectOrNull()
-      val voices = (root?.get("voices") as? JsonArray) ?: JsonArray(emptyList())
-      voices.mapNotNull { entry ->
-        val obj = entry.asObjectOrNull() ?: return@mapNotNull null
-        val voiceId = obj["voice_id"].asStringOrNull() ?: return@mapNotNull null
-        val name = obj["name"].asStringOrNull()
-        ElevenLabsVoice(voiceId, name)
+        val root = json.parseToJsonElement(data.toString(Charsets.UTF_8)).asObjectOrNull()
+        val voices = (root?.get("voices") as? JsonArray) ?: JsonArray(emptyList())
+        voices.mapNotNull { entry ->
+          val obj = entry.asObjectOrNull() ?: return@mapNotNull null
+          val voiceId = obj["voice_id"].asStringOrNull() ?: return@mapNotNull null
+          val name = obj["name"].asStringOrNull()
+          ElevenLabsVoice(voiceId, name)
+        }
+      } finally {
+        conn.disconnect()
      }
    }
  }
@@ -92,6 +92,30 @@ class GatewayConfigResolverTest {
    assertNull(resolved?.password?.takeIf { it.isNotEmpty() })
  }

+  @Test
+  fun resolveGatewayConnectConfigDefaultsPortlessWssSetupCodeTo443() {
+    val setupCode =
+      encodeSetupCode("""{"url":"wss://gateway.example","bootstrapToken":"bootstrap-1"}""")
+
+    val resolved =
+      resolveGatewayConnectConfig(
+        useSetupCode = true,
+        setupCode = setupCode,
+        manualHost = "",
+        manualPort = "",
+        manualTls = true,
+        fallbackToken = "shared-token",
+        fallbackPassword = "shared-password",
+      )
+
+    assertEquals("gateway.example", resolved?.host)
+    assertEquals(443, resolved?.port)
+    assertEquals(true, resolved?.tls)
+    assertEquals("bootstrap-1", resolved?.bootstrapToken)
+    assertNull(resolved?.token?.takeIf { it.isNotEmpty() })
+    assertNull(resolved?.password?.takeIf { it.isNotEmpty() })
+  }
+
  private fun encodeSetupCode(payloadJson: String): String {
    return Base64.getUrlEncoder().withoutPadding().encodeToString(payloadJson.toByteArray(Charsets.UTF_8))
  }
@@ -0,0 +1,125 @@
+#!/usr/bin/env bun
+
+import { $ } from "bun";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const scriptDir = dirname(fileURLToPath(import.meta.url));
+const androidDir = join(scriptDir, "..");
+const buildGradlePath = join(androidDir, "app", "build.gradle.kts");
+const bundlePath = join(androidDir, "app", "build", "outputs", "bundle", "release", "app-release.aab");
+
+type VersionState = {
+  versionName: string;
+  versionCode: number;
+};
+
+type ParsedVersionMatches = {
+  versionNameMatch: RegExpMatchArray;
+  versionCodeMatch: RegExpMatchArray;
+};
+
+function formatVersionName(date: Date): string {
+  const year = date.getFullYear();
+  const month = date.getMonth() + 1;
+  const day = date.getDate();
+  return `${year}.${month}.${day}`;
+}
+
+function formatVersionCodePrefix(date: Date): string {
+  const year = date.getFullYear().toString();
+  const month = (date.getMonth() + 1).toString().padStart(2, "0");
+  const day = date.getDate().toString().padStart(2, "0");
+  return `${year}${month}${day}`;
+}
+
+function parseVersionMatches(buildGradleText: string): ParsedVersionMatches {
+  const versionCodeMatch = buildGradleText.match(/versionCode = (\d+)/);
+  const versionNameMatch = buildGradleText.match(/versionName = "([^"]+)"/);
+  if (!versionCodeMatch || !versionNameMatch) {
+    throw new Error(`Couldn't parse versionName/versionCode from ${buildGradlePath}`);
+  }
+  return { versionCodeMatch, versionNameMatch };
+}
+
+function resolveNextVersionCode(currentVersionCode: number, todayPrefix: string): number {
+  const currentRaw = currentVersionCode.toString();
+  let nextSuffix = 0;
+
+  if (currentRaw.startsWith(todayPrefix)) {
+    const suffixRaw = currentRaw.slice(todayPrefix.length);
+    nextSuffix = (suffixRaw ? Number.parseInt(suffixRaw, 10) : 0) + 1;
+  }
+
+  if (!Number.isInteger(nextSuffix) || nextSuffix < 0 || nextSuffix > 99) {
+    throw new Error(
+      `Can't auto-bump Android versionCode for ${todayPrefix}: next suffix ${nextSuffix} is invalid`,
+    );
+  }
+
+  return Number.parseInt(`${todayPrefix}${nextSuffix.toString().padStart(2, "0")}`, 10);
+}
+
+function resolveNextVersion(buildGradleText: string, date: Date): VersionState {
+  const { versionCodeMatch } = parseVersionMatches(buildGradleText);
+  const currentVersionCode = Number.parseInt(versionCodeMatch[1] ?? "", 10);
+  if (!Number.isInteger(currentVersionCode)) {
+    throw new Error(`Invalid Android versionCode in ${buildGradlePath}`);
+  }
+
+  const versionName = formatVersionName(date);
+  const versionCode = resolveNextVersionCode(currentVersionCode, formatVersionCodePrefix(date));
+  return { versionName, versionCode };
+}
+
+function updateBuildGradleVersions(buildGradleText: string, nextVersion: VersionState): string {
+  return buildGradleText
+    .replace(/versionCode = \d+/, `versionCode = ${nextVersion.versionCode}`)
+    .replace(/versionName = "[^"]+"/, `versionName = "${nextVersion.versionName}"`);
+}
+
+async function sha256Hex(path: string): Promise<string> {
+  const buffer = await Bun.file(path).arrayBuffer();
+  const digest = await crypto.subtle.digest("SHA-256", buffer);
+  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+async function verifyBundleSignature(path: string): Promise<void> {
+  await $`jarsigner -verify ${path}`.quiet();
+}
+
+async function main() {
+  const buildGradleFile = Bun.file(buildGradlePath);
+  const originalText = await buildGradleFile.text();
+  const nextVersion = resolveNextVersion(originalText, new Date());
+  const updatedText = updateBuildGradleVersions(originalText, nextVersion);
+
+  if (updatedText === originalText) {
+    throw new Error("Android version bump produced no change");
+  }
+
+  console.log(`Android versionName -> ${nextVersion.versionName}`);
+  console.log(`Android versionCode -> ${nextVersion.versionCode}`);
+
+  await Bun.write(buildGradlePath, updatedText);
+
+  try {
+    await $`./gradlew :app:bundleRelease`.cwd(androidDir);
+  } catch (error) {
+    await Bun.write(buildGradlePath, originalText);
+    throw error;
+  }
+
+  const bundleFile = Bun.file(bundlePath);
+  if (!(await bundleFile.exists())) {
+    throw new Error(`Signed bundle missing at ${bundlePath}`);
+  }
+
+  await verifyBundleSignature(bundlePath);
+  const hash = await sha256Hex(bundlePath);
+
+  console.log(`Signed AAB: ${bundlePath}`);
+  console.log(`SHA-256: ${hash}`);
+}
+
+await main();
@@ -65,9 +65,9 @@ Release behavior:
 - Beta release also switches the app to `OpenClawPushTransport=relay`, `OpenClawPushDistribution=official`, and `OpenClawPushAPNsEnvironment=production`.
 - The beta flow does not modify `apps/ios/.local-signing.xcconfig` or `apps/ios/LocalSigning.xcconfig`.
 - Root `package.json.version` is the only version source for iOS.
- A root version like `2026.3.12-beta.1` becomes:
-  - `CFBundleShortVersionString = 2026.3.12`
-  - `CFBundleVersion = next TestFlight build number for 2026.3.12`
+- A root version like `2026.3.13-beta.1` becomes:
+  - `CFBundleShortVersionString = 2026.3.13`
+  - `CFBundleVersion = next TestFlight build number for 2026.3.13`

 Required env for beta builds:

@@ -189,6 +189,7 @@ final class ShareViewController: UIViewController {
            try await gateway.connect(
                url: url,
                token: config.token,
+                bootstrapToken: nil,
                password: config.password,
                connectOptions: makeOptions("openclaw-ios"),
                sessionBox: nil,
@@ -208,6 +209,7 @@ final class ShareViewController: UIViewController {
            try await gateway.connect(
                url: url,
                token: config.token,
+                bootstrapToken: nil,
                password: config.password,
                connectOptions: makeOptions("moltbot-ios"),
                sessionBox: nil,
@@ -19,6 +19,7 @@ enum OnboardingConnectionMode: String, CaseIterable {

 enum OnboardingStateStore {
    private static let completedDefaultsKey = "onboarding.completed"
+    private static let firstRunIntroSeenDefaultsKey = "onboarding.first_run_intro_seen"
    private static let lastModeDefaultsKey = "onboarding.last_mode"
    private static let lastSuccessTimeDefaultsKey = "onboarding.last_success_time"

@@ -39,10 +40,23 @@ enum OnboardingStateStore {
        defaults.set(Int(Date().timeIntervalSince1970), forKey: Self.lastSuccessTimeDefaultsKey)
    }

+    static func shouldPresentFirstRunIntro(defaults: UserDefaults = .standard) -> Bool {
+        !defaults.bool(forKey: Self.firstRunIntroSeenDefaultsKey)
+    }
+
+    static func markFirstRunIntroSeen(defaults: UserDefaults = .standard) {
+        defaults.set(true, forKey: Self.firstRunIntroSeenDefaultsKey)
+    }
+
    static func markIncomplete(defaults: UserDefaults = .standard) {
        defaults.set(false, forKey: Self.completedDefaultsKey)
    }

+    static func reset(defaults: UserDefaults = .standard) {
+        defaults.set(false, forKey: Self.completedDefaultsKey)
+        defaults.set(false, forKey: Self.firstRunIntroSeenDefaultsKey)
+    }
+
    static func lastMode(defaults: UserDefaults = .standard) -> OnboardingConnectionMode? {
        let raw = defaults.string(forKey: Self.lastModeDefaultsKey)?
            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
@@ -6,6 +6,7 @@ import SwiftUI
 import UIKit

 private enum OnboardingStep: Int, CaseIterable {
+    case intro
    case welcome
    case mode
    case connect
@@ -29,7 +30,8 @@ private enum OnboardingStep: Int, CaseIterable {

    var title: String {
        switch self {
-        case .welcome: "Welcome"
+        case .intro: "Welcome"
+        case .welcome: "Connect Gateway"
        case .mode: "Connection Mode"
        case .connect: "Connect"
        case .auth: "Authentication"
@@ -38,7 +40,7 @@ private enum OnboardingStep: Int, CaseIterable {
    }

    var canGoBack: Bool {
-        self != .welcome && self != .success
+        self != .intro && self != .welcome && self != .success
    }
 }

@@ -49,7 +51,7 @@ struct OnboardingWizardView: View {
    @AppStorage("node.instanceId") private var instanceId: String = UUID().uuidString
    @AppStorage("gateway.discovery.domain") private var discoveryDomain: String = ""
    @AppStorage("onboarding.developerMode") private var developerModeEnabled: Bool = false
-    @State private var step: OnboardingStep = .welcome
+    @State private var step: OnboardingStep
    @State private var selectedMode: OnboardingConnectionMode?
    @State private var manualHost: String = ""
    @State private var manualPort: Int = 18789
@@ -58,11 +60,10 @@ struct OnboardingWizardView: View {
    @State private var gatewayToken: String = ""
    @State private var gatewayPassword: String = ""
    @State private var connectMessage: String?
-    @State private var statusLine: String = "Scan the QR code from your gateway to connect."
+    @State private var statusLine: String = "In your OpenClaw chat, run /pair qr, then scan the code here."
    @State private var connectingGatewayID: String?
    @State private var issue: GatewayConnectionIssue = .none
    @State private var didMarkCompleted = false
-    @State private var didAutoPresentQR = false
    @State private var pairingRequestId: String?
    @State private var discoveryRestartTask: Task<Void, Never>?
    @State private var showQRScanner: Bool = false
@@ -74,14 +75,23 @@ struct OnboardingWizardView: View {
    let allowSkip: Bool
    let onClose: () -> Void

+    init(allowSkip: Bool, onClose: @escaping () -> Void) {
+        self.allowSkip = allowSkip
+        self.onClose = onClose
+        _step = State(
+            initialValue: OnboardingStateStore.shouldPresentFirstRunIntro() ? .intro : .welcome)
+    }
+
    private var isFullScreenStep: Bool {
-        self.step == .welcome || self.step == .success
+        self.step == .intro || self.step == .welcome || self.step == .success
    }

    var body: some View {
        NavigationStack {
            Group {
                switch self.step {
+                case .intro:
+                    self.introStep
                case .welcome:
                    self.welcomeStep
                case .success:
@@ -293,6 +303,83 @@ struct OnboardingWizardView: View {
        }
    }

+    @ViewBuilder
+    private var introStep: some View {
+        VStack(spacing: 0) {
+            Spacer()
+
+            Image(systemName: "iphone.gen3")
+                .font(.system(size: 60, weight: .semibold))
+                .foregroundStyle(.tint)
+                .padding(.bottom, 18)
+
+            Text("Welcome to OpenClaw")
+                .font(.largeTitle.weight(.bold))
+                .multilineTextAlignment(.center)
+                .padding(.bottom, 10)
+
+            Text("Turn this iPhone into a secure OpenClaw node for chat, voice, camera, and device tools.")
+                .font(.subheadline)
+                .foregroundStyle(.secondary)
+                .multilineTextAlignment(.center)
+                .padding(.horizontal, 32)
+                .padding(.bottom, 24)
+
+            VStack(alignment: .leading, spacing: 14) {
+                Label("Connect to your gateway", systemImage: "link")
+                Label("Choose device permissions", systemImage: "hand.raised")
+                Label("Use OpenClaw from your phone", systemImage: "message.fill")
+            }
+            .font(.subheadline.weight(.semibold))
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding(18)
+            .background {
+                RoundedRectangle(cornerRadius: 20, style: .continuous)
+                    .fill(Color(uiColor: .secondarySystemBackground))
+            }
+            .padding(.horizontal, 24)
+            .padding(.bottom, 16)
+
+            HStack(alignment: .top, spacing: 12) {
+                Image(systemName: "exclamationmark.triangle.fill")
+                    .font(.title3.weight(.semibold))
+                    .foregroundStyle(.orange)
+                    .frame(width: 24)
+                    .padding(.top, 2)
+
+                VStack(alignment: .leading, spacing: 6) {
+                    Text("Security notice")
+                        .font(.headline)
+                    Text(
+                        "The connected OpenClaw agent can use device capabilities you enable, such as camera, microphone, photos, contacts, calendar, and location. Continue only if you trust the gateway and agent you connect to.")
+                        .font(.footnote)
+                        .foregroundStyle(.secondary)
+                        .fixedSize(horizontal: false, vertical: true)
+                }
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding(18)
+            .background {
+                RoundedRectangle(cornerRadius: 20, style: .continuous)
+                    .fill(Color(uiColor: .secondarySystemBackground))
+            }
+            .padding(.horizontal, 24)
+
+            Spacer()
+
+            Button {
+                self.advanceFromIntro()
+            } label: {
+                Text("Continue")
+                    .frame(maxWidth: .infinity)
+            }
+            .buttonStyle(.borderedProminent)
+            .controlSize(.large)
+            .padding(.horizontal, 24)
+            .padding(.bottom, 48)
+        }
+    }
+
    @ViewBuilder
    private var welcomeStep: some View {
        VStack(spacing: 0) {
@@ -303,16 +390,37 @@ struct OnboardingWizardView: View {
                .foregroundStyle(.tint)
                .padding(.bottom, 20)

-            Text("Welcome")
+            Text("Connect Gateway")
                .font(.largeTitle.weight(.bold))
                .padding(.bottom, 8)

-            Text("Connect to your OpenClaw gateway")
+            Text("Scan a QR code from your OpenClaw gateway or continue with manual setup.")
                .font(.subheadline)
                .foregroundStyle(.secondary)
                .multilineTextAlignment(.center)
                .padding(.horizontal, 32)

+            VStack(alignment: .leading, spacing: 8) {
+                Text("How to pair")
+                    .font(.headline)
+                Text("In your OpenClaw chat, run")
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+                Text("/pair qr")
+                    .font(.system(.footnote, design: .monospaced).weight(.semibold))
+                Text("Then scan the QR code here to connect this iPhone.")
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding(16)
+            .background {
+                RoundedRectangle(cornerRadius: 18, style: .continuous)
+                    .fill(Color(uiColor: .secondarySystemBackground))
+            }
+            .padding(.horizontal, 24)
+            .padding(.top, 20)
+
            Spacer()

            VStack(spacing: 12) {
@@ -342,8 +450,7 @@ struct OnboardingWizardView: View {
                .foregroundStyle(.secondary)
                .multilineTextAlignment(.center)
                .padding(.horizontal, 24)
-            .padding(.horizontal, 24)
-            .padding(.bottom, 48)
+                .padding(.bottom, 48)
        }
    }

@@ -727,6 +834,12 @@ struct OnboardingWizardView: View {
        return nil
    }

+    private func advanceFromIntro() {
+        OnboardingStateStore.markFirstRunIntroSeen()
+        self.statusLine = "In your OpenClaw chat, run /pair qr, then scan the code here."
+        self.step = .welcome
+    }
+
    private func navigateBack() {
        guard let target = self.step.previous else { return }
        self.connectingGatewayID = nil
@@ -775,10 +888,8 @@ struct OnboardingWizardView: View {
        let hasSavedGateway = GatewaySettingsStore.loadLastGatewayConnection() != nil
        let hasToken = !self.gatewayToken.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
        let hasPassword = !self.gatewayPassword.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
-        if !self.didAutoPresentQR, !hasSavedGateway, !hasToken, !hasPassword {
-            self.didAutoPresentQR = true
-            self.statusLine = "No saved pairing found. Scan QR code to connect."
-            self.showQRScanner = true
+        if !hasSavedGateway, !hasToken, !hasPassword {
+            self.statusLine = "No saved pairing found. In your OpenClaw chat, run /pair qr, then scan the code here."
        }
    }

@@ -1008,6 +1008,7 @@ struct SettingsTab: View {

        // Reset onboarding state + clear saved gateway connection (the two things RootCanvas checks).
        GatewaySettingsStore.clearLastGatewayConnection()
+        OnboardingStateStore.reset()

        // RootCanvas also short-circuits onboarding when these are true.
        self.onboardingComplete = false
@@ -39,6 +39,35 @@ import Testing
        #expect(OnboardingStateStore.shouldPresentOnLaunch(appModel: appModel, defaults: defaults))
    }

+    @Test func firstRunIntroDefaultsToVisibleThenPersists() {
+        let testDefaults = self.makeDefaults()
+        let defaults = testDefaults.defaults
+        defer { self.reset(testDefaults) }
+
+        #expect(OnboardingStateStore.shouldPresentFirstRunIntro(defaults: defaults))
+
+        OnboardingStateStore.markFirstRunIntroSeen(defaults: defaults)
+        #expect(!OnboardingStateStore.shouldPresentFirstRunIntro(defaults: defaults))
+    }
+
+    @Test @MainActor func resetClearsCompletionAndIntroSeen() {
+        let testDefaults = self.makeDefaults()
+        let defaults = testDefaults.defaults
+        defer { self.reset(testDefaults) }
+
+        OnboardingStateStore.markCompleted(mode: .homeNetwork, defaults: defaults)
+        OnboardingStateStore.markFirstRunIntroSeen(defaults: defaults)
+
+        OnboardingStateStore.reset(defaults: defaults)
+
+        let appModel = NodeAppModel()
+        appModel.gatewayServerName = nil
+
+        #expect(OnboardingStateStore.shouldPresentOnLaunch(appModel: appModel, defaults: defaults))
+        #expect(OnboardingStateStore.shouldPresentFirstRunIntro(defaults: defaults))
+        #expect(OnboardingStateStore.lastMode(defaults: defaults) == .homeNetwork)
+    }
+
    private struct TestDefaults {
        var suiteName: String
        var defaults: UserDefaults
@@ -99,7 +99,7 @@ def normalize_release_version(raw_value)
  version = raw_value.to_s.strip.sub(/\Av/, "")
  UI.user_error!("Missing root package.json version.") unless env_present?(version)
  unless version.match?(/\A\d+\.\d+\.\d+(?:[.-]?beta[.-]\d+)?\z/i)
-    UI.user_error!("Invalid package.json version '#{raw_value}'. Expected 2026.3.12 or 2026.3.12-beta.1.")
+    UI.user_error!("Invalid package.json version '#{raw_value}'. Expected 2026.3.13 or 2026.3.13-beta.1.")
  end

  version
@@ -45,8 +45,8 @@ enum ExecApprovalEvaluator {

        let skillAllow: Bool
        if approvals.agent.autoAllowSkills, !allowlistResolutions.isEmpty {
-            let bins = await SkillBinsCache.shared.currentBins()
-            skillAllow = allowlistResolutions.allSatisfy { bins.contains($0.executableName) }
+            let bins = await SkillBinsCache.shared.currentTrust()
+            skillAllow = self.isSkillAutoAllowed(allowlistResolutions, trustedBinsByName: bins)
        } else {
            skillAllow = false
        }
@@ -65,4 +65,26 @@ enum ExecApprovalEvaluator {
            allowlistMatch: allowlistSatisfied ? allowlistMatches.first : nil,
            skillAllow: skillAllow)
    }
+
+    static func isSkillAutoAllowed(
+        _ resolutions: [ExecCommandResolution],
+        trustedBinsByName: [String: Set<String>]) -> Bool
+    {
+        guard !resolutions.isEmpty, !trustedBinsByName.isEmpty else { return false }
+        return resolutions.allSatisfy { resolution in
+            guard let executableName = SkillBinsCache.normalizeSkillBinName(resolution.executableName),
+                  let resolvedPath = SkillBinsCache.normalizeResolvedPath(resolution.resolvedPath)
+            else {
+                return false
+            }
+            return trustedBinsByName[executableName]?.contains(resolvedPath) == true
+        }
+    }
+
+    static func _testIsSkillAutoAllowed(
+        _ resolutions: [ExecCommandResolution],
+        trustedBinsByName: [String: Set<String>]) -> Bool
+    {
+        self.isSkillAutoAllowed(resolutions, trustedBinsByName: trustedBinsByName)
+    }
 }
@@ -370,6 +370,17 @@ enum ExecApprovalsStore {

    static func resolve(agentId: String?) -> ExecApprovalsResolved {
        let file = self.ensureFile()
+        return self.resolveFromFile(file, agentId: agentId)
+    }
+
+    /// Read-only resolve: loads file without writing (no ensureFile side effects).
+    /// Safe to call from background threads / off MainActor.
+    static func resolveReadOnly(agentId: String?) -> ExecApprovalsResolved {
+        let file = self.loadFile()
+        return self.resolveFromFile(file, agentId: agentId)
+    }
+
+    private static func resolveFromFile(_ file: ExecApprovalsFile, agentId: String?) -> ExecApprovalsResolved {
        let defaults = file.defaults ?? ExecApprovalsDefaults()
        let resolvedDefaults = ExecApprovalsResolvedDefaults(
            security: defaults.security ?? self.defaultSecurity,
@@ -777,6 +788,7 @@ actor SkillBinsCache {
    static let shared = SkillBinsCache()

    private var bins: Set<String> = []
+    private var trustByName: [String: Set<String>] = [:]
    private var lastRefresh: Date?
    private let refreshInterval: TimeInterval = 90

@@ -787,27 +799,90 @@ actor SkillBinsCache {
        return self.bins
    }

+    func currentTrust(force: Bool = false) async -> [String: Set<String>] {
+        if force || self.isStale() {
+            await self.refresh()
+        }
+        return self.trustByName
+    }
+
    func refresh() async {
        do {
            let report = try await GatewayConnection.shared.skillsStatus()
-            var next = Set<String>()
-            for skill in report.skills {
-                for bin in skill.requirements.bins {
-                    let trimmed = bin.trimmingCharacters(in: .whitespacesAndNewlines)
-                    if !trimmed.isEmpty { next.insert(trimmed) }
-                }
-            }
-            self.bins = next
+            let trust = Self.buildTrustIndex(report: report, searchPaths: CommandResolver.preferredPaths())
+            self.bins = trust.names
+            self.trustByName = trust.pathsByName
            self.lastRefresh = Date()
        } catch {
            if self.lastRefresh == nil {
                self.bins = []
+                self.trustByName = [:]
            }
        }
    }

+    static func normalizeSkillBinName(_ value: String) -> String? {
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    static func normalizeResolvedPath(_ value: String?) -> String? {
+        let trimmed = value?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !trimmed.isEmpty else { return nil }
+        return URL(fileURLWithPath: trimmed).standardizedFileURL.path
+    }
+
+    static func buildTrustIndex(
+        report: SkillsStatusReport,
+        searchPaths: [String]) -> SkillBinTrustIndex
+    {
+        var names = Set<String>()
+        var pathsByName: [String: Set<String>] = [:]
+
+        for skill in report.skills {
+            for bin in skill.requirements.bins {
+                let trimmed = bin.trimmingCharacters(in: .whitespacesAndNewlines)
+                guard !trimmed.isEmpty else { continue }
+                names.insert(trimmed)
+
+                guard let name = self.normalizeSkillBinName(trimmed),
+                      let resolvedPath = self.resolveSkillBinPath(trimmed, searchPaths: searchPaths),
+                      let normalizedPath = self.normalizeResolvedPath(resolvedPath)
+                else {
+                    continue
+                }
+
+                var paths = pathsByName[name] ?? Set<String>()
+                paths.insert(normalizedPath)
+                pathsByName[name] = paths
+            }
+        }
+
+        return SkillBinTrustIndex(names: names, pathsByName: pathsByName)
+    }
+
+    private static func resolveSkillBinPath(_ bin: String, searchPaths: [String]) -> String? {
+        let expanded = bin.hasPrefix("~") ? (bin as NSString).expandingTildeInPath : bin
+        if expanded.contains("/") || expanded.contains("\\") {
+            return FileManager().isExecutableFile(atPath: expanded) ? expanded : nil
+        }
+        return CommandResolver.findExecutable(named: expanded, searchPaths: searchPaths)
+    }
+
    private func isStale() -> Bool {
        guard let lastRefresh else { return true }
        return Date().timeIntervalSince(lastRefresh) > self.refreshInterval
    }
+
+    static func _testBuildTrustIndex(
+        report: SkillsStatusReport,
+        searchPaths: [String]) -> SkillBinTrustIndex
+    {
+        self.buildTrustIndex(report: report, searchPaths: searchPaths)
+    }
+}
+
+struct SkillBinTrustIndex {
+    let names: Set<String>
+    let pathsByName: [String: Set<String>]
 }
@@ -43,7 +43,33 @@ final class ExecApprovalsGatewayPrompter {
        do {
            let data = try JSONEncoder().encode(payload)
            let request = try JSONDecoder().decode(GatewayApprovalRequest.self, from: data)
-            guard self.shouldPresent(request: request) else { return }
+            let presentation = self.shouldPresent(request: request)
+            guard presentation.shouldAsk else {
+                // Ask policy says no prompt needed – resolve based on security policy
+                let decision: ExecApprovalDecision = presentation.security == .full ? .allowOnce : .deny
+                try await GatewayConnection.shared.requestVoid(
+                    method: .execApprovalResolve,
+                    params: [
+                        "id": AnyCodable(request.id),
+                        "decision": AnyCodable(decision.rawValue),
+                    ],
+                    timeoutMs: 10000)
+                return
+            }
+            guard presentation.canPresent else {
+                let decision = Self.fallbackDecision(
+                    request: request.request,
+                    askFallback: presentation.askFallback,
+                    allowlist: presentation.allowlist)
+                try await GatewayConnection.shared.requestVoid(
+                    method: .execApprovalResolve,
+                    params: [
+                        "id": AnyCodable(request.id),
+                        "decision": AnyCodable(decision.rawValue),
+                    ],
+                    timeoutMs: 10000)
+                return
+            }
            let decision = ExecApprovalsPromptPresenter.prompt(request.request)
            try await GatewayConnection.shared.requestVoid(
                method: .execApprovalResolve,
@@ -57,16 +83,89 @@ final class ExecApprovalsGatewayPrompter {
        }
    }

-    private func shouldPresent(request: GatewayApprovalRequest) -> Bool {
+    /// Whether the ask policy requires prompting the user.
+    /// Note: this only determines if a prompt is shown, not whether the action is allowed.
+    /// The security policy (full/deny/allowlist) decides the actual outcome.
+    private static func shouldAsk(security: ExecSecurity, ask: ExecAsk) -> Bool {
+        switch ask {
+        case .always:
+            return true
+        case .onMiss:
+            return security == .allowlist
+        case .off:
+            return false
+        }
+    }
+
+    struct PresentationDecision {
+        /// Whether the ask policy requires prompting the user (not whether the action is allowed).
+        var shouldAsk: Bool
+        /// Whether the prompt can actually be shown (session match, recent activity, etc.).
+        var canPresent: Bool
+        /// The resolved security policy, used to determine allow/deny when no prompt is shown.
+        var security: ExecSecurity
+        /// Fallback security policy when a prompt is needed but can't be presented.
+        var askFallback: ExecSecurity
+        var allowlist: [ExecAllowlistEntry]
+    }
+
+    private func shouldPresent(request: GatewayApprovalRequest) -> PresentationDecision {
        let mode = AppStateStore.shared.connectionMode
        let activeSession = WebChatManager.shared.activeSessionKey?.trimmingCharacters(in: .whitespacesAndNewlines)
        let requestSession = request.request.sessionKey?.trimmingCharacters(in: .whitespacesAndNewlines)
-        return Self.shouldPresent(
+        
+        // Read-only resolve to avoid disk writes on the MainActor
+        let approvals = ExecApprovalsStore.resolveReadOnly(agentId: request.request.agentId)
+        let security = approvals.agent.security
+        let ask = approvals.agent.ask
+        
+        let shouldAsk = Self.shouldAsk(security: security, ask: ask)
+        
+        let canPresent = shouldAsk && Self.shouldPresent(
            mode: mode,
            activeSession: activeSession,
            requestSession: requestSession,
            lastInputSeconds: Self.lastInputSeconds(),
            thresholdSeconds: 120)
+        
+        return PresentationDecision(
+            shouldAsk: shouldAsk,
+            canPresent: canPresent,
+            security: security,
+            askFallback: approvals.agent.askFallback,
+            allowlist: approvals.allowlist)
+    }
+
+    private static func fallbackDecision(
+        request: ExecApprovalPromptRequest,
+        askFallback: ExecSecurity,
+        allowlist: [ExecAllowlistEntry]) -> ExecApprovalDecision
+    {
+        guard askFallback == .allowlist else {
+            return askFallback == .full ? .allowOnce : .deny
+        }
+        let resolution = self.fallbackResolution(for: request)
+        let match = ExecAllowlistMatcher.match(entries: allowlist, resolution: resolution)
+        return match == nil ? .deny : .allowOnce
+    }
+
+    private static func fallbackResolution(for request: ExecApprovalPromptRequest) -> ExecCommandResolution? {
+        let resolvedPath = request.resolvedPath?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let trimmedResolvedPath = (resolvedPath?.isEmpty == false) ? resolvedPath : nil
+        let rawExecutable = self.firstToken(from: request.command) ?? trimmedResolvedPath ?? ""
+        guard !rawExecutable.isEmpty || trimmedResolvedPath != nil else { return nil }
+        let executableName = trimmedResolvedPath.map { URL(fileURLWithPath: $0).lastPathComponent } ?? rawExecutable
+        return ExecCommandResolution(
+            rawExecutable: rawExecutable,
+            resolvedPath: trimmedResolvedPath,
+            executableName: executableName,
+            cwd: request.cwd)
+    }
+
+    private static func firstToken(from command: String) -> String? {
+        let trimmed = command.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        return trimmed.split(whereSeparator: { $0.isWhitespace }).first.map(String.init)
    }

    private static func shouldPresent(
@@ -117,5 +216,29 @@ extension ExecApprovalsGatewayPrompter {
            lastInputSeconds: lastInputSeconds,
            thresholdSeconds: thresholdSeconds)
    }
+
+    static func _testShouldAsk(security: ExecSecurity, ask: ExecAsk) -> Bool {
+        self.shouldAsk(security: security, ask: ask)
+    }
+
+    static func _testFallbackDecision(
+        command: String,
+        resolvedPath: String?,
+        askFallback: ExecSecurity,
+        allowlistPatterns: [String]) -> ExecApprovalDecision
+    {
+        self.fallbackDecision(
+            request: ExecApprovalPromptRequest(
+                command: command,
+                cwd: nil,
+                host: nil,
+                security: nil,
+                ask: nil,
+                agentId: nil,
+                resolvedPath: resolvedPath,
+                sessionKey: nil),
+            askFallback: askFallback,
+            allowlist: allowlistPatterns.map { ExecAllowlistEntry(pattern: $0) })
+    }
 }
 #endif
@@ -37,8 +37,7 @@ struct ExecCommandResolution {
            var resolutions: [ExecCommandResolution] = []
            resolutions.reserveCapacity(segments.count)
            for segment in segments {
-                guard let token = self.parseFirstToken(segment),
-                      let resolution = self.resolveExecutable(rawExecutable: token, cwd: cwd, env: env)
+                guard let resolution = self.resolveShellSegmentExecutable(segment, cwd: cwd, env: env)
                else {
                    return []
                }
@@ -88,6 +87,20 @@ struct ExecCommandResolution {
            cwd: cwd)
    }

+    private static func resolveShellSegmentExecutable(
+        _ segment: String,
+        cwd: String?,
+        env: [String: String]?) -> ExecCommandResolution?
+    {
+        let tokens = self.tokenizeShellWords(segment)
+        guard !tokens.isEmpty else { return nil }
+        let effective = ExecEnvInvocationUnwrapper.unwrapDispatchWrappersForResolution(tokens)
+        guard let raw = effective.first?.trimmingCharacters(in: .whitespacesAndNewlines), !raw.isEmpty else {
+            return nil
+        }
+        return self.resolveExecutable(rawExecutable: raw, cwd: cwd, env: env)
+    }
+
    private static func parseFirstToken(_ command: String) -> String? {
        let trimmed = command.trimmingCharacters(in: .whitespacesAndNewlines)
        guard !trimmed.isEmpty else { return nil }
@@ -102,6 +115,59 @@ struct ExecCommandResolution {
        return trimmed.split(whereSeparator: { $0.isWhitespace }).first.map(String.init)
    }

+    private static func tokenizeShellWords(_ command: String) -> [String] {
+        let trimmed = command.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return [] }
+
+        var tokens: [String] = []
+        var current = ""
+        var inSingle = false
+        var inDouble = false
+        var escaped = false
+
+        func appendCurrent() {
+            guard !current.isEmpty else { return }
+            tokens.append(current)
+            current.removeAll(keepingCapacity: true)
+        }
+
+        for ch in trimmed {
+            if escaped {
+                current.append(ch)
+                escaped = false
+                continue
+            }
+
+            if ch == "\\", !inSingle {
+                escaped = true
+                continue
+            }
+
+            if ch == "'", !inDouble {
+                inSingle.toggle()
+                continue
+            }
+
+            if ch == "\"", !inSingle {
+                inDouble.toggle()
+                continue
+            }
+
+            if ch.isWhitespace, !inSingle, !inDouble {
+                appendCurrent()
+                continue
+            }
+
+            current.append(ch)
+        }
+
+        if escaped {
+            current.append("\\")
+        }
+        appendCurrent()
+        return tokens
+    }
+
    private enum ShellTokenContext {
        case unquoted
        case doubleQuoted
@@ -148,8 +214,14 @@ struct ExecCommandResolution {
        while idx < chars.count {
            let ch = chars[idx]
            let next: Character? = idx + 1 < chars.count ? chars[idx + 1] : nil
+            let lookahead = self.nextShellSignificantCharacter(chars: chars, after: idx, inSingle: inSingle)

            if escaped {
+                if ch == "\n" {
+                    escaped = false
+                    idx += 1
+                    continue
+                }
                current.append(ch)
                escaped = false
                idx += 1
@@ -157,6 +229,10 @@ struct ExecCommandResolution {
            }

            if ch == "\\", !inSingle {
+                if next == "\n" {
+                    idx += 2
+                    continue
+                }
                current.append(ch)
                escaped = true
                idx += 1
@@ -177,7 +253,7 @@ struct ExecCommandResolution {
                continue
            }

-            if !inSingle, self.shouldFailClosedForShell(ch: ch, next: next, inDouble: inDouble) {
+            if !inSingle, self.shouldFailClosedForShell(ch: ch, next: lookahead, inDouble: inDouble) {
                // Fail closed on command/process substitution in allowlist mode,
                // including command substitution inside double-quoted shell strings.
                return nil
@@ -201,6 +277,25 @@ struct ExecCommandResolution {
        return segments
    }

+    private static func nextShellSignificantCharacter(
+        chars: [Character],
+        after idx: Int,
+        inSingle: Bool) -> Character?
+    {
+        guard !inSingle else {
+            return idx + 1 < chars.count ? chars[idx + 1] : nil
+        }
+        var cursor = idx + 1
+        while cursor < chars.count {
+            if chars[cursor] == "\\", cursor + 1 < chars.count, chars[cursor + 1] == "\n" {
+                cursor += 2
+                continue
+            }
+            return chars[cursor]
+        }
+        return nil
+    }
+
    private static func shouldFailClosedForShell(ch: Character, next: Character?, inDouble: Bool) -> Bool {
        let context: ShellTokenContext = inDouble ? .doubleQuoted : .unquoted
        guard let rules = self.shellFailClosedRules[context] else {
@@ -47,7 +47,7 @@ actor PortGuardian {
            let listeners = await self.listeners(on: port)
            guard !listeners.isEmpty else { continue }
            for listener in listeners {
-                if self.isExpected(listener, port: port, mode: mode) {
+                if Self.isExpected(listener, port: port, mode: mode) {
                    let message = """
                    port \(port) already served by expected \(listener.command)
                    (pid \(listener.pid)) — keeping
@@ -55,6 +55,14 @@ actor PortGuardian {
                    self.logger.info("\(message, privacy: .public)")
                    continue
                }
+                if mode == .remote {
+                    let message = """
+                    port \(port) held by \(listener.command)
+                    (pid \(listener.pid)) in remote mode — not killing
+                    """
+                    self.logger.warning(message)
+                    continue
+                }
                let killed = await self.kill(listener.pid)
                if killed {
                    let message = """
@@ -271,8 +279,8 @@ actor PortGuardian {

        switch mode {
        case .remote:
-            expectedDesc = "SSH tunnel to remote gateway"
-            okPredicate = { $0.command.lowercased().contains("ssh") }
+            expectedDesc = "Remote gateway (SSH tunnel, Docker, or direct)"
+            okPredicate = { _ in true }
        case .local:
            expectedDesc = "Gateway websocket (node/tsx)"
            okPredicate = { listener in
@@ -352,13 +360,12 @@ actor PortGuardian {
        return sigkill.ok
    }

-    private func isExpected(_ listener: Listener, port: Int, mode: AppState.ConnectionMode) -> Bool {
+    private static func isExpected(_ listener: Listener, port: Int, mode: AppState.ConnectionMode) -> Bool {
        let cmd = listener.command.lowercased()
        let full = listener.fullCommand.lowercased()
        switch mode {
        case .remote:
-            // Remote mode expects an SSH tunnel for the gateway WebSocket port.
-            if port == GatewayEnvironment.gatewayPort() { return cmd.contains("ssh") }
+            if port == GatewayEnvironment.gatewayPort() { return true }
            return false
        case .local:
            // The gateway daemon may listen as `openclaw` or as its runtime (`node`, `bun`, etc).
@@ -406,6 +413,16 @@ extension PortGuardian {
        self.parseListeners(from: text).map { ($0.pid, $0.command, $0.fullCommand, $0.user) }
    }

+    static func _testIsExpected(
+        command: String,
+        fullCommand: String,
+        port: Int,
+        mode: AppState.ConnectionMode) -> Bool
+    {
+        let listener = Listener(pid: 0, command: command, fullCommand: fullCommand, user: nil)
+        return Self.isExpected(listener, port: port, mode: mode)
+    }
+
    static func _testBuildReport(
        port: Int,
        mode: AppState.ConnectionMode,
@@ -15,9 +15,9 @@
    <key>CFBundlePackageType</key>
    <string>APPL</string>
    <key>CFBundleShortVersionString</key>
-    <string>2026.3.12</string>
+    <string>2026.3.13</string>
    <key>CFBundleVersion</key>
-    <string>202603120</string>
+    <string>202603130</string>
    <key>CFBundleIconFile</key>
    <string>OpenClaw</string>
    <key>CFBundleURLTypes</key>
@@ -54,7 +54,7 @@ enum RuntimeResolutionError: Error {

 enum RuntimeLocator {
    private static let logger = Logger(subsystem: "ai.openclaw", category: "runtime")
-    private static let minNode = RuntimeVersion(major: 22, minor: 0, patch: 0)
+    private static let minNode = RuntimeVersion(major: 22, minor: 16, patch: 0)

    static func resolve(
        searchPaths: [String] = CommandResolver.preferredPaths()) -> Result<RuntimeResolution, RuntimeResolutionError>
@@ -91,7 +91,7 @@ enum RuntimeLocator {
        switch error {
        case let .notFound(searchPaths):
            [
-                "openclaw needs Node >=22.0.0 but found no runtime.",
+                "openclaw needs Node >=22.16.0 but found no runtime.",
                "PATH searched: \(searchPaths.joined(separator: ":"))",
                "Install Node: https://nodejs.org/en/download",
            ].joined(separator: "\n")
@@ -105,7 +105,7 @@ enum RuntimeLocator {
            [
                "Could not parse \(kind.rawValue) version output \"\(raw)\" from \(path).",
                "PATH searched: \(searchPaths.joined(separator: ":"))",
-                "Try reinstalling or pinning a supported version (Node >=22.0.0).",
+                "Try reinstalling or pinning a supported version (Node >=22.16.0).",
            ].joined(separator: "\n")
        }
    }
@@ -141,6 +141,26 @@ struct ExecAllowlistTests {
        #expect(resolutions.isEmpty)
    }

+    @Test func `resolve for allowlist fails closed on line-continued command substitution`() {
+        let command = ["/bin/sh", "-lc", "echo $\\\n(/usr/bin/touch /tmp/openclaw-allowlist-test-line-cont-subst)"]
+        let resolutions = ExecCommandResolution.resolveForAllowlist(
+            command: command,
+            rawCommand: "echo $\\\n(/usr/bin/touch /tmp/openclaw-allowlist-test-line-cont-subst)",
+            cwd: nil,
+            env: ["PATH": "/usr/bin:/bin"])
+        #expect(resolutions.isEmpty)
+    }
+
+    @Test func `resolve for allowlist fails closed on chained line-continued command substitution`() {
+        let command = ["/bin/sh", "-lc", "echo ok && $\\\n(/usr/bin/touch /tmp/openclaw-allowlist-test-chained-line-cont-subst)"]
+        let resolutions = ExecCommandResolution.resolveForAllowlist(
+            command: command,
+            rawCommand: "echo ok && $\\\n(/usr/bin/touch /tmp/openclaw-allowlist-test-chained-line-cont-subst)",
+            cwd: nil,
+            env: ["PATH": "/usr/bin:/bin"])
+        #expect(resolutions.isEmpty)
+    }
+
    @Test func `resolve for allowlist fails closed on quoted backticks`() {
        let command = ["/bin/sh", "-lc", "echo \"ok `/usr/bin/id`\""]
        let resolutions = ExecCommandResolution.resolveForAllowlist(
@@ -208,6 +228,30 @@ struct ExecAllowlistTests {
        #expect(resolutions[1].executableName == "touch")
    }

+    @Test func `resolve for allowlist unwraps env dispatch wrappers inside shell segments`() {
+        let command = ["/bin/sh", "-lc", "env /usr/bin/touch /tmp/openclaw-allowlist-test"]
+        let resolutions = ExecCommandResolution.resolveForAllowlist(
+            command: command,
+            rawCommand: "env /usr/bin/touch /tmp/openclaw-allowlist-test",
+            cwd: nil,
+            env: ["PATH": "/usr/bin:/bin"])
+        #expect(resolutions.count == 1)
+        #expect(resolutions[0].resolvedPath == "/usr/bin/touch")
+        #expect(resolutions[0].executableName == "touch")
+    }
+
+    @Test func `resolve for allowlist unwraps env assignments inside shell segments`() {
+        let command = ["/bin/sh", "-lc", "env FOO=bar /usr/bin/touch /tmp/openclaw-allowlist-test"]
+        let resolutions = ExecCommandResolution.resolveForAllowlist(
+            command: command,
+            rawCommand: "env FOO=bar /usr/bin/touch /tmp/openclaw-allowlist-test",
+            cwd: nil,
+            env: ["PATH": "/usr/bin:/bin"])
+        #expect(resolutions.count == 1)
+        #expect(resolutions[0].resolvedPath == "/usr/bin/touch")
+        #expect(resolutions[0].executableName == "touch")
+    }
+
    @Test func `resolve for allowlist unwraps env to effective direct executable`() {
        let command = ["/usr/bin/env", "FOO=bar", "/usr/bin/printf", "ok"]
        let resolutions = ExecCommandResolution.resolveForAllowlist(
@@ -52,4 +52,51 @@ struct ExecApprovalsGatewayPrompterTests {
            lastInputSeconds: 400)
        #expect(!remote)
    }
+
+    // MARK: - shouldAsk
+
+    @Test func askAlwaysPromptsRegardlessOfSecurity() {
+        #expect(ExecApprovalsGatewayPrompter._testShouldAsk(security: .deny, ask: .always))
+        #expect(ExecApprovalsGatewayPrompter._testShouldAsk(security: .allowlist, ask: .always))
+        #expect(ExecApprovalsGatewayPrompter._testShouldAsk(security: .full, ask: .always))
+    }
+
+    @Test func askOnMissPromptsOnlyForAllowlist() {
+        #expect(ExecApprovalsGatewayPrompter._testShouldAsk(security: .allowlist, ask: .onMiss))
+        #expect(!ExecApprovalsGatewayPrompter._testShouldAsk(security: .deny, ask: .onMiss))
+        #expect(!ExecApprovalsGatewayPrompter._testShouldAsk(security: .full, ask: .onMiss))
+    }
+
+    @Test func askOffNeverPrompts() {
+        #expect(!ExecApprovalsGatewayPrompter._testShouldAsk(security: .deny, ask: .off))
+        #expect(!ExecApprovalsGatewayPrompter._testShouldAsk(security: .allowlist, ask: .off))
+        #expect(!ExecApprovalsGatewayPrompter._testShouldAsk(security: .full, ask: .off))
+    }
+
+    @Test func fallbackAllowlistAllowsMatchingResolvedPath() {
+        let decision = ExecApprovalsGatewayPrompter._testFallbackDecision(
+            command: "git status",
+            resolvedPath: "/usr/bin/git",
+            askFallback: .allowlist,
+            allowlistPatterns: ["/usr/bin/git"])
+        #expect(decision == .allowOnce)
+    }
+
+    @Test func fallbackAllowlistDeniesAllowlistMiss() {
+        let decision = ExecApprovalsGatewayPrompter._testFallbackDecision(
+            command: "git status",
+            resolvedPath: "/usr/bin/git",
+            askFallback: .allowlist,
+            allowlistPatterns: ["/usr/bin/rg"])
+        #expect(decision == .deny)
+    }
+
+    @Test func fallbackFullAllowsWhenPromptCannotBeShown() {
+        let decision = ExecApprovalsGatewayPrompter._testFallbackDecision(
+            command: "git status",
+            resolvedPath: "/usr/bin/git",
+            askFallback: .full,
+            allowlistPatterns: [])
+        #expect(decision == .allowOnce)
+    }
 }
@@ -0,0 +1,90 @@
+import Foundation
+import Testing
+@testable import OpenClaw
+
+struct ExecSkillBinTrustTests {
+    @Test func `build trust index resolves skill bin paths`() throws {
+        let fixture = try Self.makeExecutable(named: "jq")
+        defer { try? FileManager.default.removeItem(at: fixture.root) }
+
+        let trust = SkillBinsCache._testBuildTrustIndex(
+            report: Self.makeReport(bins: ["jq"]),
+            searchPaths: [fixture.root.path])
+
+        #expect(trust.names == ["jq"])
+        #expect(trust.pathsByName["jq"] == [fixture.path])
+    }
+
+    @Test func `skill auto allow accepts trusted resolved skill bin path`() throws {
+        let fixture = try Self.makeExecutable(named: "jq")
+        defer { try? FileManager.default.removeItem(at: fixture.root) }
+
+        let trust = SkillBinsCache._testBuildTrustIndex(
+            report: Self.makeReport(bins: ["jq"]),
+            searchPaths: [fixture.root.path])
+        let resolution = ExecCommandResolution(
+            rawExecutable: "jq",
+            resolvedPath: fixture.path,
+            executableName: "jq",
+            cwd: nil)
+
+        #expect(ExecApprovalEvaluator._testIsSkillAutoAllowed([resolution], trustedBinsByName: trust.pathsByName))
+    }
+
+    @Test func `skill auto allow rejects same basename at different path`() throws {
+        let trusted = try Self.makeExecutable(named: "jq")
+        let untrusted = try Self.makeExecutable(named: "jq")
+        defer {
+            try? FileManager.default.removeItem(at: trusted.root)
+            try? FileManager.default.removeItem(at: untrusted.root)
+        }
+
+        let trust = SkillBinsCache._testBuildTrustIndex(
+            report: Self.makeReport(bins: ["jq"]),
+            searchPaths: [trusted.root.path])
+        let resolution = ExecCommandResolution(
+            rawExecutable: "jq",
+            resolvedPath: untrusted.path,
+            executableName: "jq",
+            cwd: nil)
+
+        #expect(!ExecApprovalEvaluator._testIsSkillAutoAllowed([resolution], trustedBinsByName: trust.pathsByName))
+    }
+
+    private static func makeExecutable(named name: String) throws -> (root: URL, path: String) {
+        let root = FileManager.default.temporaryDirectory
+            .appendingPathComponent("openclaw-skill-bin-\(UUID().uuidString)", isDirectory: true)
+        try FileManager.default.createDirectory(at: root, withIntermediateDirectories: true)
+        let file = root.appendingPathComponent(name)
+        try "#!/bin/sh\nexit 0\n".write(to: file, atomically: true, encoding: .utf8)
+        try FileManager.default.setAttributes(
+            [.posixPermissions: NSNumber(value: Int16(0o755))],
+            ofItemAtPath: file.path)
+        return (root, file.path)
+    }
+
+    private static func makeReport(bins: [String]) -> SkillsStatusReport {
+        SkillsStatusReport(
+            workspaceDir: "/tmp/workspace",
+            managedSkillsDir: "/tmp/skills",
+            skills: [
+                SkillStatus(
+                    name: "test-skill",
+                    description: "test",
+                    source: "local",
+                    filePath: "/tmp/skills/test-skill/SKILL.md",
+                    baseDir: "/tmp/skills/test-skill",
+                    skillKey: "test-skill",
+                    primaryEnv: nil,
+                    emoji: nil,
+                    homepage: nil,
+                    always: false,
+                    disabled: false,
+                    eligible: true,
+                    requirements: SkillRequirements(bins: bins, env: [], config: []),
+                    missing: SkillMissing(bins: [], env: [], config: []),
+                    configChecks: [],
+                    install: [])
+            ])
+    }
+}
@@ -139,6 +139,54 @@ struct LowCoverageHelperTests {
        #expect(emptyReport.summary.contains("Nothing is listening"))
    }

+    @Test func `port guardian remote mode does not kill docker`() {
+        #expect(PortGuardian._testIsExpected(
+            command: "com.docker.backend",
+            fullCommand: "com.docker.backend",
+            port: 18789, mode: .remote) == true)
+
+        #expect(PortGuardian._testIsExpected(
+            command: "ssh",
+            fullCommand: "ssh -L 18789:localhost:18789 user@host",
+            port: 18789, mode: .remote) == true)
+
+        #expect(PortGuardian._testIsExpected(
+            command: "podman",
+            fullCommand: "podman",
+            port: 18789, mode: .remote) == true)
+    }
+
+    @Test func `port guardian local mode still rejects unexpected`() {
+        #expect(PortGuardian._testIsExpected(
+            command: "com.docker.backend",
+            fullCommand: "com.docker.backend",
+            port: 18789, mode: .local) == false)
+
+        #expect(PortGuardian._testIsExpected(
+            command: "python",
+            fullCommand: "python server.py",
+            port: 18789, mode: .local) == false)
+
+        #expect(PortGuardian._testIsExpected(
+            command: "node",
+            fullCommand: "node /path/to/gateway-daemon",
+            port: 18789, mode: .local) == true)
+    }
+
+    @Test func `port guardian remote mode report accepts any listener`() {
+        let dockerReport = PortGuardian._testBuildReport(
+            port: 18789, mode: .remote,
+            listeners: [(pid: 99, command: "com.docker.backend",
+                         fullCommand: "com.docker.backend", user: "me")])
+        #expect(dockerReport.offenders.isEmpty)
+
+        let localDockerReport = PortGuardian._testBuildReport(
+            port: 18789, mode: .local,
+            listeners: [(pid: 99, command: "com.docker.backend",
+                         fullCommand: "com.docker.backend", user: "me")])
+        #expect(!localDockerReport.offenders.isEmpty)
+    }
+
    @Test @MainActor func `canvas scheme handler resolves files and errors`() throws {
        let root = FileManager().temporaryDirectory
            .appendingPathComponent("canvas-\(UUID().uuidString)", isDirectory: true)
@@ -16,7 +16,7 @@ struct RuntimeLocatorTests {
    @Test func `resolve succeeds with valid node`() throws {
        let script = """
        #!/bin/sh
-        echo v22.5.0
+        echo v22.16.0
        """
        let node = try self.makeTempExecutable(contents: script)
        let result = RuntimeLocator.resolve(searchPaths: [node.deletingLastPathComponent().path])
@@ -25,7 +25,23 @@ struct RuntimeLocatorTests {
            return
        }
        #expect(res.path == node.path)
-        #expect(res.version == RuntimeVersion(major: 22, minor: 5, patch: 0))
+        #expect(res.version == RuntimeVersion(major: 22, minor: 16, patch: 0))
+    }
+
+    @Test func `resolve fails on boundary below minimum`() throws {
+        let script = """
+        #!/bin/sh
+        echo v22.15.9
+        """
+        let node = try self.makeTempExecutable(contents: script)
+        let result = RuntimeLocator.resolve(searchPaths: [node.deletingLastPathComponent().path])
+        guard case let .failure(.unsupported(_, found, required, path, _)) = result else {
+            Issue.record("Expected unsupported error, got \(result)")
+            return
+        }
+        #expect(found == RuntimeVersion(major: 22, minor: 15, patch: 9))
+        #expect(required == RuntimeVersion(major: 22, minor: 16, patch: 0))
+        #expect(path == node.path)
    }

    @Test func `resolve fails when too old`() throws {
@@ -60,7 +76,17 @@ struct RuntimeLocatorTests {

    @Test func `describe failure includes paths`() {
        let msg = RuntimeLocator.describeFailure(.notFound(searchPaths: ["/tmp/a", "/tmp/b"]))
+        #expect(msg.contains("Node >=22.16.0"))
        #expect(msg.contains("PATH searched: /tmp/a:/tmp/b"))
+
+        let parseMsg = RuntimeLocator.describeFailure(
+            .versionParse(
+                kind: .node,
+                raw: "garbage",
+                path: "/usr/local/bin/node",
+                searchPaths: ["/usr/local/bin"],
+            ))
+        #expect(parseMsg.contains("Node >=22.16.0"))
    }

    @Test func `runtime version parses with leading V and metadata`() {
@@ -74,4 +74,22 @@ struct VoiceWakeRuntimeTests {
        let config = WakeWordGateConfig(triggers: ["openclaw"], minPostTriggerGap: 0.3)
        #expect(WakeWordGate.match(transcript: transcript, segments: segments, config: config)?.command == "do thing")
    }
+
+    @Test func `gate command text handles foreign string ranges`() {
+        let transcript = "hey openclaw do thing"
+        let other = "do thing"
+        let foreignRange = other.range(of: "do")
+        let segments = [
+            WakeWordSegment(text: "hey", start: 0.0, duration: 0.1, range: transcript.range(of: "hey")),
+            WakeWordSegment(text: "openclaw", start: 0.2, duration: 0.1, range: transcript.range(of: "openclaw")),
+            WakeWordSegment(text: "do", start: 0.9, duration: 0.1, range: foreignRange),
+            WakeWordSegment(text: "thing", start: 1.1, duration: 0.1, range: nil),
+        ]
+
+        #expect(
+            WakeWordGate.commandText(
+                transcript: transcript,
+                segments: segments,
+                triggerEndTime: 0.3) == "do thing")
+    }
 }
@@ -0,0 +1 @@
+- tests: align OpenAI Codex auth login expectations with the `gpt-5.4` default model to prevent stale CI failures. (#44367) thanks @jrrcdev
@@ -9,6 +9,7 @@ services:
      CLAUDE_AI_SESSION_KEY: ${CLAUDE_AI_SESSION_KEY:-}
      CLAUDE_WEB_SESSION_KEY: ${CLAUDE_WEB_SESSION_KEY:-}
      CLAUDE_WEB_COOKIE: ${CLAUDE_WEB_COOKIE:-}
+      TZ: ${OPENCLAW_TZ:-UTC}
    volumes:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
@@ -65,6 +66,7 @@ services:
      CLAUDE_AI_SESSION_KEY: ${CLAUDE_AI_SESSION_KEY:-}
      CLAUDE_WEB_SESSION_KEY: ${CLAUDE_WEB_SESSION_KEY:-}
      CLAUDE_WEB_COOKIE: ${CLAUDE_WEB_COOKIE:-}
+      TZ: ${OPENCLAW_TZ:-UTC}
    volumes:
      - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw
      - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace
@@ -10,6 +10,7 @@ HOME_VOLUME_NAME="${OPENCLAW_HOME_VOLUME:-}"
 RAW_SANDBOX_SETTING="${OPENCLAW_SANDBOX:-}"
 SANDBOX_ENABLED=""
 DOCKER_SOCKET_PATH="${OPENCLAW_DOCKER_SOCKET:-}"
+TIMEZONE="${OPENCLAW_TZ:-}"

 fail() {
  echo "ERROR: $*" >&2
@@ -135,6 +136,11 @@ contains_disallowed_chars() {
  [[ "$value" == *$'\n'* || "$value" == *$'\r'* || "$value" == *$'\t'* ]]
 }

+is_valid_timezone() {
+  local value="$1"
+  [[ -e "/usr/share/zoneinfo/$value" && ! -d "/usr/share/zoneinfo/$value" ]]
+}
+
 validate_mount_path_value() {
  local label="$1"
  local value="$2"
@@ -202,6 +208,17 @@ fi
 if [[ -n "$SANDBOX_ENABLED" ]]; then
  validate_mount_path_value "OPENCLAW_DOCKER_SOCKET" "$DOCKER_SOCKET_PATH"
 fi
+if [[ -n "$TIMEZONE" ]]; then
+  if contains_disallowed_chars "$TIMEZONE"; then
+    fail "OPENCLAW_TZ contains unsupported control characters."
+  fi
+  if [[ ! "$TIMEZONE" =~ ^[A-Za-z0-9/_+\-]+$ ]]; then
+    fail "OPENCLAW_TZ must be a valid IANA timezone string (e.g. Asia/Shanghai)."
+  fi
+  if ! is_valid_timezone "$TIMEZONE"; then
+    fail "OPENCLAW_TZ must match a timezone in /usr/share/zoneinfo (e.g. Asia/Shanghai)."
+  fi
+fi

 mkdir -p "$OPENCLAW_CONFIG_DIR"
 mkdir -p "$OPENCLAW_WORKSPACE_DIR"
@@ -224,6 +241,7 @@ export OPENCLAW_HOME_VOLUME="$HOME_VOLUME_NAME"
 export OPENCLAW_ALLOW_INSECURE_PRIVATE_WS="${OPENCLAW_ALLOW_INSECURE_PRIVATE_WS:-}"
 export OPENCLAW_SANDBOX="$SANDBOX_ENABLED"
 export OPENCLAW_DOCKER_SOCKET="$DOCKER_SOCKET_PATH"
+export OPENCLAW_TZ="$TIMEZONE"

 # Detect Docker socket GID for sandbox group_add.
 DOCKER_GID=""
@@ -408,7 +426,8 @@ upsert_env "$ENV_FILE" \
  OPENCLAW_DOCKER_SOCKET \
  DOCKER_GID \
  OPENCLAW_INSTALL_DOCKER_CLI \
-  OPENCLAW_ALLOW_INSECURE_PRIVATE_WS
+  OPENCLAW_ALLOW_INSECURE_PRIVATE_WS \
+  OPENCLAW_TZ

 if [[ "$IMAGE_NAME" == "openclaw:local" ]]; then
  echo "==> Building Docker image: $IMAGE_NAME"
@@ -73,7 +73,7 @@ await web_search({
 ## Notes

 - OpenClaw uses the Brave **Search** plan. If you have a legacy subscription (e.g. the original Free plan with 2,000 queries/month), it remains valid but does not include newer features like LLM Context or higher rate limits.
- Each Brave plan includes **$5/month in free credit** (renewing). The Search plan costs $5 per 1,000 requests, so the credit covers 1,000 queries/month. Set your usage limit in the Brave dashboard to avoid unexpected charges. See the [Brave API portal](https://brave.com/search/api/) for current plans.
+- Each Brave plan includes **\$5/month in free credit** (renewing). The Search plan costs \$5 per 1,000 requests, so the credit covers 1,000 queries/month. Set your usage limit in the Brave dashboard to avoid unexpected charges. See the [Brave API portal](https://brave.com/search/api/) for current plans.
 - The Search plan includes the LLM Context endpoint and AI inference rights. Storing results to train or tune models requires a plan with explicit storage rights. See the Brave [Terms of Service](https://api-dashboard.search.brave.com/terms-of-service).
 - Results are cached for 15 minutes by default (configurable via `cacheTtlMinutes`).

@@ -145,7 +145,7 @@ Configure your tunnel's ingress rules to only route the webhook path:
   - `audienceType: "app-url"` → audience is your HTTPS webhook URL.
   - `audienceType: "project-number"` → audience is the Cloud project number.
 3. Messages are routed by space:
-   - DMs use session key `agent:<agentId>:googlechat:dm:<spaceId>`.
+   - DMs use session key `agent:<agentId>:googlechat:direct:<spaceId>`.
   - Spaces use session key `agent:<agentId>:googlechat:group:<spaceId>`.
 4. DM access is pairing by default. Unknown senders receive a pairing code; approve with:
   - `openclaw pairing approve googlechat <code>`
@@ -195,6 +195,8 @@ Groups:

 - `channels.signal.groupPolicy = open | allowlist | disabled`.
 - `channels.signal.groupAllowFrom` controls who can trigger in groups when `allowlist` is set.
+- `channels.signal.groups["<group-id>" | "*"]` can override group behavior with `requireMention`, `tools`, and `toolsBySender`.
+- Use `channels.signal.accounts.<id>.groups` for per-account overrides in multi-account setups.
 - Runtime note: if `channels.signal` is completely missing, runtime falls back to `groupPolicy="allowlist"` for group checks (even if `channels.defaults.groupPolicy` is set).

 ## How it works (behavior)
@@ -312,6 +314,8 @@ Provider options:
 - `channels.signal.allowFrom`: DM allowlist (E.164 or `uuid:<id>`). `open` requires `"*"`. Signal has no usernames; use phone/UUID ids.
 - `channels.signal.groupPolicy`: `open | allowlist | disabled` (default: allowlist).
 - `channels.signal.groupAllowFrom`: group sender allowlist.
+- `channels.signal.groups`: per-group overrides keyed by Signal group id (or `"*"`). Supported fields: `requireMention`, `tools`, `toolsBySender`.
+- `channels.signal.accounts.<id>.groups`: per-account version of `channels.signal.groups` for multi-account setups.
 - `channels.signal.historyLimit`: max group messages to include as context (0 disables).
 - `channels.signal.dmHistoryLimit`: DM history limit in user turns. Per-user overrides: `channels.signal.dms["<phone_or_uuid>"].historyLimit`.
 - `channels.signal.textChunkLimit`: outbound chunk size (chars).
@@ -218,6 +218,55 @@ For actions/directory reads, user token can be preferred when configured. For wr
  - if encoded option values exceed Slack limits, the flow falls back to buttons
 - For long option payloads, Slash command argument menus use a confirm dialog before dispatching a selected value.

+## Interactive replies
+
+Slack can render agent-authored interactive reply controls, but this feature is disabled by default.
+
+Enable it globally:
+
+```json5
+{
+  channels: {
+    slack: {
+      capabilities: {
+        interactiveReplies: true,
+      },
+    },
+  },
+}
+```
+
+Or enable it for one Slack account only:
+
+```json5
+{
+  channels: {
+    slack: {
+      accounts: {
+        ops: {
+          capabilities: {
+            interactiveReplies: true,
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+When enabled, agents can emit Slack-only reply directives:
+
+- `[[slack_buttons: Approve:approve, Reject:reject]]`
+- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
+
+These directives compile into Slack Block Kit and route clicks or selections back through the existing Slack interaction event path.
+
+Notes:
+
+- This is Slack-specific UI. Other channels do not translate Slack Block Kit directives into their own button systems.
+- The interactive callback values are OpenClaw-generated opaque tokens, not raw agent-authored values.
+- If generated interactive blocks would exceed Slack Block Kit limits, OpenClaw falls back to the original text reply instead of sending an invalid blocks payload.
+
 Default slash command settings:

 - `enabled: false`
@@ -9,32 +9,32 @@ read_when:

 # CI Pipeline

-The CI runs on every push to `main` and every pull request. It uses smart scoping to skip expensive jobs when only docs or native code changed.
+The CI runs on every push to `main` and every pull request. It uses smart scoping to skip expensive jobs when only unrelated areas changed.

 ## Job Overview

-| Job               | Purpose                                                 | When it runs                                      |
-| ----------------- | ------------------------------------------------------- | ------------------------------------------------- |
-| `docs-scope`      | Detect docs-only changes                                | Always                                            |
-| `changed-scope`   | Detect which areas changed (node/macos/android/windows) | Non-docs PRs                                      |
-| `check`           | TypeScript types, lint, format                          | Push to `main`, or PRs with Node-relevant changes |
-| `check-docs`      | Markdown lint + broken link check                       | Docs changed                                      |
-| `code-analysis`   | LOC threshold check (1000 lines)                        | PRs only                                          |
-| `secrets`         | Detect leaked secrets                                   | Always                                            |
-| `build-artifacts` | Build dist once, share with other jobs                  | Non-docs, node changes                            |
-| `release-check`   | Validate npm pack contents                              | After build                                       |
-| `checks`          | Node/Bun tests + protocol check                         | Non-docs, node changes                            |
-| `checks-windows`  | Windows-specific tests                                  | Non-docs, windows-relevant changes                |
-| `macos`           | Swift lint/build/test + TS tests                        | PRs with macos changes                            |
-| `android`         | Gradle build + tests                                    | Non-docs, android changes                         |
+| Job               | Purpose                                                 | When it runs                       |
+| ----------------- | ------------------------------------------------------- | ---------------------------------- |
+| `docs-scope`      | Detect docs-only changes                                | Always                             |
+| `changed-scope`   | Detect which areas changed (node/macos/android/windows) | Non-doc changes                    |
+| `check`           | TypeScript types, lint, format                          | Non-docs, node changes             |
+| `check-docs`      | Markdown lint + broken link check                       | Docs changed                       |
+| `secrets`         | Detect leaked secrets                                   | Always                             |
+| `build-artifacts` | Build dist once, share with `release-check`             | Pushes to `main`, node changes     |
+| `release-check`   | Validate npm pack contents                              | Pushes to `main` after build       |
+| `checks`          | Node tests + protocol check on PRs; Bun compat on push  | Non-docs, node changes             |
+| `compat-node22`   | Minimum supported Node runtime compatibility            | Pushes to `main`, node changes     |
+| `checks-windows`  | Windows-specific tests                                  | Non-docs, windows-relevant changes |
+| `macos`           | Swift lint/build/test + TS tests                        | PRs with macos changes             |
+| `android`         | Gradle build + tests                                    | Non-docs, android changes          |

 ## Fail-Fast Order

 Jobs are ordered so cheap checks fail before expensive ones run:

-1. `docs-scope` + `code-analysis` + `check` (parallel, ~1-2 min)
-2. `build-artifacts` (blocked on above)
-3. `checks`, `checks-windows`, `macos`, `android` (blocked on build)
+1. `docs-scope` + `changed-scope` + `check` + `secrets` (parallel, cheap gates first)
+2. PRs: `checks` (Linux Node test split into 2 shards), `checks-windows`, `macos`, `android`
+3. Pushes to `main`: `build-artifacts` + `release-check` + Bun compat + `compat-node22`

 Scope logic lives in `scripts/ci-changed-scope.mjs` and is covered by unit tests in `src/scripts/ci-changed-scope.test.ts`.

@@ -27,7 +27,7 @@ Related:
 ## Quick start (local)

 ```bash
-openclaw browser --browser-profile chrome tabs
+openclaw browser profiles
 openclaw browser --browser-profile openclaw start
 openclaw browser --browser-profile openclaw open https://example.com
 openclaw browser --browser-profile openclaw snapshot
@@ -38,7 +38,8 @@ openclaw browser --browser-profile openclaw snapshot
 Profiles are named browser routing configs. In practice:

 - `openclaw`: launches/attaches to a dedicated OpenClaw-managed Chrome instance (isolated user data dir).
- `chrome`: controls your existing Chrome tab(s) via the Chrome extension relay.
+- `user`: controls your existing signed-in Chrome session via Chrome DevTools MCP.
+- `chrome-relay`: controls your existing Chrome tab(s) via the Chrome extension relay.

 ```bash
 openclaw browser profiles
@@ -126,6 +126,23 @@ openclaw gateway probe
 openclaw gateway probe --json
 ```

+Interpretation:
+
+- `Reachable: yes` means at least one target accepted a WebSocket connect.
+- `RPC: ok` means detail RPC calls (`health`/`status`/`system-presence`/`config.get`) also succeeded.
+- `RPC: limited - missing scope: operator.read` means connect succeeded but detail RPC is scope-limited. This is reported as **degraded** reachability, not full failure.
+- Exit code is non-zero only when no probed target is reachable.
+
+JSON notes (`--json`):
+
+- Top level:
+  - `ok`: at least one target is reachable.
+  - `degraded`: at least one target had scope-limited detail RPC.
+- Per target (`targets[].connect`):
+  - `ok`: reachability after connect + degraded classification.
+  - `rpcOk`: full detail RPC success.
+  - `scopeLimited`: detail RPC failed due to missing operator scope.
+
 #### Remote over SSH (Mac app parity)

 The macOS app “Remote over SSH” mode uses a local port-forward so the remote gateway (which may be bound to loopback only) becomes reachable at `ws://127.0.0.1:<port>`.
@@ -60,7 +60,7 @@ openclaw sessions cleanup --dry-run
 openclaw sessions cleanup --agent work --dry-run
 openclaw sessions cleanup --all-agents --dry-run
 openclaw sessions cleanup --enforce
-openclaw sessions cleanup --enforce --active-key "agent:main:telegram:dm:123"
+openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123"
 openclaw sessions cleanup --json
 ```

@@ -191,9 +191,9 @@ the workspace is writable. See [Memory](/concepts/memory) and
 - Direct chats follow `session.dmScope` (default `main`).
  - `main`: `agent:<agentId>:<mainKey>` (continuity across devices/channels).
    - Multiple phone numbers and channels can map to the same agent main key; they act as transports into one conversation.
-  - `per-peer`: `agent:<agentId>:dm:<peerId>`.
-  - `per-channel-peer`: `agent:<agentId>:<channel>:dm:<peerId>`.
-  - `per-account-channel-peer`: `agent:<agentId>:<channel>:<accountId>:dm:<peerId>` (accountId defaults to `default`).
+  - `per-peer`: `agent:<agentId>:direct:<peerId>`.
+  - `per-channel-peer`: `agent:<agentId>:<channel>:direct:<peerId>`.
+  - `per-account-channel-peer`: `agent:<agentId>:<channel>:<accountId>:direct:<peerId>` (accountId defaults to `default`).
  - If `session.identityLinks` matches a provider-prefixed peer id (for example `telegram:123`), the canonical key replaces `<peerId>` so the same person shares a session across channels.
 - Group chats isolate state: `agent:<agentId>:<channel>:group:<id>` (rooms/channels use `agent:<agentId>:<channel>:channel:<id>`).
  - Telegram forum topics append `:topic:<threadId>` to the group id for isolation.
@@ -59,7 +59,7 @@ Bootstrap files are trimmed and appended under **Project Context** so the model
 - `USER.md`
 - `HEARTBEAT.md`
 - `BOOTSTRAP.md` (only on brand-new workspaces)
- `MEMORY.md` and/or `memory.md` (when present in the workspace; either or both may be injected)
+- `MEMORY.md` when present, otherwise `memory.md` as a lowercase fallback

 All of these files are **injected into the context window** on every turn, which
 means they consume tokens. Keep them concise — especially `MEMORY.md`, which can
@@ -2342,7 +2342,7 @@ See [Plugins](/tools/plugin).
  browser: {
    enabled: true,
    evaluateEnabled: true,
-    defaultProfile: "chrome",
+    defaultProfile: "user",
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // default trusted-network mode
      // allowPrivateNetwork: true, // legacy alias
@@ -472,7 +472,7 @@ Control-plane write RPCs (`config.apply`, `config.patch`, `update.run`) are rate
    openclaw gateway call config.apply --params '{
      "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
      "baseHash": "<hash>",
-      "sessionKey": "agent:main:whatsapp:dm:+15555550123"
+      "sessionKey": "agent:main:whatsapp:direct:+15555550123"
    }'
    ```

@@ -18,77 +18,16 @@ This endpoint is **disabled by default**. Enable it in config first.
 Under the hood, requests are executed as a normal Gateway agent run (same codepath as
 `openclaw agent`), so routing/permissions/config match your Gateway.

-## Authentication
+## Authentication, security, and routing

-Uses the Gateway auth configuration. Send a bearer token:
+Operational behavior matches [OpenAI Chat Completions](/gateway/openai-http-api):

- `Authorization: Bearer <token>`
+- use `Authorization: Bearer <token>` with the normal Gateway auth config
+- treat the endpoint as full operator access for the gateway instance
+- select agents with `model: "openclaw:<agentId>"`, `model: "agent:<agentId>"`, or `x-openclaw-agent-id`
+- use `x-openclaw-session-key` for explicit session routing

-Notes:
-
- When `gateway.auth.mode="token"`, use `gateway.auth.token` (or `OPENCLAW_GATEWAY_TOKEN`).
- When `gateway.auth.mode="password"`, use `gateway.auth.password` (or `OPENCLAW_GATEWAY_PASSWORD`).
- If `gateway.auth.rateLimit` is configured and too many auth failures occur, the endpoint returns `429` with `Retry-After`.
-
-## Security boundary (important)
-
-Treat this endpoint as a **full operator-access** surface for the gateway instance.
-
- HTTP bearer auth here is not a narrow per-user scope model.
- A valid Gateway token/password for this endpoint should be treated like an owner/operator credential.
- Requests run through the same control-plane agent path as trusted operator actions.
- There is no separate non-owner/per-user tool boundary on this endpoint; once a caller passes Gateway auth here, OpenClaw treats that caller as a trusted operator for this gateway.
- If the target agent policy allows sensitive tools, this endpoint can use them.
- Keep this endpoint on loopback/tailnet/private ingress only; do not expose it directly to the public internet.
-
-See [Security](/gateway/security) and [Remote access](/gateway/remote).
-
-## Choosing an agent
-
-No custom headers required: encode the agent id in the OpenResponses `model` field:
-
- `model: "openclaw:<agentId>"` (example: `"openclaw:main"`, `"openclaw:beta"`)
- `model: "agent:<agentId>"` (alias)
-
-Or target a specific OpenClaw agent by header:
-
- `x-openclaw-agent-id: <agentId>` (default: `main`)
-
-Advanced:
-
- `x-openclaw-session-key: <sessionKey>` to fully control session routing.
-
-## Enabling the endpoint
-
-Set `gateway.http.endpoints.responses.enabled` to `true`:
-
-```json5
-{
-  gateway: {
-    http: {
-      endpoints: {
-        responses: { enabled: true },
-      },
-    },
-  },
-}
-```
-
-## Disabling the endpoint
-
-Set `gateway.http.endpoints.responses.enabled` to `false`:
-
-```json5
-{
-  gateway: {
-    http: {
-      endpoints: {
-        responses: { enabled: false },
-      },
-    },
-  },
-}
-```
+Enable or disable this endpoint with `gateway.http.endpoints.responses.enabled`.

 ## Session behavior

@@ -289,7 +289,7 @@ Look for:

 - Valid browser executable path.
 - CDP profile reachability.
- Extension relay tab attachment for `profile="chrome"`.
+- Extension relay tab attachment for `profile="chrome-relay"`.

 Common signatures:

@@ -53,8 +53,8 @@ Think of the suites as “increasing realism” (and increasing flakiness/cost):
  - No real keys required
  - Should be fast and stable
 - Pool note:
-  - OpenClaw uses Vitest `vmForks` on Node 22/23 for faster unit shards.
-  - On Node 24+, OpenClaw automatically falls back to regular `forks` to avoid Node VM linking errors (`ERR_VM_MODULE_LINK_FAILURE` / `module is already linked`).
+  - OpenClaw uses Vitest `vmForks` on Node 22, 23, and 24 for faster unit shards.
+  - On Node 25+, OpenClaw automatically falls back to regular `forks` until the repo is re-validated there.
  - Override manually with `OPENCLAW_TEST_VM_FORKS=0` (force `forks`) or `OPENCLAW_TEST_VM_FORKS=1` (force `vmForks`).

 ### E2E (gateway smoke)
@@ -28,7 +28,7 @@ Good output in one line:

 - `openclaw status` → shows configured channels and no obvious auth errors.
 - `openclaw status --all` → full report is present and shareable.
- `openclaw gateway probe` → expected gateway target is reachable.
+- `openclaw gateway probe` → expected gateway target is reachable (`Reachable: yes`). `RPC: limited - missing scope: operator.read` is degraded diagnostics, not a connect failure.
 - `openclaw gateway status` → `Runtime: running` and `RPC probe: ok`.
 - `openclaw doctor` → no blocking config/service errors.
 - `openclaw channels status --probe` → channels report `connected` or `ready`.
@@ -0,0 +1,138 @@
+---
+summary: "Shared Docker VM runtime steps for long-lived OpenClaw Gateway hosts"
+read_when:
+  - You are deploying OpenClaw on a cloud VM with Docker
+  - You need the shared binary bake, persistence, and update flow
+title: "Docker VM Runtime"
+---
+
+# Docker VM Runtime
+
+Shared runtime steps for VM-based Docker installs such as GCP, Hetzner, and similar VPS providers.
+
+## Bake required binaries into the image
+
+Installing binaries inside a running container is a trap.
+Anything installed at runtime will be lost on restart.
+
+All external binaries required by skills must be installed at image build time.
+
+The examples below show three common binaries only:
+
+- `gog` for Gmail access
+- `goplaces` for Google Places
+- `wacli` for WhatsApp
+
+These are examples, not a complete list.
+You may install as many binaries as needed using the same pattern.
+
+If you add new skills later that depend on additional binaries, you must:
+
+1. Update the Dockerfile
+2. Rebuild the image
+3. Restart the containers
+
+**Example Dockerfile**
+
+```dockerfile
+FROM node:24-bookworm
+
+RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*
+
+# Example binary 1: Gmail CLI
+RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
+  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog
+
+# Example binary 2: Google Places CLI
+RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \
+  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces
+
+# Example binary 3: WhatsApp CLI
+RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
+  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli
+
+# Add more binaries below using the same pattern
+
+WORKDIR /app
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
+COPY ui/package.json ./ui/package.json
+COPY scripts ./scripts
+
+RUN corepack enable
+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"]
+```
+
+## Build and launch
+
+```bash
+docker compose build
+docker compose up -d openclaw-gateway
+```
+
+If build fails with `Killed` or `exit code 137` during `pnpm install --frozen-lockfile`, the VM is out of memory.
+Use a larger machine class before retrying.
+
+Verify binaries:
+
+```bash
+docker compose exec openclaw-gateway which gog
+docker compose exec openclaw-gateway which goplaces
+docker compose exec openclaw-gateway which wacli
+```
+
+Expected output:
+
+```
+/usr/local/bin/gog
+/usr/local/bin/goplaces
+/usr/local/bin/wacli
+```
+
+Verify Gateway:
+
+```bash
+docker compose logs -f openclaw-gateway
+```
+
+Expected output:
+
+```
+[gateway] listening on ws://0.0.0.0:18789
+```
+
+## What persists where
+
+OpenClaw runs in Docker, but Docker is not the source of truth.
+All long-lived state must survive restarts, rebuilds, and reboots.
+
+| Component           | Location                          | Persistence mechanism  | Notes                            |
+| ------------------- | --------------------------------- | ---------------------- | -------------------------------- |
+| Gateway config      | `/home/node/.openclaw/`           | Host volume mount      | Includes `openclaw.json`, tokens |
+| Model auth profiles | `/home/node/.openclaw/`           | Host volume mount      | OAuth tokens, API keys           |
+| Skill configs       | `/home/node/.openclaw/skills/`    | Host volume mount      | Skill-level state                |
+| Agent workspace     | `/home/node/.openclaw/workspace/` | Host volume mount      | Code and agent artifacts         |
+| WhatsApp session    | `/home/node/.openclaw/`           | Host volume mount      | Preserves QR login               |
+| Gmail keyring       | `/home/node/.openclaw/`           | Host volume + password | Requires `GOG_KEYRING_PASSWORD`  |
+| External binaries   | `/usr/local/bin/`                 | Docker image           | Must be baked at build time      |
+| Node runtime        | Container filesystem              | Docker image           | Rebuilt every image build        |
+| OS packages         | Container filesystem              | Docker image           | Do not install at runtime        |
+| Docker container    | Ephemeral                         | Restartable            | Safe to destroy                  |
+
+## Updates
+
+To update OpenClaw on the VM:
+
+```bash
+git pull
+docker compose build
+docker compose up -d
+```
@@ -281,77 +281,20 @@ services:

 ---

-## 10) Bake required binaries into the image (critical)
+## 10) Shared Docker VM runtime steps

-Installing binaries inside a running container is a trap.
-Anything installed at runtime will be lost on restart.
+Use the shared runtime guide for the common Docker host flow:

-All external binaries required by skills must be installed at image build time.
-
-The examples below show three common binaries only:
-
- `gog` for Gmail access
- `goplaces` for Google Places
- `wacli` for WhatsApp
-
-These are examples, not a complete list.
-You may install as many binaries as needed using the same pattern.
-
-If you add new skills later that depend on additional binaries, you must:
-
-1. Update the Dockerfile
-2. Rebuild the image
-3. Restart the containers
-
-**Example Dockerfile**
-
-```dockerfile
-FROM node:24-bookworm
-
-RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*
-
-# Example binary 1: Gmail CLI
-RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
-  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog
-
-# Example binary 2: Google Places CLI
-RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \
-  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces
-
-# Example binary 3: WhatsApp CLI
-RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
-  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli
-
-# Add more binaries below using the same pattern
-
-WORKDIR /app
-COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
-COPY ui/package.json ./ui/package.json
-COPY scripts ./scripts
-
-RUN corepack enable
-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"]
-```
+- [Bake required binaries into the image](/install/docker-vm-runtime#bake-required-binaries-into-the-image)
+- [Build and launch](/install/docker-vm-runtime#build-and-launch)
+- [What persists where](/install/docker-vm-runtime#what-persists-where)
+- [Updates](/install/docker-vm-runtime#updates)

 ---

-## 11) Build and launch
+## 11) GCP-specific launch notes

-```bash
-docker compose build
-docker compose up -d openclaw-gateway
-```
-
-If build fails with `Killed` / `exit code 137` during `pnpm install --frozen-lockfile`, the VM is out of memory. Use `e2-small` minimum, or `e2-medium` for more reliable first builds.
+On GCP, if build fails with `Killed` or `exit code 137` during `pnpm install --frozen-lockfile`, the VM is out of memory. Use `e2-small` minimum, or `e2-medium` for more reliable first builds.

 When binding to LAN (`OPENCLAW_GATEWAY_BIND=lan`), configure a trusted browser origin before continuing:

@@ -361,39 +304,7 @@ docker compose run --rm openclaw-cli config set gateway.controlUi.allowedOrigins

 If you changed the gateway port, replace `18789` with your configured port.

-Verify binaries:
-
-```bash
-docker compose exec openclaw-gateway which gog
-docker compose exec openclaw-gateway which goplaces
-docker compose exec openclaw-gateway which wacli
-```
-
-Expected output:
-
-```
-/usr/local/bin/gog
-/usr/local/bin/goplaces
-/usr/local/bin/wacli
-```
-
---
-
-## 12) Verify Gateway
-
-```bash
-docker compose logs -f openclaw-gateway
-```
-
-Success:
-
-```
-[gateway] listening on ws://0.0.0.0:18789
-```
-
---
-
-## 13) Access from your laptop
+## 12) Access from your laptop

 Create an SSH tunnel to forward the Gateway port:

@@ -420,38 +331,8 @@ docker compose run --rm openclaw-cli devices list
 docker compose run --rm openclaw-cli devices approve <requestId>
 ```

---
-
-## What persists where (source of truth)
-
-OpenClaw runs in Docker, but Docker is not the source of truth.
-All long-lived state must survive restarts, rebuilds, and reboots.
-
-| Component           | Location                          | Persistence mechanism  | Notes                            |
-| ------------------- | --------------------------------- | ---------------------- | -------------------------------- |
-| Gateway config      | `/home/node/.openclaw/`           | Host volume mount      | Includes `openclaw.json`, tokens |
-| Model auth profiles | `/home/node/.openclaw/`           | Host volume mount      | OAuth tokens, API keys           |
-| Skill configs       | `/home/node/.openclaw/skills/`    | Host volume mount      | Skill-level state                |
-| Agent workspace     | `/home/node/.openclaw/workspace/` | Host volume mount      | Code and agent artifacts         |
-| WhatsApp session    | `/home/node/.openclaw/`           | Host volume mount      | Preserves QR login               |
-| Gmail keyring       | `/home/node/.openclaw/`           | Host volume + password | Requires `GOG_KEYRING_PASSWORD`  |
-| External binaries   | `/usr/local/bin/`                 | Docker image           | Must be baked at build time      |
-| Node runtime        | Container filesystem              | Docker image           | Rebuilt every image build        |
-| OS packages         | Container filesystem              | Docker image           | Do not install at runtime        |
-| Docker container    | Ephemeral                         | Restartable            | Safe to destroy                  |
-
---
-
-## Updates
-
-To update OpenClaw on the VM:
-
-```bash
-cd ~/openclaw
-git pull
-docker compose build
-docker compose up -d
-```
+Need the shared persistence and update reference again?
+See [Docker VM Runtime](/install/docker-vm-runtime#what-persists-where) and [Docker VM Runtime updates](/install/docker-vm-runtime#updates).

 ---

@@ -202,107 +202,20 @@ services:

 ---

-## 7) Bake required binaries into the image (critical)
+## 7) Shared Docker VM runtime steps

-Installing binaries inside a running container is a trap.
-Anything installed at runtime will be lost on restart.
+Use the shared runtime guide for the common Docker host flow:

-All external binaries required by skills must be installed at image build time.
-
-The examples below show three common binaries only:
-
- `gog` for Gmail access
- `goplaces` for Google Places
- `wacli` for WhatsApp
-
-These are examples, not a complete list.
-You may install as many binaries as needed using the same pattern.
-
-If you add new skills later that depend on additional binaries, you must:
-
-1. Update the Dockerfile
-2. Rebuild the image
-3. Restart the containers
-
-**Example Dockerfile**
-
-```dockerfile
-FROM node:24-bookworm
-
-RUN apt-get update && apt-get install -y socat && rm -rf /var/lib/apt/lists/*
-
-# Example binary 1: Gmail CLI
-RUN curl -L https://github.com/steipete/gog/releases/latest/download/gog_Linux_x86_64.tar.gz \
-  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/gog
-
-# Example binary 2: Google Places CLI
-RUN curl -L https://github.com/steipete/goplaces/releases/latest/download/goplaces_Linux_x86_64.tar.gz \
-  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/goplaces
-
-# Example binary 3: WhatsApp CLI
-RUN curl -L https://github.com/steipete/wacli/releases/latest/download/wacli_Linux_x86_64.tar.gz \
-  | tar -xz -C /usr/local/bin && chmod +x /usr/local/bin/wacli
-
-# Add more binaries below using the same pattern
-
-WORKDIR /app
-COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
-COPY ui/package.json ./ui/package.json
-COPY scripts ./scripts
-
-RUN corepack enable
-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"]
-```
+- [Bake required binaries into the image](/install/docker-vm-runtime#bake-required-binaries-into-the-image)
+- [Build and launch](/install/docker-vm-runtime#build-and-launch)
+- [What persists where](/install/docker-vm-runtime#what-persists-where)
+- [Updates](/install/docker-vm-runtime#updates)

 ---

-## 8) Build and launch
+## 8) Hetzner-specific access

-```bash
-docker compose build
-docker compose up -d openclaw-gateway
-```
-
-Verify binaries:
-
-```bash
-docker compose exec openclaw-gateway which gog
-docker compose exec openclaw-gateway which goplaces
-docker compose exec openclaw-gateway which wacli
-```
-
-Expected output:
-
-```
-/usr/local/bin/gog
-/usr/local/bin/goplaces
-/usr/local/bin/wacli
-```
-
---
-
-## 9) Verify Gateway
-
-```bash
-docker compose logs -f openclaw-gateway
-```
-
-Success:
-
-```
-[gateway] listening on ws://0.0.0.0:18789
-```
-
-From your laptop:
+After the shared build and launch steps, tunnel from your laptop:

 ```bash
 ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP
@@ -316,25 +229,7 @@ Paste your gateway token.

 ---

-## What persists where (source of truth)
-
-OpenClaw runs in Docker, but Docker is not the source of truth.
-All long-lived state must survive restarts, rebuilds, and reboots.
-
-| Component           | Location                          | Persistence mechanism  | Notes                            |
-| ------------------- | --------------------------------- | ---------------------- | -------------------------------- |
-| Gateway config      | `/home/node/.openclaw/`           | Host volume mount      | Includes `openclaw.json`, tokens |
-| Model auth profiles | `/home/node/.openclaw/`           | Host volume mount      | OAuth tokens, API keys           |
-| Skill configs       | `/home/node/.openclaw/skills/`    | Host volume mount      | Skill-level state                |
-| Agent workspace     | `/home/node/.openclaw/workspace/` | Host volume mount      | Code and agent artifacts         |
-| WhatsApp session    | `/home/node/.openclaw/`           | Host volume mount      | Preserves QR login               |
-| Gmail keyring       | `/home/node/.openclaw/`           | Host volume + password | Requires `GOG_KEYRING_PASSWORD`  |
-| External binaries   | `/usr/local/bin/`                 | Docker image           | Must be baked at build time      |
-| Node runtime        | Container filesystem              | Docker image           | Rebuilt every image build        |
-| OS packages         | Container filesystem              | Docker image           | Do not install at runtime        |
-| Docker container    | Ephemeral                         | Restartable            | Safe to destroy                  |
-
---
+The shared persistence map lives in [Docker VM Runtime](/install/docker-vm-runtime#what-persists-where).

 ## Infrastructure as Code (Terraform)

@@ -9,6 +9,8 @@ title: "Android App"

 # Android App (Node)

+> **Note:** The Android app has not been publicly released yet. The source code is available in the [OpenClaw repository](https://github.com/openclaw/openclaw) under `apps/android`. You can build it yourself using Java 17 and the Android SDK (`./gradlew :app:assembleDebug`). See [apps/android/README.md](https://github.com/openclaw/openclaw/blob/main/apps/android/README.md) for build instructions.
+
 ## Support snapshot

 - Role: companion node app (Android does not host the Gateway).
@@ -39,7 +39,7 @@ Notes:
 # Default is auto-derived from APP_VERSION when omitted.
 SKIP_NOTARIZE=1 \
 BUNDLE_ID=ai.openclaw.mac \
-APP_VERSION=2026.3.12 \
+APP_VERSION=2026.3.13 \
 BUILD_CONFIG=release \
 SIGN_IDENTITY="Developer ID Application: <Developer Name> (<TEAMID>)" \
 scripts/package-mac-dist.sh
@@ -47,10 +47,10 @@ scripts/package-mac-dist.sh
 # `package-mac-dist.sh` already creates the zip + DMG.
 # If you used `package-mac-app.sh` directly instead, create them manually:
 # If you want notarization/stapling in this step, use the NOTARIZE command below.
-ditto -c -k --sequesterRsrc --keepParent dist/OpenClaw.app dist/OpenClaw-2026.3.12.zip
+ditto -c -k --sequesterRsrc --keepParent dist/OpenClaw.app dist/OpenClaw-2026.3.13.zip

 # Optional: build a styled DMG for humans (drag to /Applications)
-scripts/create-dmg.sh dist/OpenClaw.app dist/OpenClaw-2026.3.12.dmg
+scripts/create-dmg.sh dist/OpenClaw.app dist/OpenClaw-2026.3.13.dmg

 # Recommended: build + notarize/staple zip + DMG
 # First, create a keychain profile once:
@@ -58,13 +58,13 @@ scripts/create-dmg.sh dist/OpenClaw.app dist/OpenClaw-2026.3.12.dmg
 #     --apple-id "<apple-id>" --team-id "<team-id>" --password "<app-specific-password>"
 NOTARIZE=1 NOTARYTOOL_PROFILE=openclaw-notary \
 BUNDLE_ID=ai.openclaw.mac \
-APP_VERSION=2026.3.12 \
+APP_VERSION=2026.3.13 \
 BUILD_CONFIG=release \
 SIGN_IDENTITY="Developer ID Application: <Developer Name> (<TEAMID>)" \
 scripts/package-mac-dist.sh

 # Optional: ship dSYM alongside the release
-ditto -c -k --keepParent apps/macos/.build/release/OpenClaw.app.dSYM dist/OpenClaw-2026.3.12.dSYM.zip
+ditto -c -k --keepParent apps/macos/.build/release/OpenClaw.app.dSYM dist/OpenClaw-2026.3.13.dSYM.zip
 ```

 ## Appcast entry
@@ -72,7 +72,7 @@ ditto -c -k --keepParent apps/macos/.build/release/OpenClaw.app.dSYM dist/OpenCl
 Use the release note generator so Sparkle renders formatted HTML notes:

 ```bash
-SPARKLE_PRIVATE_KEY_FILE=/path/to/ed25519-private-key scripts/make_appcast.sh dist/OpenClaw-2026.3.12.zip https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml
+SPARKLE_PRIVATE_KEY_FILE=/path/to/ed25519-private-key scripts/make_appcast.sh dist/OpenClaw-2026.3.13.zip https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml
 ```

 Generates HTML release notes from `CHANGELOG.md` (via [`scripts/changelog-to-html.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/changelog-to-html.sh)) and embeds them in the appcast entry.
@@ -80,7 +80,7 @@ Commit the updated `appcast.xml` alongside the release assets (zip + dSYM) when

 ## Publish & verify

- Upload `OpenClaw-2026.3.12.zip` (and `OpenClaw-2026.3.12.dSYM.zip`) to the GitHub release for tag `v2026.3.12`.
+- Upload `OpenClaw-2026.3.13.zip` (and `OpenClaw-2026.3.13.dSYM.zip`) to the GitHub release for tag `v2026.3.13`.
 - Ensure the raw appcast URL matches the baked feed: `https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml`.
 - Sanity checks:
  - `curl -I https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml` returns 200.
@@ -41,6 +41,7 @@ Current caveats:
 - `openclaw onboard --non-interactive` still expects a reachable local gateway unless you pass `--skip-health`
 - `openclaw onboard --non-interactive --install-daemon` and `openclaw gateway install` try Windows Scheduled Tasks first
 - if Scheduled Task creation is denied, OpenClaw falls back to a per-user Startup-folder login item and starts the gateway immediately
+- if `schtasks` itself wedges or stops responding, OpenClaw now aborts that path quickly and falls back instead of hanging forever
 - Scheduled Tasks are still preferred when available because they provide better supervisor status

 If you want the native CLI only, without gateway service install, use one of these:
@@ -296,6 +296,12 @@ Inbound policy defaults to `disabled`. To enable inbound calls, set:
 }
 ```

+`inboundPolicy: "allowlist"` is a low-assurance caller-ID screen. The plugin
+normalizes the provider-supplied `From` value and compares it to `allowFrom`.
+Webhook verification authenticates provider delivery and payload integrity, but
+it does not prove PSTN/VoIP caller-number ownership. Treat `allowFrom` as
+caller-ID filtering, not strong caller identity.
+
 Auto-responses use the agent system. Tune with:

 - `responseModel`
@@ -85,8 +85,8 @@ See [Memory](/concepts/memory).
 - **Kimi (Moonshot)**: `KIMI_API_KEY`, `MOONSHOT_API_KEY`, or `tools.web.search.kimi.apiKey`
 - **Perplexity Search API**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY`, or `tools.web.search.perplexity.apiKey`

-**Brave Search free credit:** Each Brave plan includes $5/month in renewing
-free credit. The Search plan costs $5 per 1,000 requests, so the credit covers
+**Brave Search free credit:** Each Brave plan includes \$5/month in renewing
+free credit. The Search plan costs \$5 per 1,000 requests, so the credit covers
 1,000 requests/month at no charge. Set your usage limit in the Brave dashboard
 to avoid unexpected charges.

@@ -11,7 +11,7 @@ title: "Tests"

 - `pnpm test:force`: Kills any lingering gateway process holding the default control port, then runs the full Vitest suite with an isolated gateway port so server tests don’t collide with a running instance. Use this when a prior gateway run left port 18789 occupied.
 - `pnpm test:coverage`: Runs the unit suite with V8 coverage (via `vitest.unit.config.ts`). Global thresholds are 70% lines/branches/functions/statements. Coverage excludes integration-heavy entrypoints (CLI wiring, gateway/telegram bridges, webchat static server) to keep the target focused on unit-testable logic.
- `pnpm test` on Node 24+: OpenClaw auto-disables Vitest `vmForks` and uses `forks` to avoid `ERR_VM_MODULE_LINK_FAILURE` / `module is already linked`. You can force behavior with `OPENCLAW_TEST_VM_FORKS=0|1`.
+- `pnpm test` on Node 22, 23, and 24 uses Vitest `vmForks` by default for faster startup. Node 25+ falls back to `forks` until re-validated. You can force behavior with `OPENCLAW_TEST_VM_FORKS=0|1`.
 - `pnpm test`: runs the fast core unit lane by default for quick local feedback.
 - `pnpm test:channels`: runs channel-heavy suites.
 - `pnpm test:extensions`: runs extension/plugin suites.
@@ -18,7 +18,7 @@ OpenClaw assembles its own system prompt on every run. It includes:
 - Tool list + short descriptions
 - Skills list (only metadata; instructions are loaded on demand with `read`)
 - Self-update instructions
- Workspace + bootstrap files (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` when new, plus `MEMORY.md` and/or `memory.md` when present). Large files are truncated by `agents.defaults.bootstrapMaxChars` (default: 20000), and total bootstrap injection is capped by `agents.defaults.bootstrapTotalMaxChars` (default: 150000). `memory/*.md` files are on-demand via memory tools and are not auto-injected.
+- Workspace + bootstrap files (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md` when new, plus `MEMORY.md` when present or `memory.md` as a lowercase fallback). Large files are truncated by `agents.defaults.bootstrapMaxChars` (default: 20000), and total bootstrap injection is capped by `agents.defaults.bootstrapTotalMaxChars` (default: 150000). `memory/*.md` files are on-demand via memory tools and are not auto-injected.
 - Time (UTC + user timezone)
 - Reply tags + heartbeat behavior
 - Runtime metadata (host/OS/model/thinking)
@@ -167,93 +167,8 @@ openclaw onboard --non-interactive \
 `--json` does **not** imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts.
 </Note>

-<AccordionGroup>
-  <Accordion title="Gemini example">
-    ```bash
-    openclaw onboard --non-interactive \
-      --mode local \
-      --auth-choice gemini-api-key \
-      --gemini-api-key "$GEMINI_API_KEY" \
-      --gateway-port 18789 \
-      --gateway-bind loopback
-    ```
-  </Accordion>
-  <Accordion title="Z.AI example">
-    ```bash
-    openclaw onboard --non-interactive \
-      --mode local \
-      --auth-choice zai-api-key \
-      --zai-api-key "$ZAI_API_KEY" \
-      --gateway-port 18789 \
-      --gateway-bind loopback
-    ```
-  </Accordion>
-  <Accordion title="Vercel AI Gateway example">
-    ```bash
-    openclaw onboard --non-interactive \
-      --mode local \
-      --auth-choice ai-gateway-api-key \
-      --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
-      --gateway-port 18789 \
-      --gateway-bind loopback
-    ```
-  </Accordion>
-  <Accordion title="Cloudflare AI Gateway example">
-    ```bash
-    openclaw onboard --non-interactive \
-      --mode local \
-      --auth-choice cloudflare-ai-gateway-api-key \
-      --cloudflare-ai-gateway-account-id "your-account-id" \
-      --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
-      --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \
-      --gateway-port 18789 \
-      --gateway-bind loopback
-    ```
-  </Accordion>
-  <Accordion title="Moonshot example">
-    ```bash
-    openclaw onboard --non-interactive \
-      --mode local \
-      --auth-choice moonshot-api-key \
-      --moonshot-api-key "$MOONSHOT_API_KEY" \
-      --gateway-port 18789 \
-      --gateway-bind loopback
-    ```
-  </Accordion>
-  <Accordion title="Synthetic example">
-    ```bash
-    openclaw onboard --non-interactive \
-      --mode local \
-      --auth-choice synthetic-api-key \
-      --synthetic-api-key "$SYNTHETIC_API_KEY" \
-      --gateway-port 18789 \
-      --gateway-bind loopback
-    ```
-  </Accordion>
-  <Accordion title="OpenCode example">
-    ```bash
-    openclaw onboard --non-interactive \
-      --mode local \
-      --auth-choice opencode-zen \
-      --opencode-zen-api-key "$OPENCODE_API_KEY" \
-      --gateway-port 18789 \
-      --gateway-bind loopback
-    ```
-    Swap to `--auth-choice opencode-go --opencode-go-api-key "$OPENCODE_API_KEY"` for the Go catalog.
-  </Accordion>
-  <Accordion title="Ollama example">
-    ```bash
-    openclaw onboard --non-interactive \
-      --mode local \
-      --auth-choice ollama \
-      --custom-model-id "qwen3.5:27b" \
-      --accept-risk \
-      --gateway-port 18789 \
-      --gateway-bind loopback
-    ```
-    Add `--custom-base-url "http://ollama-host:11434"` to target a remote Ollama instance.
-  </Accordion>
-</AccordionGroup>
+Provider-specific command examples live in [CLI Automation](/start/wizard-cli-automation#provider-specific-examples).
+Use this reference page for flag semantics and step ordering.

 ### Add agent (non-interactive)

@@ -123,7 +123,7 @@ curl -s http://127.0.0.1:18791/tabs

 ### Problem: "Chrome extension relay is running, but no tab is connected"

-You’re using the `chrome` profile (extension relay). It expects the OpenClaw
+You’re using the `chrome-relay` profile (extension relay). It expects the OpenClaw
 browser extension to be attached to a live tab.

 Fix options:
@@ -135,5 +135,5 @@ Fix options:

 Notes:

- The `chrome` profile uses your **system default Chromium browser** when possible.
+- The `chrome-relay` profile uses your **system default Chromium browser** when possible.
 - Local `openclaw` profiles auto-assign `cdpPort`/`cdpUrl`; only set those for remote CDP.
@@ -20,6 +20,13 @@ Back to the main browser docs: [Browser](/tools/browser).

 OpenClaw controls a **dedicated Chrome profile** (named `openclaw`, orange‑tinted UI). This is separate from your daily browser profile.

+For agent browser tool calls:
+
+- Default choice: the agent should use its isolated `openclaw` browser.
+- Use `profile="user"` only when existing logged-in sessions matter and the user is at the computer to click/approve any attach prompt.
+- Use `profile="chrome-relay"` only for the Chrome extension / toolbar-button attach flow.
+- If you have multiple user-browser profiles, specify the profile explicitly instead of guessing.
+
 Two easy ways to access it:

 1. **Ask the agent to open the browser** and then log in yourself.
@@ -33,7 +33,7 @@ Choose this when:

 ### Option 2: Chrome extension relay

-Use the built-in `chrome` profile plus the OpenClaw Chrome extension.
+Use the built-in `chrome-relay` profile plus the OpenClaw Chrome extension.

 Choose this when:

@@ -155,7 +155,7 @@ Example:
 {
  browser: {
    enabled: true,
-    defaultProfile: "chrome",
+    defaultProfile: "chrome-relay",
    relayBindHost: "0.0.0.0",
  },
 }
@@ -197,7 +197,7 @@ openclaw browser tabs --browser-profile remote
 For the extension relay:

 ```bash
-openclaw browser tabs --browser-profile chrome
+openclaw browser tabs --browser-profile chrome-relay
 ```

 Good result:
@@ -18,8 +18,8 @@ Beginner view:
 - Think of it as a **separate, agent-only browser**.
 - The `openclaw` profile does **not** touch your personal browser profile.
 - The agent can **open tabs, read pages, click, and type** in a safe lane.
- The default `chrome` profile uses the **system default Chromium browser** via the
-  extension relay; switch to `openclaw` for the isolated managed browser.
+- The built-in `user` profile attaches to your real signed-in Chrome session;
+  `chrome-relay` is the explicit extension-relay profile.

 ## What you get

@@ -43,11 +43,22 @@ openclaw browser --browser-profile openclaw snapshot
 If you get “Browser disabled”, enable it in config (see below) and restart the
 Gateway.

-## Profiles: `openclaw` vs `chrome`
+## Profiles: `openclaw` vs `user` vs `chrome-relay`

 - `openclaw`: managed, isolated browser (no extension required).
- `chrome`: extension relay to your **system browser** (requires the OpenClaw
-  extension to be attached to a tab).
+- `user`: built-in Chrome MCP attach profile for your **real signed-in Chrome**
+  session.
+- `chrome-relay`: extension relay to your **system browser** (requires the
+  OpenClaw extension to be attached to a tab).
+
+For agent browser tool calls:
+
+- Default: use the isolated `openclaw` browser.
+- Prefer `profile="user"` when existing logged-in sessions matter and the user
+  is at the computer to click/approve any attach prompt.
+- Use `profile="chrome-relay"` only when the user explicitly wants the Chrome
+  extension / toolbar-button attach flow.
+- `profile` is the explicit override when you want a specific browser mode.

 Set `browser.defaultProfile: "openclaw"` if you want managed mode by default.

@@ -68,7 +79,7 @@ Browser settings live in `~/.openclaw/openclaw.json`.
    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
-    defaultProfile: "chrome",
+    defaultProfile: "openclaw",
    color: "#FF4500",
    headless: false,
    noSandbox: false,
@@ -77,6 +88,16 @@ Browser settings live in `~/.openclaw/openclaw.json`.
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
+      user: {
+        driver: "existing-session",
+        attachOnly: true,
+        color: "#00AA00",
+      },
+      "chrome-relay": {
+        driver: "extension",
+        cdpUrl: "http://127.0.0.1:18792",
+        color: "#00AA00",
+      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
@@ -97,9 +118,11 @@ Notes:
 - `browser.ssrfPolicy.allowPrivateNetwork` remains supported as a legacy alias for compatibility.
 - `attachOnly: true` means “never launch a local browser; only attach if it is already running.”
 - `color` + per-profile `color` tint the browser UI so you can see which profile is active.
- Default profile is `openclaw` (OpenClaw-managed standalone browser). Use `defaultProfile: "chrome"` to opt into the Chrome extension relay.
+- Default profile is `openclaw` (OpenClaw-managed standalone browser). Use `defaultProfile: "user"` to opt into the signed-in user browser, or `defaultProfile: "chrome-relay"` for the extension relay.
 - Auto-detect order: system default browser if Chromium-based; otherwise Chrome → Brave → Edge → Chromium → Chrome Canary.
 - Local `openclaw` profiles auto-assign `cdpPort`/`cdpUrl` — set those only for remote CDP.
+- `driver: "existing-session"` uses Chrome DevTools MCP instead of raw CDP. Do
+  not set `cdpUrl` for that driver.

 ## Use Brave (or another Chromium-based browser)

@@ -264,11 +287,13 @@ OpenClaw supports multiple named profiles (routing configs). Profiles can be:
 - **openclaw-managed**: a dedicated Chromium-based browser instance with its own user data directory + CDP port
 - **remote**: an explicit CDP URL (Chromium-based browser running elsewhere)
 - **extension relay**: your existing Chrome tab(s) via the local relay + Chrome extension
+- **existing session**: your existing Chrome profile via Chrome DevTools MCP auto-connect

 Defaults:

 - The `openclaw` profile is auto-created if missing.
- The `chrome` profile is built-in for the Chrome extension relay (points at `http://127.0.0.1:18792` by default).
+- The `chrome-relay` profile is built-in for the Chrome extension relay (points at `http://127.0.0.1:18792` by default).
+- Existing-session profiles are opt-in; create them with `--driver existing-session`.
 - Local CDP ports allocate from **18800–18899** by default.
 - Deleting a profile moves its local data directory to Trash.

@@ -311,8 +336,8 @@ openclaw browser extension install

 2. Use it:

- CLI: `openclaw browser --browser-profile chrome tabs`
- Agent tool: `browser` with `profile="chrome"`
+- CLI: `openclaw browser --browser-profile chrome-relay tabs`
+- Agent tool: `browser` with `profile="chrome-relay"`

 Optional: if you want a different name or relay port, create your own profile:

@@ -328,6 +353,81 @@ Notes:

 - This mode relies on Playwright-on-CDP for most operations (screenshots/snapshots/actions).
 - Detach by clicking the extension icon again.
+- Agent use: prefer `profile="user"` for logged-in sites. Use `profile="chrome-relay"`
+  only when you specifically want the extension flow. The user must be present
+  to click the extension and attach the tab.
+
+## Chrome existing-session via MCP
+
+OpenClaw can also attach to a running Chrome profile through the official
+Chrome DevTools MCP server. This reuses the tabs and login state already open in
+that Chrome profile.
+
+Official background and setup references:
+
+- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
+- [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp)
+
+Built-in profile:
+
+- `user`
+
+Optional: create your own custom existing-session profile if you want a
+different name or color.
+
+Then in Chrome:
+
+1. Open `chrome://inspect/#remote-debugging`
+2. Enable remote debugging
+3. Keep Chrome running and approve the connection prompt when OpenClaw attaches
+
+Live attach smoke test:
+
+```bash
+openclaw browser --browser-profile user start
+openclaw browser --browser-profile user status
+openclaw browser --browser-profile user tabs
+openclaw browser --browser-profile user snapshot --format ai
+```
+
+What success looks like:
+
+- `status` shows `driver: existing-session`
+- `status` shows `transport: chrome-mcp`
+- `status` shows `running: true`
+- `tabs` lists your already-open Chrome tabs
+- `snapshot` returns refs from the selected live tab
+
+What to check if attach does not work:
+
+- Chrome is version `144+`
+- remote debugging is enabled at `chrome://inspect/#remote-debugging`
+- Chrome showed and you accepted the attach consent prompt
+
+Agent use:
+
+- Use `profile="user"` when you need the user’s logged-in browser state.
+- If you use a custom existing-session profile, pass that explicit profile name.
+- Prefer `profile="user"` over `profile="chrome-relay"` unless the user
+  explicitly wants the extension / attach-tab flow.
+- Only choose this mode when the user is at the computer to approve the attach
+  prompt.
+- the Gateway or node host can spawn `npx chrome-devtools-mcp@latest --autoConnect`
+
+Notes:
+
+- This path is higher-risk than the isolated `openclaw` profile because it can
+  act inside your signed-in browser session.
+- OpenClaw does not launch Chrome for this driver; it attaches to an existing
+  session only.
+- OpenClaw uses the official Chrome DevTools MCP `--autoConnect` flow here, not
+  the legacy default-profile remote debugging port workflow.
+- Existing-session screenshots support page captures and `--ref` element
+  captures from snapshots, but not CSS `--element` selectors.
+- Existing-session `wait --url` supports exact, substring, and glob patterns
+  like other browser drivers. `wait --load networkidle` is not supported yet.
+- Some features still require the extension relay or managed browser path, such
+  as PDF export and download interception.
 - Leave the relay loopback-only by default. If the relay must be reachable from a different network namespace (for example Gateway in WSL2, Chrome on Windows), set `browser.relayBindHost` to an explicit bind address such as `0.0.0.0` while keeping the surrounding network private and authenticated.

 WSL2 / cross-namespace example:
@@ -337,7 +437,7 @@ WSL2 / cross-namespace example:
  browser: {
    enabled: true,
    relayBindHost: "0.0.0.0",
-    defaultProfile: "chrome",
+    defaultProfile: "chrome-relay",
  },
 }
 ```
@@ -13,6 +13,13 @@ The OpenClaw Chrome extension lets the agent control your **existing Chrome tabs

 Attach/detach happens via a **single Chrome toolbar button**.

+If you want Chrome’s official DevTools MCP attach flow instead of the OpenClaw
+extension relay, use an `existing-session` browser profile instead. See
+[Browser](/tools/browser#chrome-existing-session-via-mcp). For Chrome’s own
+setup docs, see [Chrome for Developers: Use Chrome DevTools MCP with your
+browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
+and the [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp).
+
 ## What it is (concept)

 There are three parts:
@@ -55,7 +62,7 @@ After upgrading OpenClaw:

 ## Use it (set gateway token once)

-OpenClaw ships with a built-in browser profile named `chrome` that targets the extension relay on the default port.
+OpenClaw ships with a built-in browser profile named `chrome-relay` that targets the extension relay on the default port.

 Before first attach, open extension Options and set:

@@ -64,8 +71,8 @@ Before first attach, open extension Options and set:

 Use it:

- CLI: `openclaw browser --browser-profile chrome tabs`
- Agent tool: `browser` with `profile="chrome"`
+- CLI: `openclaw browser --browser-profile chrome-relay tabs`
+- Agent tool: `browser` with `profile="chrome-relay"`

 If you want a different name or a different relay port, create your own profile:

@@ -271,6 +271,8 @@ Approval-backed interpreter/runtime runs are intentionally conservative:
 - Exact argv/cwd/env context is always bound.
 - Direct shell script and direct runtime file forms are best-effort bound to one concrete local
  file snapshot.
+- Common package-manager wrapper forms that still resolve to one direct local file (for example
+  `pnpm exec`, `pnpm node`, `npm exec`, `npx`) are unwrapped before binding.
 - If OpenClaw cannot identify exactly one concrete local file for an interpreter/runtime command
  (for example package scripts, eval forms, runtime-specific loader chains, or ambiguous multi-file
  forms), approval-backed execution is denied instead of claiming semantic coverage it does not
@@ -316,7 +316,11 @@ Common parameters:
  Notes:
 - Requires `browser.enabled=true` (default is `true`; set `false` to disable).
 - All actions accept optional `profile` parameter for multi-instance support.
- When `profile` is omitted, uses `browser.defaultProfile` (defaults to "chrome").
+- Omit `profile` for the safe default: isolated OpenClaw-managed browser (`openclaw`).
+- Use `profile="user"` for the real local host browser when existing logins/cookies matter and the user is present to click/approve any attach prompt.
+- Use `profile="chrome-relay"` only for the Chrome extension / toolbar-button attach flow.
+- `profile="user"` and `profile="chrome-relay"` are host-only; do not combine them with sandbox/node targets.
+- When `profile` is omitted, uses `browser.defaultProfile` (defaults to `openclaw`).
 - Profile names: lowercase alphanumeric + hyphens only (max 64 chars).
 - Port range: 18800-18899 (~100 profiles max).
 - Remote profiles are attach-only (no start/stop/reset).
@@ -85,6 +85,13 @@ Implications:
 Use allowlists and explicit install/load paths for non-bundled plugins. Treat
 workspace plugins as development-time code, not production defaults.

+Important trust note:
+
+- `plugins.allow` trusts **plugin ids**, not source provenance.
+- A workspace plugin with the same id as a bundled plugin intentionally shadows
+  the bundled copy when that workspace plugin is enabled/allowlisted.
+- This is normal and useful for local development, patch testing, and hotfixes.
+
 ## Available plugins (official)

 - Microsoft Teams is plugin-only as of 2026.1.15; install `@openclaw/msteams` if you use Teams.
@@ -363,6 +370,14 @@ manifest.
 If multiple plugins resolve to the same id, the first match in the order above
 wins and lower-precedence copies are ignored.

+That means:
+
+- workspace plugins intentionally shadow bundled plugins with the same id
+- `plugins.allow: ["foo"]` authorizes the active `foo` plugin by id, even when
+  the active copy comes from the workspace instead of the bundled extension root
+- if you need stricter provenance control, use explicit install/load paths and
+  inspect the resolved plugin source before enabling it
+
 ### Enablement rules

 Enablement is resolved after discovery:
@@ -372,6 +387,7 @@ Enablement is resolved after discovery:
 - `plugins.entries.<id>.enabled: false` disables that plugin
 - workspace-origin plugins are disabled by default
 - allowlists restrict the active set when `plugins.allow` is non-empty
+- allowlists are **id-based**, not source-based
 - bundled plugins are disabled by default unless:
  - the bundled id is in the built-in default-on set, or
  - you explicitly enable it, or
@@ -1322,6 +1338,8 @@ Plugins run in-process with the Gateway. Treat them as trusted code:

 - Only install plugins you trust.
 - Prefer `plugins.allow` allowlists.
+- Remember that `plugins.allow` is id-based, so an enabled workspace plugin can
+  intentionally shadow a bundled plugin with the same id.
 - Restart the Gateway after changes.

 ## Testing plugins
@@ -65,8 +65,8 @@ Use `openclaw configure --section web` to set up your API key and choose a provi
 2. In the dashboard, choose the **Search** plan and generate an API key.
 3. Run `openclaw configure --section web` to store the key in config, or set `BRAVE_API_KEY` in your environment.

-Each Brave plan includes **$5/month in free credit** (renewing). The Search
-plan costs $5 per 1,000 requests, so the credit covers 1,000 queries/month. Set
+Each Brave plan includes **\$5/month in free credit** (renewing). The Search
+plan costs \$5 per 1,000 requests, so the credit covers 1,000 queries/month. Set
 your usage limit in the Brave dashboard to avoid unexpected charges. See the
 [Brave API portal](https://brave.com/search/api/) for current plans and
 pricing.
@@ -1,6 +1,6 @@
 {
  "name": "@openclaw/acpx",
-  "version": "2026.3.12",
+  "version": "2026.3.13",
  "description": "OpenClaw ACP runtime backend via acpx",
  "type": "module",
  "dependencies": {
@@ -54,6 +54,49 @@ describe("acpx ensure", () => {
    }
  });

+  function mockEnsureInstallFlow() {
+    spawnAndCollectMock
+      .mockResolvedValueOnce({
+        stdout: "acpx 0.0.9\n",
+        stderr: "",
+        code: 0,
+        error: null,
+      })
+      .mockResolvedValueOnce({
+        stdout: "added 1 package\n",
+        stderr: "",
+        code: 0,
+        error: null,
+      })
+      .mockResolvedValueOnce({
+        stdout: `acpx ${ACPX_PINNED_VERSION}\n`,
+        stderr: "",
+        code: 0,
+        error: null,
+      });
+  }
+
+  function expectEnsureInstallCalls(stripProviderAuthEnvVars?: boolean) {
+    expect(spawnAndCollectMock.mock.calls[0]?.[0]).toMatchObject({
+      command: "/plugin/node_modules/.bin/acpx",
+      args: ["--version"],
+      cwd: "/plugin",
+      stripProviderAuthEnvVars,
+    });
+    expect(spawnAndCollectMock.mock.calls[1]?.[0]).toMatchObject({
+      command: "npm",
+      args: ["install", "--omit=dev", "--no-save", `acpx@${ACPX_PINNED_VERSION}`],
+      cwd: "/plugin",
+      stripProviderAuthEnvVars,
+    });
+    expect(spawnAndCollectMock.mock.calls[2]?.[0]).toMatchObject({
+      command: "/plugin/node_modules/.bin/acpx",
+      args: ["--version"],
+      cwd: "/plugin",
+      stripProviderAuthEnvVars,
+    });
+  }
+
  it("accepts the pinned acpx version", async () => {
    spawnAndCollectMock.mockResolvedValueOnce({
      stdout: `acpx ${ACPX_PINNED_VERSION}\n`,
@@ -177,25 +220,7 @@ describe("acpx ensure", () => {
  });

  it("installs and verifies pinned acpx when precheck fails", async () => {
-    spawnAndCollectMock
-      .mockResolvedValueOnce({
-        stdout: "acpx 0.0.9\n",
-        stderr: "",
-        code: 0,
-        error: null,
-      })
-      .mockResolvedValueOnce({
-        stdout: "added 1 package\n",
-        stderr: "",
-        code: 0,
-        error: null,
-      })
-      .mockResolvedValueOnce({
-        stdout: `acpx ${ACPX_PINNED_VERSION}\n`,
-        stderr: "",
-        code: 0,
-        error: null,
-      });
+    mockEnsureInstallFlow();

    await ensureAcpx({
      command: "/plugin/node_modules/.bin/acpx",
@@ -204,33 +229,11 @@ describe("acpx ensure", () => {
    });

    expect(spawnAndCollectMock).toHaveBeenCalledTimes(3);
-    expect(spawnAndCollectMock.mock.calls[1]?.[0]).toMatchObject({
-      command: "npm",
-      args: ["install", "--omit=dev", "--no-save", `acpx@${ACPX_PINNED_VERSION}`],
-      cwd: "/plugin",
-    });
+    expectEnsureInstallCalls();
  });

  it("threads stripProviderAuthEnvVars through version probes and install", async () => {
-    spawnAndCollectMock
-      .mockResolvedValueOnce({
-        stdout: "acpx 0.0.9\n",
-        stderr: "",
-        code: 0,
-        error: null,
-      })
-      .mockResolvedValueOnce({
-        stdout: "added 1 package\n",
-        stderr: "",
-        code: 0,
-        error: null,
-      })
-      .mockResolvedValueOnce({
-        stdout: `acpx ${ACPX_PINNED_VERSION}\n`,
-        stderr: "",
-        code: 0,
-        error: null,
-      });
+    mockEnsureInstallFlow();

    await ensureAcpx({
      command: "/plugin/node_modules/.bin/acpx",
@@ -239,24 +242,7 @@ describe("acpx ensure", () => {
      stripProviderAuthEnvVars: true,
    });

-    expect(spawnAndCollectMock.mock.calls[0]?.[0]).toMatchObject({
-      command: "/plugin/node_modules/.bin/acpx",
-      args: ["--version"],
-      cwd: "/plugin",
-      stripProviderAuthEnvVars: true,
-    });
-    expect(spawnAndCollectMock.mock.calls[1]?.[0]).toMatchObject({
-      command: "npm",
-      args: ["install", "--omit=dev", "--no-save", `acpx@${ACPX_PINNED_VERSION}`],
-      cwd: "/plugin",
-      stripProviderAuthEnvVars: true,
-    });
-    expect(spawnAndCollectMock.mock.calls[2]?.[0]).toMatchObject({
-      command: "/plugin/node_modules/.bin/acpx",
-      args: ["--version"],
-      cwd: "/plugin",
-      stripProviderAuthEnvVars: true,
-    });
+    expectEnsureInstallCalls(true);
  });

  it("fails with actionable error when npm install fails", async () => {
@@ -162,6 +162,39 @@ function resolveTextChunk(params: {
  };
 }

+function createTextDeltaEvent(params: {
+  content: string | null | undefined;
+  stream: "output" | "thought";
+  tag?: AcpSessionUpdateTag;
+}): AcpRuntimeEvent | null {
+  if (params.content == null || params.content.length === 0) {
+    return null;
+  }
+  return {
+    type: "text_delta",
+    text: params.content,
+    stream: params.stream,
+    ...(params.tag ? { tag: params.tag } : {}),
+  };
+}
+
+function createToolCallEvent(params: {
+  payload: Record<string, unknown>;
+  tag: AcpSessionUpdateTag;
+}): AcpRuntimeEvent {
+  const title = asTrimmedString(params.payload.title) || "tool call";
+  const status = asTrimmedString(params.payload.status);
+  const toolCallId = asOptionalString(params.payload.toolCallId);
+  return {
+    type: "tool_call",
+    text: status ? `${title} (${status})` : title,
+    tag: params.tag,
+    ...(toolCallId ? { toolCallId } : {}),
+    ...(status ? { status } : {}),
+    title,
+  };
+}
+
 export function parsePromptEventLine(line: string): AcpRuntimeEvent | null {
  const trimmed = line.trim();
  if (!trimmed) {
@@ -187,57 +220,28 @@ export function parsePromptEventLine(line: string): AcpRuntimeEvent | null {
  const tag = structured.tag;

  switch (type) {
-    case "text": {
-      const content = asString(payload.content);
-      if (content == null || content.length === 0) {
-        return null;
-      }
-      return {
-        type: "text_delta",
-        text: content,
+    case "text":
+      return createTextDeltaEvent({
+        content: asString(payload.content),
        stream: "output",
-        ...(tag ? { tag } : {}),
-      };
-    }
-    case "thought": {
-      const content = asString(payload.content);
-      if (content == null || content.length === 0) {
-        return null;
-      }
-      return {
-        type: "text_delta",
-        text: content,
+        tag,
+      });
+    case "thought":
+      return createTextDeltaEvent({
+        content: asString(payload.content),
        stream: "thought",
-        ...(tag ? { tag } : {}),
-      };
-    }
-    case "tool_call": {
-      const title = asTrimmedString(payload.title) || "tool call";
-      const status = asTrimmedString(payload.status);
-      const toolCallId = asOptionalString(payload.toolCallId);
-      return {
-        type: "tool_call",
-        text: status ? `${title} (${status})` : title,
+        tag,
+      });
+    case "tool_call":
+      return createToolCallEvent({
+        payload,
        tag: (tag ?? "tool_call") as AcpSessionUpdateTag,
-        ...(toolCallId ? { toolCallId } : {}),
-        ...(status ? { status } : {}),
-        title,
-      };
-    }
-    case "tool_call_update": {
-      const title = asTrimmedString(payload.title) || "tool call";
-      const status = asTrimmedString(payload.status);
-      const toolCallId = asOptionalString(payload.toolCallId);
-      const text = status ? `${title} (${status})` : title;
-      return {
-        type: "tool_call",
-        text,
+      });
+    case "tool_call_update":
+      return createToolCallEvent({
+        payload,
        tag: (tag ?? "tool_call_update") as AcpSessionUpdateTag,
-        ...(toolCallId ? { toolCallId } : {}),
-        ...(status ? { status } : {}),
-        title,
-      };
-    }
+      });
    case "agent_message_chunk":
      return resolveTextChunk({
        payload,
--- a/Show More
+++ b/Show More
				`@@ -0,0 +1 @@`
				- tests: align OpenAI Codex auth login expectations with the `gpt-5.4` default model to prevent stale CI failures. (#44367) thanks @jrrcdev